5240lab 적용 근거

본 환경에는 기능 개발 시 활용할 수 있는 절차가 `feature-workflow`로 정의되어 있다. 이 절차는 **요구사항을 먼저 명세로 확정한 뒤(spec-kit), 정해진 작업 규율에 따라 구현하는(Superpowers)** 방식을 하나의 흐름으로 연결한다. "○○ 기능 개발해줘"와 같이 요청하면 적용된다. 실험 목적에 따라 단계를 조정하여 활용한다.

- **spec-kit** — 개발 대상을 정의한다. 요구사항, 기술 계획, 작업 목록 문서를 산출한다.
- **Superpowers** — 작업 방식을 관리한다. 착수 전 설계 검토(브레인스토밍)와 구현 단계의 테스트·검증 절차를 담당한다.

spec-kit이 설계 문서를, Superpowers가 작업 규율을 담당하며, 두 영역은 아래 단일 절차로 연결된다.

| 단계 | 내용 |
|---|---|
| 1. 설계 검토 | 요구사항을 정리하고 2~3개 방안을 비교하여 방향을 확정 |
| 2. 명세 작성 | 확정된 방향을 요구사항·계획·작업 목록 문서로 작성 (spec-kit) |
| 3. 구현 | 작업 목록에 따라 구현하며, 테스트 선작성 및 단계별 검증 적용 |

1. `/speckit.constitution` — 프로젝트 기본 원칙 정의 (최초 1회)
2. `/speckit.specify` — 요구사항 정의
3. `/speckit.clarify` — 모호한 항목 확정
4. `/speckit.plan` — 기술 구성 및 구현 방식 결정
5. `/speckit.tasks` — 작업 단위 분해
6. `/speckit.implement` — 구현 실행

1. Do not add a per-project PostgreSQL container unless the user explicitly asks for an isolated database server.
2. Use the shared container named `shared-postgres`.
3. Create one database and one database user per project.
4. Use `infra/shared-postgres/scripts/create-project-db.sh <project-name>` before wiring a new project to PostgreSQL.

7. Never commit `infra/shared-postgres/.env` or project `.env` files containing database passwords.

### I. Preserve repository boundaries

Each application directory is an independent change scope. Never stage or alter unrelated sibling application data.

### III. Test observable behavior first

Update or add a failing regression assertion before implementation, then run the smallest relevant test and the broader available suite when practical.

✔ urlVariants: 인코딩/비인코딩 표기를 모두 낸다 (0.259962ms)
✔ extractInternalLinks: 내부 앵커만 추출, 해시는 비교 키에서 제거 (3.85115ms)
✔ replaceHref: href 문자열만 바꾸고 앵커 텍스트는 보존 (1.086679ms)
✔ unlinkHref: 해당 href의 a 태그를 안쪽 텍스트만 남기고 해제 (0.328292ms)

ℹ tests 6
ℹ suites 0
ℹ pass 6
ℹ fail 0

Task 2: complete (commit 8dcaa8e, review clean)
  - Minor(최종리뷰 참고): buildRelatedBlock href에 it.url 미이스케이프(내부 생성 URL만 쓰므로 저위험)
Task 3: complete (commit 4cac08d, review clean; 플랜 Step5 검증버그 fb55a3f로 문서수정)
  - Minor(최종리뷰 참고): lib.mjs 관련블록 href 미이스케이프(내부 생성 URL, links-lib와 동일 관행)
