@uzysjung/agent-harness 26.106.0 → 26.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uzysjung/agent-harness",
-  "version": "26.106.0",
+  "version": "26.107.0",
   "description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
   "type": "module",
   "publishConfig": {

package/templates/hooks/spec-drift-check.sh

@@ -1,12 +1,13 @@
 #!/bin/bash
 # spec-drift-check.sh
-# SPEC.md/todo.md/PRD.md의 drift를 검출한다.
-# Verify 또는 Ship 단계에서 호출 가능.
+# SPEC/TODO 문서의 drift를 검출한다. Verify 또는 Ship 단계에서 호출 가능.
 #
 # 검출 항목:
-#  1. SPEC.md의 Verification Checklist에 unchecked 항목 존재
-#  2. todo.md의 unchecked 항목 존재
-#  3. PRD.md Status가 In Progress인데 모든 Phase가 Complete인 경우
+#  1. SPEC 문서에 unchecked 항목 존재 (docs/SPEC.md → SPEC.md 중 첫 존재 파일)
+#  2. TODO 문서에 unchecked 항목 존재 (docs/todo.md → docs/TODO.md → todo.md → TODO.md
+#     → tasks/todo.md 중 첫 존재 파일 — first-match 라 대소문자 무시 FS 에서도 이중 카운트 없음)
+#  3. SPEC Status가 "Define"인데 build/verify gate가 완료된 경우 (gate-status.json 존재 시)
+#  4. Ship 단계에서는 모든 unchecked가 차단
 #
 # Exit codes:
 #  0: drift 없음
@@ -26,40 +27,74 @@ count_unchecked() {
   grep -c "^- \[ \]\|^  - \[ \]" "$file" 2>/dev/null | tail -1 | tr -d ' \n'
 }
 
-# 1. SPEC.md unchecked 검사
-if [ -f "$DOCS_DIR/SPEC.md" ]; then
-  UNCHECKED=$(count_unchecked "$DOCS_DIR/SPEC.md")
+# 후보 목록 중 첫 존재 파일 (없으면 빈 문자열). v26.107.0 — docs/ 고정이던 탐지를
+# 실제 워크플로 산출 레이아웃(root SPEC.md·tasks/todo.md 등)까지 확장 (SOD 리뷰 I-3).
+first_existing() {
+  local f
+  for f in "$@"; do
+    if [ -f "$f" ]; then
+      echo "$f"
+      return 0
+    fi
+  done
+  echo ""
+}
+
+SPEC_FILE=$(first_existing "$DOCS_DIR/SPEC.md" "$PROJECT_DIR/SPEC.md")
+TODO_FILE=$(first_existing "$DOCS_DIR/todo.md" "$DOCS_DIR/TODO.md" "$PROJECT_DIR/todo.md" \
+  "$PROJECT_DIR/TODO.md" "$PROJECT_DIR/tasks/todo.md")
+
+# 1. SPEC unchecked 검사
+if [ -n "$SPEC_FILE" ]; then
+  UNCHECKED=$(count_unchecked "$SPEC_FILE")
   UNCHECKED=${UNCHECKED:-0}
   if [ "$UNCHECKED" -gt 0 ] 2>/dev/null; then
-    echo "DRIFT: SPEC.md에 unchecked 항목 ${UNCHECKED}건" >&2
+    echo "DRIFT: ${SPEC_FILE#"$PROJECT_DIR"/}에 unchecked 항목 ${UNCHECKED}건" >&2
     DRIFT=$((DRIFT + 1))
   fi
 fi
 
-# 2. todo.md unchecked 검사
-if [ -f "$DOCS_DIR/todo.md" ]; then
-  UNCHECKED=$(count_unchecked "$DOCS_DIR/todo.md")
+# 2. TODO unchecked 검사
+if [ -n "$TODO_FILE" ]; then
+  UNCHECKED=$(count_unchecked "$TODO_FILE")
   UNCHECKED=${UNCHECKED:-0}
   if [ "$UNCHECKED" -gt 0 ] 2>/dev/null; then
-    echo "DRIFT: todo.md에 unchecked 항목 ${UNCHECKED}건" >&2
+    echo "DRIFT: ${TODO_FILE#"$PROJECT_DIR"/}에 unchecked 항목 ${UNCHECKED}건" >&2
     DRIFT=$((DRIFT + 1))
   fi
 fi
 
-# 3. Ship 단계에서는 모든 unchecked가 차단
+# 3. SPEC Status 일관성 — gate-status.json과 대조 (6-gate 워크플로 사용 프로젝트만; 파일 없으면 skip)
+GATE_FILE="$PROJECT_DIR/.claude/gate-status.json"
+if [ -f "$GATE_FILE" ] && [ -n "$SPEC_FILE" ] && command -v jq &> /dev/null; then
+  BUILD_DONE=$(jq -r '.build.completed // false' "$GATE_FILE")
+  VERIFY_DONE=$(jq -r '.verify.completed // false' "$GATE_FILE")
+
+  # SPEC Status가 "Define"인지 확인 (frontmatter 형식만, 본문 파이프라인 설명 제외)
+  if grep -qE "^> \*\*Status\*\*:.*Define" "$SPEC_FILE"; then
+    if [ "$BUILD_DONE" = "true" ] || [ "$VERIFY_DONE" = "true" ]; then
+      echo "DRIFT: SPEC Status='Define'인데 Build/Verify gate가 완료됨" >&2
+      DRIFT=$((DRIFT + 1))
+      # Ship 게이트에서는 차단 (Build 이후에도 SPEC이 Define이면 안 됨)
+      [ "$1" = "ship" ] && BLOCK=1
+    fi
+  fi
+fi
+
+# 4. Ship 단계에서는 모든 unchecked가 차단
 if [ "$1" = "ship" ] && [ "$DRIFT" -gt 0 ]; then
   BLOCK=1
 fi
 
 # Summary
 if [ "$DRIFT" -eq 0 ]; then
-  echo "OK: SPEC/todo/PRD 동기화 상태 정상"
+  echo "OK: SPEC/TODO 동기화 상태 정상"
   exit 0
 fi
 
 if [ "$BLOCK" -eq 1 ]; then
   echo "" >&2
-  echo "BLOCKED (ship gate): SPEC drift 발견 — SPEC.md, todo.md, PRD.md 동기화 후 재시도" >&2
+  echo "BLOCKED (ship gate): SPEC/TODO drift 발견 — 동기화 후 재시도" >&2
   exit 2
 fi
 

package/templates/rules/doc-governance.md

@@ -0,0 +1,62 @@
+# Document Governance
+
+문서 작성 + 작업 완료 시 추적 동기화 규칙. 프로젝트 문서가 "거짓 상태"가 되는 것을 막는 SSOT 규약 —
+실서비스 운영에서 검증된 관행의 일반화.
+
+## SSOT 위계 (한 사실은 한 곳)
+
+| 문서 | 역할 | 갱신 시점 |
+|------|------|----------|
+| `NORTH_STAR.md` | 왜·어디로 (비전 · 북극성 지표 · Non-Goals · 의사결정 휴리스틱) | 방향 전환 시만 |
+| `SPEC.md` (+ `specs/`) | 무엇 (제품/기능 스펙 — 모듈이 커지면 파일 분리) | 기능 정의/변경 |
+| `PRD.md` | 문제 · 솔루션 · 요구사항 | 제품 방향 변경 |
+| `TODO.md` (또는 `tasks/todo.md`) | 다음 할 일 · 진행/완료 추적 | 작업 시작/완료 |
+| `README.md` | 진입점 · 현재 상태 (shipped/stack/배포) | 현재 상태 변동 |
+| `docs/decisions/` | 아키텍처/의존성/데이터모델/보안 결정 (ADR) | change-management.md 분류 따름 |
+
+- 파일 위치는 프로젝트 레이아웃을 따른다 (루트 또는 `docs/`) — **역할·위계·동기화 의무는 불변**.
+- **위계 = 충돌 시 상위 우선.** NORTH_STAR 와 SPEC 이 모순되면 NORTH_STAR 가 이긴다.
+- **같은 사실을 두 곳에 쓰지 않는다.** 한 곳(SSOT)에 두고 나머지는 링크로 가리킨다. 중복 서술 = drift 의 씨앗.
+
+## 무엇을 언제 쓰나
+
+- 신규 기능 → **먼저 SPEC 등재, 그 다음 구현** (spec-first). 대화에서 "추가하자/넣자" = 우선 문서 작업이지 구현 착수가 아니다.
+- 아키텍처 / 외부 의존성 / 데이터 모델 / 보안 / breaking API 결정 → **ADR** (`docs/decisions/`, 템플릿은 change-management.md).
+- 진행/완료 추적 → TODO. 현재 상태 변동 → README.
+
+## 작업 완료 처리 (merge = 코드 + 추적 동기화) — 핵심 의무
+
+PR 머지로 작업이 끝난 게 아니다. **머지 직후 같은 작업 단위로**:
+
+1. TODO 해당 항목 → `[x] (✅ #PR번호)`.
+2. AC / Phase / Non-Goals / DO NOT CHANGE 에 영향 시 → SPEC Change Log.
+3. 현재 상태(shipped / 배포) 변동 시 → README §현재 상태.
+
+빠지면 추적 SSOT 가 거짓 상태가 되고, **다음 세션이 완료분을 backlog 로 오인해 중복 작업하거나
+미완분을 완료로 오인해 건너뛴다.** 금지.
+
+## 현행 vs archive
+
+- **현행 SSOT 만 루트/`docs/` 에**: 위 위계 문서 + `specs/` + `decisions/`.
+- **히스토리는 `docs/archive/`** 로 격리 (옛 버전, 폐기 sub-spec, 완료된 리서치/audit 산출물) —
+  지도 파일(`archive/README.md`) 하나로 찾을 수 있게 한다. 현행 문서에 히스토리가 쌓이면
+  "현재가 무엇인지"를 읽는 비용이 히스토리에 비례해 커진다.
+- 변경 이력이 길어진 문서는 이력만 archive 로 빼고 본문에는 최근분만 남긴다.
+
+## 작성 원칙
+
+- **why 중심** — what 은 코드/diff 가 보여준다.
+- SPEC 이 800줄을 넘으면 기능별 분리 (`spec-scaling` 스킬 참조).
+- **추정/임의 단정 금지** — "직관상 별로", "일반적으로 필요", "내 경험상"은 출처 없는 일반화.
+  측정/스펙 참조/재현 증거로 입증한다.
+
+## 검증 게이트
+
+`.claude/hooks/spec-drift-check.sh` 가 SPEC/TODO 의 unchecked 잔존·Status 불일치를 검출한다 —
+verify 단계에서 경고(exit 1), **ship 단계(`spec-drift-check.sh ship`)에서는 차단(exit 2)**.
+탐지 경로: SPEC 은 `docs/SPEC.md` → `SPEC.md`(루트) 중 첫 존재 파일, TODO 는 `docs/todo.md` →
+`docs/TODO.md` → `todo.md` → `TODO.md` → `tasks/todo.md` 중 첫 존재 파일 — **이 목록 밖 레이아웃은
+게이트가 못 본다** (그 경우 본 규약은 프로즈로만 작동한다고 알라). dev 트랙 설치 시
+ship-checklist.md 의 "SPEC/PRD 정합성" 게이트가 이 스크립트를 호출한다. 프로즈 규약(본 문서)과
+결정론 게이트(훅)는 짝이다 — 규약만으로 안 지켜지는 것이 확인되면 게이트를 넓혀라
+(dev 트랙 설치 시 recurrence-prevention 스킬의 에스컬레이션 사다리 참조).