Task 4: complete (commit f078fad, review clean; 라이브 스캔: 정상78/리다이렉트8/오류0, 리다이렉트 8건은 전부 Elementor 페이지 출처)

  if (!/^(select|with)\b/i.test(normalized)) {
    throw new Error("Only SELECT or WITH read-only queries are allowed.");
  }
  if (/\bfor\s+update\b/i.test(normalized)) {
    throw new Error("SELECT ... FOR UPDATE is not allowed.");
  }
  if (FORBIDDEN_SQL_PATTERN.test(normalized)) {
    throw new Error("SQL contains a forbidden data-changing or administrative keyword.");

PROJECT_RAW="$1"
PROJECT_SLUG="$(printf '%s' "$PROJECT_RAW" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/_/g; s/^_+//; s/_+$//')"

if [[ -z "$PROJECT_SLUG" ]]; then
  echo "Project name must contain at least one letter or number." >&2
  exit 1
fi

[[ "$gitlink_mode" == "160000" ]] || fail "$SUBMODULE_REL is not a gitlink"
[[ -d "$SUBMODULE_PATH" ]] || fail "submodule directory is not initialized"

submodule_root="$(git -C "$SUBMODULE_PATH" rev-parse --show-toplevel 2>/dev/null || true)"
[[ "$submodule_root" == "$SUBMODULE_PATH" ]] || \
  fail "$SUBMODULE_REL is not an independent Git worktree"

### III. 테스트 우선과 회귀 방지 (NON-NEGOTIABLE)

행동 변경은 실패하는 자동화 테스트를 먼저 작성하고 RED → GREEN → REFACTOR
순서로 구현해야 한다. 순수 로직은 단위 테스트로, 컴포넌트 계약과 사용자 흐름은
통합 또는 렌더 테스트로 검증한다. 관련 테스트와 기존 사이트 검사, 린트,
프로덕션 빌드가 모두 통과하기 전에는 구현 완료로 간주하지 않는다.

수정 후 재검증:
- `node --env-file=app/.env.local scripts/render-check.mjs` → `docs=88 errors=0 rawDirectives=0 h1=88/88 anchors=27/27` (회귀 없음)
- `npm run build` 성공 → `systemctl restart insapien-docs` → `node --env-file=app/.env.local scripts/parity-check.mjs` → **`88/88 parity ok`**

당신은 독립 감사자다. 작성자를 신뢰하지 말고 소스와 대조하라. **이관본 문서를 수정하지 마라** — 발견만 하고 보고서에 기록한다(수정 반영은 별도 단계).

## 검사 A — 미근거/모순 (이관본 → 소스)
이관본의 실질 주장(화면 동작·권한·절차·경고·FAQ 답·차단 규칙·자동 동작)을 정본·리버스 spec과 대조:
- **미근거**: 어느 소스에도 없음 — 문장 인용 + 심각도(high: 틀리면 사용자 실수·사고 / medium: 오해 소지 / low: 무해)
- **모순**: 소스와 반대 — 문장 인용 + 소스의 실제 서술 + 위치
- 일반적 UI 상식("조회를 누릅니다")은 통과. 구체 규칙 주장("~인 경우에만", "~하면 차단")은 반드시 근거 확인.

# 리버스 반영 운영 런북 (감지 확정판, 2026-08-09)

사용자 확정 절차: 새 스펙 전달 → 기준본 비교·감지 → 문서 매핑 → 제안문 등록 → **관리자가 비교 화면에서 반영/보류 결정**. 이 문서는 그중 Claude 세션이 수행하는 감지~등록 단계의 실행 절차다.

0. **자동 감시** — `scripts/reverse-watch.mjs`(systemd `insapien-docs-reverse-watch.timer`, 매일 03:30 KST)가 스펙 저장소를 기준본과 비교. 변경·신규 발견 시 인박스 자동 반입+기계 감지 보고서 생성+`app_settings.reverse_watch_status` 기록 → 관리자 홈 카드·/manage/reverse 패널에 "⚠ 스펙 변경 감지" 표시. **사람이 배포를 기억할 필요 없음.**

echo "[deploy] npm run build"
(cd "$ROOT_DIR/app" && npm run build)

echo "[deploy] systemctl restart insapien-docs"
sudo systemctl restart insapien-docs

echo "[deploy] systemctl is-active insapien-docs"
sudo systemctl is-active insapien-docs