diff --git a/CHANGELOG.md b/CHANGELOG.md index 62a1758f..d2dbc28d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,17 @@ modified: 2026-09-13 같은 커밋이면 통과, 다른 커밋·`origin/HEAD` 없음은 종전처럼 거부한다. git 실패는 계속 fail-closed이고 `done` 가드는 브랜치를 조회하지 않아 영향이 없다. +### Docs +- **`docs/harness-workflow-simulation.html` 본문을 현행 동작에 맞추고 `docs:check` 현행 문서로 등록했다** (task `simulation-doc-refresh`). + 0.40.1~0.44.4 CHANGELOG를 시나리오별로 대조해(대조표는 task artifact) 워크스루 단계를 고쳤다 — user handoff는 gitignore된 + 워크트리 로컬이고 `task` 활성화가 쓴다(구조·S2·S5·S6), handoff 갱신분은 다음 작업 커밋에 담고 단독 sweep은 푸시 직전만(S3), + 머지 후 종결은 기본 브랜치에서 체크→`done`→`summary --write`→커밋 하나(S4), `--member` 우선·거부되는 이름(S2), + 관리 절은 `init`이 렌더하고 `doctor`가 낡은 절을 경고(S1), `init --stack` 고정과 `harness-team stack`의 `pin:` 줄(S1·명령 카드), + `list --remote`·`--area`(명령 카드). handoff 항목·user handoff 예시도 실제 렌더 형식으로 바로잡았다. + 표지 셋(hero·🆕 배너·footer)을 package.json 버전에 맞추고 `excludedCurrentDocuments`에서 `currentVersionDocuments`로 옮겼다 — + 이제 표지가 밀리면 `npm run docs:check`가 실패한다 — `MAINTAINING.md` 릴리스 5단계에 이 문서의 표지 3곳 갱신을 추가했다. + `docs/followups.md` 10번을 지웠다. + ## [0.44.4] - 2026-09-27 ### Fixed diff --git a/MAINTAINING.md b/MAINTAINING.md index 99846783..ccfde194 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -194,12 +194,16 @@ grep -rn 'origin/main' commands/ skills/ templates/ 이고 이 셋은 템플릿에 하드코딩돼 있습니다. `docs:check`는 이 셋의 **버전 번호**가 `package.json`과 같은지만 대조합니다(`scripts/docs-version-drift.mjs`) — 배너 **산문**이 이번 릴리스를 제대로 설명하는지는 사람이 봐야 합니다. 생성물을 직접 고치면 다음 `docs:generate`가 되돌립니다. 템플릿을 고치고 재생성하세요. + - **`docs/harness-workflow-simulation.html`의 버전 표지 3곳(hero 배지·최신 🆕 배너·footer)도 손으로 올립니다** — + overview 템플릿과 같은 모양이고 `docs:check`가 같은 방식으로 대조합니다. 새 릴리스가 워크스루 단계를 바꿨으면 + 표지만 올리지 말고 해당 시나리오 본문을 먼저 고칩니다 — 표지는 본문이 현행이라는 도장입니다. - **`docs/index.html`의 what-changes 목록에 새 버전을 등재합니다** — 등재하지 않으면 방금 쓴 릴리스 노트가 문서 허브에서 도달 불가입니다. `docs:check`가 목록의 첫 항목이 현행 버전인지 대조합니다. - - **왜 이 두 줄이 절차에 있나:** 0.22.0과 0.23.0이 **연속으로** overview 템플릿을 놓쳐 배지가 + - **왜 이 줄들이 절차에 있나:** 0.22.0과 0.23.0이 **연속으로** overview 템플릿을 놓쳐 배지가 두 세대(v0.21.0) 밀린 채 발행됐습니다. 가드 없는 표면은 절차에 적히지 않으면 반드시 밀립니다. 결합 강도 순서를 기억하세요: `what-changes-*`(3방향 강제) > `harness-overview`·`index.html`(생성+pin·버전 표지 대조, - **산문은 무방비**) > `prerequisites.md`(doctor 양방향) > simulation·guide류(**가드 0** — "X 기준" 라벨 문서와 + **산문은 무방비**) > `harness-workflow-simulation.html`(버전 표지 대조만, **본문은 무방비**) > + `prerequisites.md`(doctor 양방향) > guide류(**가드 0** — "X 기준" 라벨 문서와 명시 제외 문서는 표지 대조 대상이 아닙니다. 분류 규칙은 `scripts/docs-version-drift.mjs` 머리 주석). 6. `CHANGELOG.md`의 `## [Unreleased]`를 새 버전 헤딩(`## [X.Y.Z] - YYYY-MM-DD`)으로 이동 7. main에서 4~6단계의 결과를 **한 커밋**으로 만들어 push합니다. 기능 변경은 PR로 들어오지만, 릴리스 준비 커밋 자체는 그 PR들이 이미 병합된 main 위에 얹는 범프·문서 커밋입니다. diff --git a/docs/followups.md b/docs/followups.md index 272a8e90..57296c41 100644 --- a/docs/followups.md +++ b/docs/followups.md @@ -7,18 +7,9 @@ ## 우선순위 -**남은 것: 10번 하나.** - -10. **`docs/harness-workflow-simulation.html` 본문 현행화 → 버전 드리프트 검사 등록** (2026-09-27, task `docs-version-drift-check`) - - 문제: hero 배지·🆕 배너·footer가 v0.40.0에 머물러 있다(현행과 16릴리스 차이). 그러나 본문 시나리오가 - 0.40.0 기준이라 표지만 고치면 틀린 문서에 현행 도장을 찍는다 — 적어도 0.42.1(handoff 단독 커밋 중단)· - 0.44.0(머지 후 종결은 커밋 하나)이 워크스루 단계에 걸린다. 0.40.1–0.44.2 CHANGELOG 전체를 대조해야 한다. - - 현재 상태: `scripts/docs-version-drift.mjs`의 `excludedCurrentDocuments`에 사유와 함께 올라 있다 — - 조용히 빠진 것이 아니라 **명시 제외**다. 분류가 `current`인 한 제외 항목은 유지되고, "기준" 라벨을 달아 - `baseline`이 되면 검사가 낡은 제외 항목이라며 실패한다. - - 완료 조건: 본문을 현행화하고 표지 셋을 package.json 버전에 맞춘 뒤, 항목을 `excludedCurrentDocuments`에서 - `currentVersionDocuments`로 옮긴다(표지는 `overviewMarkers`와 같은 hero·🆕·footer, footer 정규식만 확인). - `npm run docs:check` green. +**남은 것: 없음.** +(10번은 2026-09-28 task `simulation-doc-refresh`로 처리했다 — 시뮬레이션 문서 본문을 현행화하고 +`docs:check` 현행 문서로 등록했다. 대조표는 그 task의 artifact에 있다.) (4번은 2026-09-12에 **B(src 상수 + 문서 블록 + pin)로 결정**해 task `framing-prompts-in-src`로 올려 여기서 지웠다. testcritic은 `--rubric` 선택자로 3 루브릭 모두 src에 둔다.) (6번은 2026-09-12에 처리했다. 다만 **전제가 반쯤 뒤집혔다** — 실측 결과 이 머신(데스크톱 앱 세션)에서는 diff --git a/docs/harness-workflow-simulation.html b/docs/harness-workflow-simulation.html index 3cd3d962..09334688 100644 --- a/docs/harness-workflow-simulation.html +++ b/docs/harness-workflow-simulation.html @@ -284,7 +284,7 @@

Task Workflow Simulation

새로운 harness task 시스템의 전체 흐름 — init부터 완료, 세션 재개, task 전환까지의 시나리오별 시뮬레이션

- v0.40.0 + v0.44.4 post-commit 자동화 증거 기반 종결 가드 7종 원장은 생성물 @@ -293,6 +293,18 @@

Task Workflow Simulation

+ 🆕 0.40.1–0.44.4 — user handoff는 워크트리 로컬 · 종결은 커밋 하나 · member·stack 판정 정정: +
+ 0.44.4 docs/<user>/<user>-handoff.md를 추적하지 않는다 — 내용이 전부 gitignore된 active.json과 그 워크트리의 git log -1에서 나오는 렌더링이라, 같은 user의 병렬 PR이 머지마다 이 파일에서 충돌했다. 하네스 관리 .gitignore에 docs/*/*-handoff.md(깊이 2 — task handoff는 계속 추적)가 들어가고, task 활성화가 이 파일을 곧바로 쓴다. 커밋 대상 handoff는 task handoff 1파일이다(아래 S3). 아직 추적 중인 저장소는 doctor가 경고하고 migrate가 git rm --cached를 안내만 한다. +
+ 0.44.0 머지 후 종결이 커밋 하나다 — done 가드가 plan.md의 체크박스만 켠 변경을 미커밋 작업으로 세지 않아, 기본 브랜치에서 마지막 단계 체크 → done → summary --write → 커밋 하나로 끝난다(아래 S4). 0.44.1은 하위 디렉터리 설치본에서 이 면제·handoff 제외가 듣지 않던 것을 고쳤다. +
+ 0.42.1 post-commit 훅이 갱신한 handoff만 담는 커밋을 따로 만들지 않는다 — 다음 작업 커밋에 함께 담고, 단독 sweep은 푸시·브랜치 전환·워크트리 정리 직전에 남은 변경이 handoff뿐일 때만 만든다. 훅 동작은 그대로이고 규범만 바뀌었다. +
+ 0.43.0 doctor가 템플릿보다 낡은 관리 절(AGENTS.md#protocol 등)을 경고하고 init을 처방한다 — 관리 절은 migrate가 아니라 init이 렌더한다(아래 S1). 0.44.3 init --stack X로 강제한 스택이 .harness/render-state.json에 고정되고 harness-team stack이 pin: 줄로 보여 준다. +
+ 0.41.0–0.42.0 task 경로·이름 판정: task --area·list --area(모노레포), --member가 config user보다 우선(0.41.5), 명령 이름·.·..·spec 없는 디렉터리·한 세그먼트가 아닌 user는 아무것도 쓰지 않고 거부, list --remote로 원격 브랜치에만 있는 task 조회, 결정 D10(CLAUDE.md의 @AGENTS.md import 유지). 0.40.2 .git/hooks가 없어 post-commit 훅이 조용히 안 깔리던 것 수정 · 0.40.3 protect-files 비밀 3종. +

🆕 0.40.0 — 산문으로 세 벌 들고 있던 절차가 명령 네 개가 된다:
0.40.0 슬래시 커맨드 문서가 에이전트에게 손으로 시키던 절차 네 가지를 harness-team 하위 명령이 소유한다 — 스택 감지(stack), 리뷰/ship 범위·base 판정(scope), .harness/config.json 저장(config get/set), 다이어그램 기록(diagram record). 같은 절차가 세 문서에 세 벌로 복제돼 이미 드리프트가 나 있었다(테스트 3형제 0단계 29/42/36줄, 다이어그램 기록 한 줄이 세 문구). 판정이 없는 부분만 CLI가 가져가고 판단이 남는 부분(기존 테스트 샘플링·러너 부재·Docker 분기, probe·degrade)은 산문에 남는다. 함께 review가 base를 origin/main으로 하드코딩하던 결함을 고쳤다 — 기본 브랜치가 master면 죽고, 동명의 낡은 로컬 브랜치가 있으면 엉뚱한 diff를 조용히 리뷰했다. templates/는 불변이라 소비자는 플러그인 갱신만 하면 되고 migrate는 필요 없다. @@ -404,7 +416,7 @@

Task Workflow Simulation

│ docs/chad/ # 사용자별 영역 ├── chad-task.md # 원장 — summary --write가 렌더 -├── chad-handoff.md # 세션 포인터 +├── chad-handoff.md # 세션 포인터 — 워크트리 로컬, gitignore (0.44.4) │ docs/chad/auth-redesign/ # task 디렉토리 ├── auth-redesign-spec.md @@ -419,11 +431,11 @@

Task Workflow Simulation

파일별 역할

chad-handoff.md — 세션 포인터

-

어떤 task가 활성인지 + 마지막 작업 메모. 상세 내용은 task별 handoff에 위임. post-commit hook이 자동 갱신.

+

어떤 task가 활성인지 + 마지막 커밋 한 줄. 상세 내용은 task별 handoff에 위임. task 활성화·post-commit hook·done이 다시 쓴다. 추적하지 않는다(0.44.4) — 내용이 전부 gitignore된 active.json과 그 워크트리의 마지막 커밋에서 나오므로 워크트리마다 다르고, 추적하면 같은 user의 병렬 PR이 머지마다 충돌한다.

[task]-handoff.md — task 컨텍스트

-

해당 task의 누적 작업 기록. commit마다 git diff 기반으로 자동 append. task 전환 후 재개 시 이 파일로 컨텍스트 복원.

+

해당 task의 누적 작업 기록. commit마다 git diff 기반으로 자동 append — 커밋되는 handoff는 이 파일 하나다. task 전환 후 재개 시 이 파일로 컨텍스트 복원.

[task]-plan.md — 체크리스트

@@ -476,7 +488,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

Claude

.git/config에서 user.name 탐색

-
발견: "chad" → AskUserQuestion으로 확인
+
발견: "chad" → AskUserQuestion으로 확인. 이름은 docs/<user>/ 한 세그먼트여야 한다 — 빈 값·/·\·선행 .·제어문자면 저장 전에 멈춘다(0.41.6). 한글·공백은 통과한다.
❓ AskUserQuestion — docs/ 경로에 "chad"를 사용합니다. 맞나요?
@@ -488,6 +500,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

스택 자동 감지 + 설정 저장

.harness/config.json → { "user": "chad" }
+
감지와 다른 스택을 init --stack X로 강제하면 .harness/render-state.json의 stack에 고정되어 doctor·migrate·플래그 없는 init이 같은 스택으로 렌더한다(0.44.3). 고정 여부는 harness-team stack의 pin: 줄로 확인하고, 감지된 id를 다시 주면 풀린다.
@@ -499,6 +512,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

post-commit hook 설치

.git/hooks/post-commit → harness-team handoff 2>/dev/null || true
+
core.hooksPath가 설정돼 있으면(husky·lefthook) 그 디렉터리에 설치하고, 그 디렉터리가 없으면 안내만 한다. core.hooksPath가 없는데 .git/hooks가 없으면 만들고 설치한다(0.40.2 — 전에는 조용히 건너뛰었다).
⚡ 이후 모든 git commit에서 자동 실행
@@ -507,6 +521,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

System
AGENTS.md 코어 + CLAUDE.md(@AGENTS.md import) 렌더, hooks/skills 배포 완료 (rules는 RN 계열 stack만)
+
하네스 관리 .gitignore 줄도 보장한다 — .harness/active.json·.harness/config.json 등 개인 상태와 docs/*/*-handoff.md(user handoff, 0.44.4).
@@ -515,6 +530,12 @@

[task]-meta.json — 기계 상태 (0.16.0)

migrate/sync도 동일: .harness/config.json이 없으면 동일하게 사용자 이름을 확인하고, post-commit hook이 없으면 설치합니다. 이미 있으면 skip. + +
+ 갱신 경로는 둘이다 (0.43.0): AGENTS.md·CLAUDE.md의 관리 절(<!-- harness:section=… -->)은 + init만 다시 렌더한다 — 재실행은 init --yes이고, 사용자가 편집한 절은 건너뛴다. 설치된 훅·스킬·규칙 파일은 migrate가 갱신한다. + doctor는 편집되지 않았는데 템플릿보다 낡은 관리 절을 관리 절 N개가 최신 템플릿보다 낡음으로 경고하고 harness-team init을 처방한다. +
@@ -536,6 +557,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

사용자

"로그인 버그 고쳐줘" 또는 harness-team task login-bug

+
member는 --member → .harness/config.json의 user → 폴백 순으로 정해진다 — 다른 member의 task를 이어 하려면 task <name> --member <그 member>(0.41.5 — 전에는 config user가 이겨 엉뚱한 docs/<config user>/<name>/을 새로 만들었다). 모노레포면 --area <area>로 meta에 area를 기록한다(0.41.0 — 경로는 바뀌지 않는다).
@@ -563,8 +585,10 @@

[task]-meta.json — 기계 상태 (0.16.0)

└── login-bug-meta.json # created·firstActivatedAt·status·closedAt (기계 상태) .harness/active.json → { "user": "chad", "task": "login-bug", "path": "docs/chad/login-bug", "switchedAt": "2026-08-22T03:41:52.000Z" } +docs/chad/chad-handoff.md → Active Task: login-bug # 활성화 즉시 씀 — 워크트리 로컬 (0.44.4) docs/chad/chad-task.md · docs/task_summary.md # 건드리지 않음 (0.16.0) — summary --write가 렌더 +
아무것도 쓰지 않고 거부(exit 1)하는 이름: harness-team 명령 이름(list·done 등, 0.41.4) · .·..(0.42.0) · spec 마커 없이 내용물이 있는 디렉터리(0.41.1) · 한 세그먼트가 아닌 user(0.41.6) · --member 없이 추론한 member로 다른 member에 이미 있는 이름을 새로 만드는 경우(0.41.5 — --member <그 member>를 안내한다). 명령 이름이라도 그 이름의 task가 이미 있으면(spec 마커) 종전대로 활성화한다.
@@ -583,7 +607,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

Claude

/harness-spec으로 login-bug-spec.md 초안 생성 (0.18.0 — Confluence·Figma·인터뷰 3소스, 또는 직접 작성) → /harness-interview로 Ambiguity 자가진단 검증 → login-bug-plan.md 확정 후 작업 시작

-
CLI가 그대로 안내한다: next: /harness-spec으로 …-spec.md 초안 생성 (또는 직접 작성, Ambiguity 자가진단 포함) · next: /harness-interview → 구현 → 테스트 (/harness-unittest 계열) → 리뷰 → /harness-retro → done
+
CLI가 그대로 안내한다: next: /harness-spec으로 …-spec.md 초안 생성 (또는 직접 작성, Ambiguity 자가진단 포함) · next: /harness-interview → plan.md 작성 → 구현 → 테스트 (/harness-unittest 계열) → 리뷰 → /harness-retro → done
@@ -603,7 +627,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

3
작업 중 → Commit
-
코드 수정 후 commit 시 post-commit hook이 자동으로 handoff 갱신
+
코드 수정 후 commit 시 post-commit hook이 자동으로 handoff 갱신 — 갱신분은 다음 작업 커밋에 담는다
@@ -630,18 +654,22 @@

[task]-meta.json — 기계 상태 (0.16.0)

post-commit hook 자동 실행

harness-team handoff

-
git log -1, git diff HEAD~1 읽기 → handoff 갱신
+
git log -1 --oneline, git diff HEAD~1 --stat 읽기 → handoff 갱신
-docs/chad/login-bug/login-bug-handoff.md — append - ## 2026-05-15 commit: fix: 로그인 토큰 검증 로직 수정 - 변경: src/auth/token.ts, src/auth/validate.ts - 다음: 엣지 케이스 처리 - -docs/chad/chad-handoff.md — 갱신 - Active: login-bug - Last commit: 로그인 토큰 검증 로직 수정 +docs/chad/login-bug/login-bug-handoff.md — append # 추적 — 다음 커밋에 담긴다 + ## 2026-05-15T06:12:03.481Z — 3f2a9c1 fix: 로그인 토큰 검증 로직 수정 + src/auth/token.ts | 12 ++++++------ + src/auth/validate.ts | 8 +++++--- + +docs/chad/chad-handoff.md — 재작성 # gitignore — 커밋 대상 아님 (0.44.4) + ## Active Task + login-bug + ## Last Commit (2026-05-15) + 3f2a9c1 fix: 로그인 토큰 검증 로직 수정 + ## Full Context → docs/chad/login-bug/login-bug-handoff.md
+
커밋이 handoff 파일만 바꾼 sweep 커밋이면 훅은 아무것도 쓰지 않는다(0.38.1 — 자기 출력을 먹는 churn 차단). 병합·빈 커밋은 기록한다. --amend는 마지막 항목을 교체한다(0.38.2).
⚡ 사용자 개입 없이 자동 완료
@@ -652,6 +680,17 @@

[task]-meta.json — 기계 상태 (0.16.0)

hook — plan 완료 여부 확인

login-bug-plan.md 미완료 항목 존재 → 아무 동작 없음, 작업 계속

+
모든 체크박스가 - [x]면 훅이 PLAN_COMPLETE를 출력한다 — S4의 트리거 (1)이다.
+
+ + +
+
5
+
+
Claude — 다음 커밋
+
+

커밋 직후 트리는 login-bug-handoff.md 때문에 dirty다. 그 변경만 담는 커밋을 따로 만들지 않고 다음 작업 커밋에 함께 stage한다(0.42.1).

+
단독 sweep 커밋은 푸시·브랜치 전환·워크트리 정리 직전에 남은 변경이 handoff뿐일 때만 만든다 — 보통 PR/MR당 한 번이다. dirty handoff는 done 가드가 무시하므로 남겨 둬도 종결을 막지 않는다. chad-handoff.md는 gitignore라 stage 대상이 아니다 — git add -f로 억지로 담지 않는다.
@@ -679,7 +718,16 @@

[task]-meta.json — 기계 상태 (0.16.0)

트리거 3가지: (1) post-commit hook이 plan 전체 완료 감지, (2) 사용자가 "다 됐어", "완료했어", "PR 올릴게" 등 완료 신호 발화, (3) 사용자가 직접 harness-team done 실행. - 셋 모두 종결 가드를 통과한 뒤 AskUserQuestion을 거쳐 실수 완료를 방지합니다 (P0 — 선언이 아니라 강제). + 셋 모두 종결 가드를 통과해야 합니다 (P0 — 선언이 아니라 강제). (1)·(2)는 Claude가 done을 실행하기 전에 AskUserQuestion으로 확인합니다 — CLI 자체는 묻지 않으므로 (3) 직접 실행은 가드만 거칩니다. + + +
+ PR/MR로 일하면 종결은 머지 후 기본 브랜치에서 커밋 하나다 (0.44.0): + plan의 마지막 단계(보통 "커밋·PR")를 - [x]로 켠다 → harness-team done → harness-team summary --write + → 커밋 하나(chore(task): <name> 종결)에 plan·meta·task handoff·원장을 함께 담는다. + done 가드는 활성 task의 plan.md 변경이 줄머리 체크박스를 켠 것뿐이면 미커밋 작업으로 세지 않는다(끄기·줄 추가·산문 수정은 종전대로 막는다) — 그래서 체크·종결·원장을 커밋 셋으로 나눌 이유가 없다. + 단계를 켜는 판단은 여전히 에이전트 몫이다 — 머지를 확인하기 전에 켜지 않는다. + summary --write는 기본 브랜치이거나 HEAD가 origin/HEAD의 기본 브랜치와 같은 커밋일 때만 허용되고 피처 브랜치에서는 거부되므로, 종결은 PR 브랜치가 아니라 기본 브랜치에서 한다.
@@ -716,7 +764,7 @@

[task]-meta.json — 기계 상태 (0.16.0)

가드 7종 + 선언 유효성 (구성은 0.21.0 이후 불변 — 증거 출처만 0.37.0에서 바뀜) 1. plan.md에 미완 체크박스(- [ ]) # 0.7~ 2. artifact.md 미작성 / 템플릿 그대로 # 0.7~ -3. 미커밋 변경 존재 # handoff 2개는 제외 (0.9.5) +3. 미커밋 변경 존재 # handoff 제외 (0.9.5) · plan 체크박스만 켠 변경 제외 (0.44.0) 4. task 시작 이후 커밋 0개 # 0.7~ 5. 소스 변경 O + 테스트 변경 X # 0.18.1 · 기본 ON — 0.19.0에서 실제 발동 6. spec이 review: required인데 리뷰 증거 없음 # 0.18.1 · spec opt-in · 0.37.0부터 meta.reviews[] @@ -761,6 +809,12 @@

[task]-meta.json — 기계 상태 (0.16.0)

docs/chad/login-bug/login-bug-meta.json { "status": "done", "closedAt": "2026-08-22T04:11:07.914Z" } +docs/chad/chad-handoff.md — 종결 형태로 재작성 # gitignore (0.44.4) + ## Active Task + 없음 — `.harness/active.json` 은 `null` 이다. + ## Last Completed Task (2026-08-22) + `login-bug` — done + docs/chad/chad-task.md · docs/task_summary.md # 건드리지 않음 (0.16.0) 기본 브랜치에서 harness-team summary --write 로 렌더 @@ -805,11 +859,14 @@

[task]-meta.json — 기계 상태 (0.16.0)

docs/chad/chad-handoff.md 읽기

-Active: login-bug -Last commit: 로그인 토큰 검증 수정 (2026-05-15) -다음: 엣지 케이스 처리 +## Active Task +login-bug +## Last Commit (2026-05-15) +3f2a9c1 fix: 로그인 토큰 검증 로직 수정 +## Full Context → docs/chad/login-bug/login-bug-handoff.md
+
이 파일은 워크트리 로컬이다(0.44.4) — 새 워크트리·clone에는 없고, task <name> 활성화 때 곧바로 쓰인다. "다음에 할 일"은 여기가 아니라 plan·Context Card에 있다.
@@ -872,8 +929,10 @@

[task]-meta.json — 기계 상태 (0.16.0)

있으면 → active 전환 .harness/active.json → { "user": "chad", "task": "auth-redesign", "path": "docs/chad/auth-redesign", "switchedAt": "2026-08-23T09:12:30.000Z" } -docs/chad/chad-handoff.md - Active: auth-redesign ← 갱신 +docs/chad/chad-handoff.md # 활성화가 곧바로 씀 — 워크트리 로컬 (0.44.4) + ## Active Task + auth-redesign ← 갱신 + ## Full Context → docs/chad/auth-redesign/auth-redesign-handoff.md docs/chad/login-bug/ ← 그대로 보존 @@ -1049,23 +1108,27 @@

[task]-meta.json — 기계 상태 (0.16.0)

harness-team task <name>

-

task 생성 + 활성화. feature/fix 구분 없이 이름으로 식별. 이미 존재하면 활성화만.

+

task 생성 + 활성화. feature/fix 구분 없이 이름으로 식별. 이미 존재하면(spec 마커) 활성화만. --member <x>는 config user보다 우선한다(0.41.5). --area <area>는 meta에 area를 기록한다(0.41.0). 활성화는 워크트리 로컬 <user>-handoff.md도 쓴다(0.44.4).

harness-team list

-

전체 task 목록 + 현재 active task(*) 표시. 원장이 아니라 docs/<user>/<name>/<name>-spec.md가 있는 디렉터리를 스캔한다 (0.16.0).

+

전체 task 목록 + 현재 active task(*) 표시. 원장이 아니라 docs/<user>/<name>/<name>-spec.md가 있는 디렉터리를 스캔한다 (0.16.0). --area로 거르고(0.41.0), --remote는 머지되지 않은 origin 브랜치에만 있는 task를 덧붙인다 — fetch하지 않고 로컬 refs/remotes/origin/* 기준이다(0.42.0).

harness-team done

-

수동 완료 트리거. 종결 가드 7종(plan·artifact·미커밋·커밋 0개·테스트·리뷰 증거·검증 증거) 통과 후 AskUserQuestion 확인 → 완료 처리. plan 완료 감지나 발화로도 트리거됨. 리뷰·검증 증거는 meta.reviews[]가 정본이고, 그 키가 없는 구 task만 artifact 마커로 판정한다(0.37.0). --force는 경고만 하고 통과시키되 무시된 issue가 1개 이상이면 meta에 forcedAt·forcedIssues를 남긴다(0.34.0).

+

수동 완료 트리거. 종결 가드 7종(plan·artifact·미커밋·커밋 0개·테스트·리뷰 증거·검증 증거) 통과 후 완료 처리 — CLI는 묻지 않으며, plan 완료 감지나 발화로 트리거될 때 Claude가 실행 전에 AskUserQuestion으로 확인한다. 리뷰·검증 증거는 meta.reviews[]가 정본이고, 그 키가 없는 구 task만 artifact 마커로 판정한다(0.37.0). --force는 경고만 하고 통과시키되 무시된 issue가 1개 이상이면 meta에 forcedAt·forcedIssues를 남긴다(0.34.0).

harness-team handoff

-

post-commit hook 전용 (.git/hooks/post-commit에서 자동 실행). git log/diff 기반으로 <name>-handoff.md와 <user>-handoff.md를 갱신. 활성 포인터가 없으면 조용히 no-op이다.

+

post-commit hook 전용 (git이 실제로 읽는 hooks 디렉터리 — core.hooksPath·워크트리 반영 — 의 post-commit에서 자동 실행). git log/diff 기반으로 <name>-handoff.md와 <user>-handoff.md를 갱신. 활성 포인터가 없으면 조용히 no-op이다. 커밋 대상은 <name>-handoff.md 하나이고 다음 작업 커밋에 함께 담는다(0.42.1·0.44.4).

harness-team summary [--write|--check] 0.16.0

-

task 디렉터리를 스캔해 원장(docs/task_summary.md·docs/<user>/<user>-task.md)을 렌더한다. 인자 없이 실행하면 stdout으로만 낸다. --write는 HEAD가 origin/HEAD의 기본 브랜치와 정확히 같은 커밋일 때만 허용된다(0.30.0 — 브랜치 이름이 아니라 커밋 기준이라 워크트리에서도 통과한다). ahead·behind는 fail-closed 거부 — 피처 브랜치에서 원장을 쓰면 병렬 충돌이 돌아온다.

+

task 디렉터리를 스캔해 원장(docs/task_summary.md·docs/<user>/<user>-task.md)을 렌더한다. 인자 없이 실행하면 stdout으로만 낸다. --write는 기본 브랜치에서, 또는 HEAD가 origin/HEAD의 기본 브랜치와 정확히 같은 커밋일 때만 허용된다(0.30.0 — 커밋 기준 경로 덕분에 기본 브랜치를 체크아웃할 수 없는 워크트리에서도 통과한다). 피처 브랜치가 ahead·behind면 fail-closed 거부 — 피처 브랜치에서 원장을 쓰면 병렬 충돌이 돌아온다. 머지 후 종결 커밋 하나에 함께 담는다(S4).

+
+
+

harness-team stack 0.40.0

+

스택 감지 결과를 보여 준다. init --stack X로 고정한 스택이 있으면 pin: <고정> (detected: <감지> → effective: <고정>) — unpin: <해제 명령> 줄이 붙고, --json에는 stackPin 필드가 나온다(0.44.3).

harness-team context init|check 0.12.0

@@ -1102,7 +1165,7 @@

harness-team boundary check ` | S7 | CHANGELOG | 해당 없음(S7은 소유자 `scope`만 가리킴) | +| 0.43.0 | doctor가 낡은 관리 절 경고 → `init` 처방, migrate는 관리 절 미렌더 | S1 infobox | `src/commands/doctor.mjs:980` | 반영(S1 infobox 정정) | +| 0.44.0 (#108) | done 가드 체크박스-only plan 면제 → 머지 후 종결 = 체크→done→summary→커밋 하나 | S4 | harness-task "머지 후 종결" 절 + `isCheckboxOnlyChange` | 반영(S4 infobox·가드 3 주석) | +| 0.44.0 (#107) | AGENTS.md protocol 관리 절 압축, 소비자는 `init --yes` | S1 infobox | CHANGELOG | 반영(관리 절 = init) | +| 0.44.1 | 하위 디렉터리 설치본의 handoff 제외·면제 판정 수정 | S4 가드 3 | CHANGELOG | 해당 없음(동작 정정, 워크스루 불변) | +| 0.44.2 | 워크트리에서 백업 경로를 메인 체크아웃 기준으로 | — | — | 해당 없음 | +| 0.44.3 (#111/#113) | `init --stack X` 고정(render-state `stack`), `harness-team stack`의 `pin:` 줄 | S1 step 3·명령 카드 | `src/render-state.mjs` stack 필드 | 반영 | +| 0.44.3 | docs:check 버전 표지 검사, 이 문서는 명시 제외 | 레지스트리 | `scripts/docs-version-drift.mjs` | 이 PR로 등록 | +| 0.44.4 (#115) | `docs/*/*-handoff.md` gitignore(워크트리 로컬), `task` 활성화가 user handoff를 씀, 커밋 대상은 task handoff 1파일 | 구조·S1·S2·S3·S5·S6·명령 카드 | `src/harness.mjs` gitignore 목록, `task-paths.mjs` `USER_HANDOFF_IGNORE`, `task.mjs` `renderUserHandoff`·활성화 | 반영 | + +소스로 추가 확인한 기존 본문 오류(0.40.0 이전부터): +- S3 task handoff 항목 형식 — 실제는 `## — ` + `git diff HEAD~1 --stat`(`runHandoffAuto`). 본문의 + `commit:`/`변경:`/`다음:` 형식은 실제와 달라 고쳤다. +- S3·S5 user handoff 내용 — 실제는 `## Active Task` / `## Last Commit ()` / `## Full Context → ` + (`renderUserHandoff`). "다음:" 줄은 없다. 고쳤다. +- S4 done — `-handoff.md`도 종결 형태로 다시 쓴다(`runDone`). 트리에 추가했다. +- post-commit 훅의 `PLAN_COMPLETE` 신호(S3 step 4)는 현행 그대로다 — 수정 없음. + +## Reviews +*Codex 등 리뷰 실행 시 결과(요약·발견·조치)를 날짜와 함께 남긴다. 남기지 않은 리뷰는 "안 한 것"으로 간주.* +*기계 판독용 마커를 함께 남긴다: ``* + +### 2026-09-27T16:07:20.493Z — codex (harness-team review) + +- engine: codex · scope: worktree · tip: c210a38764dcb2b019bf241f090be78a207b0fb5 · exit 0 · 2264 B + +```text +전하, **P1은 없습니다. 문서의 동작 주장 두 곳은 수정이 필요합니다.** Working tree에는 post-commit이 갱신한 task handoff만 미커밋 상태였고, 요청하신 HTML·레지스트리·MAINTAINING 변경은 `main` 대비 커밋 `c210a38`에서 검토했습니다. 파일은 수정하지 않았습니다. + +- **P2** [docs/harness-workflow-simulation.html:730](/Users/hsonpro/.ao/data/worktrees/harness-aijient-team-plugin/harness-aijient-team-plugin-12/docs/harness-workflow-simulation.html:730) — `summary --write`가 `origin/HEAD`와 같은 커밋에서만 허용된다는 주장은 과장입니다. 실제 가드는 기본 브랜치 **이름**이면 커밋 동일성 검사를 건너뛰므로, ahead·behind 상태에서도 실행될 수 있습니다. +- **P2** [docs/harness-workflow-simulation.html:721](/Users/hsonpro/.ao/data/worktrees/harness-aijient-team-plugin/harness-aijient-team-plugin-12/docs/harness-workflow-simulation.html:721) — 직접 실행한 `harness-team done`까지 `AskUserQuestion`을 거친다는 기존 본문 주장은 실제 CLI와 다릅니다. `runDone`은 가드 통과 후 확인 질문 없이 완료 상태를 씁니다. +- **P3** [docs/harness-workflow-simulation.html:1123](/Users/hsonpro/.ao/data/worktrees/harness-aijient-team-plugin/harness-aijient-team-plugin-12/docs/harness-workflow-simulation.html:1123) — 훅 위치를 `.git/hooks/post-commit`으로 고정해 적었습니다. 설치 코드는 `core.hooksPath`와 Git worktree의 실제 hooks 경로를 따릅니다. +- **P3** [MAINTAINING.md:202](/Users/hsonpro/.ao/data/worktrees/harness-aijient-team-plugin/harness-aijient-team-plugin-12/MAINTAINING.md:202) — 시뮬레이션 문서 갱신 항목을 추가했지만 설명은 여전히 “이 두 줄”이라고 합니다. + +**검토 결과:** `docs-version-drift.mjs`의 레지스트리 이동과 MAINTAINING의 표지 갱신 절차는 일치합니다. 표지 검사 결과는 `[]`이고 `docs:check`도 통과했습니다. 작성된 버전 주장에서 **0.44.4 이후의 미래 버전 번호는 발견하지 못했습니다.** 다만 표지 검사는 본문 사실관계를 검증하지 않으므로, 위 P2를 고친 뒤 문서 현행화를 승인하는 것이 적절합니다. +``` + + + +**판별·조치 (2026-09-28):** 4건 모두 소스로 재현해 진짜 결함으로 판별, 전부 반영했다. +- P2 `summary --write` 조건 — `runSummary`는 현재 브랜치가 기본 브랜치 이름이면 통과하고, 아니면 `isSyncedWithDefault`(같은 커밋)를 + 본다(`src/commands/summary.mjs:390-392`). S4 infobox를 "기본 브랜치이거나 같은 커밋"으로 고쳤고, 같은 과장이 있던 기존 summary + 명령 카드(0.30.0 문장)도 함께 고쳤다. +- P2 `done`의 AskUserQuestion — `runDone`은 묻지 않는다. 확인은 Claude가 (1)·(2) 트리거에서 실행 전에 하는 것이라고 S4 infobox와 + done 명령 카드를 고쳤다(기존 본문 오류). +- P3 훅 경로 — handoff 카드를 `git rev-parse --git-path hooks`(core.hooksPath·워크트리 반영) 기준 서술로 고쳤다. +- P3 MAINTAINING "이 두 줄" → "이 줄들". + +## Learnings diff --git a/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-context.md b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-context.md new file mode 100644 index 00000000..50ea373e --- /dev/null +++ b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-context.md @@ -0,0 +1,27 @@ +# simulation-doc-refresh — Context Card + + +## Now +- Goal: +- Current atomic step: +- Stop / human-decision condition: + +## Constraints and settled decisions +- + +## JIT retrieval map +- Identifiers / symbols: +- Narrow globs: +- Read next: +- Verification command: + +## Failure capsules (max 3 unresolved) +### F-001 +- Signal: +- Tried: +- Compact finding / current hypothesis: +- Next discriminator: +- Source (safe path or command): + +## Resume checklist +- diff --git a/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-handoff.md b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-handoff.md new file mode 100644 index 00000000..8a5bba80 --- /dev/null +++ b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-handoff.md @@ -0,0 +1,26 @@ +# simulation-doc-refresh — Handoff + +(세션 종료 시 post-commit hook이 자동 갱신합니다) + +## 2026-09-27T16:03:59.228Z — c210a38 docs(sim): 시뮬레이션 문서 본문을 0.44.4 현행으로 맞추고 docs:check 현행 문서로 등록 +CHANGELOG.md | 11 ++ + MAINTAINING.md | 6 +- + docs/followups.md | 15 +-- + docs/harness-workflow-simulation.html | 117 ++++++++++++++++----- + .../simulation-doc-refresh-artifact.md | 49 +++++++++ + .../simulation-doc-refresh-context.md | 27 +++++ + .../simulation-doc-refresh-handoff.md | 3 + + .../simulation-doc-refresh-meta.json | 11 ++ + .../simulation-doc-refresh-plan.md | 20 ++++ + .../simulation-doc-refresh-spec.md | 41 ++++++++ + scripts/docs-version-drift.mjs | 9 +- + 11 files changed, 263 insertions(+), 46 deletions(-) + +## 2026-09-27T16:08:19.728Z — ecb1811 docs(sim): codex 리뷰 반영 — summary --write 조건·done 확인 주체·훅 경로 정정 +MAINTAINING.md | 2 +- + docs/harness-workflow-simulation.html | 10 ++++----- + .../simulation-doc-refresh-artifact.md | 25 ++++++++++++++++++++++ + .../simulation-doc-refresh-handoff.md | 14 ++++++++++++ + .../simulation-doc-refresh-meta.json | 12 ++++++++++- + .../simulation-doc-refresh-plan.md | 2 +- + 6 files changed, 57 insertions(+), 8 deletions(-) diff --git a/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-meta.json b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-meta.json new file mode 100644 index 00000000..0ce3bbcb --- /dev/null +++ b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-meta.json @@ -0,0 +1,21 @@ +{ + "user": "hslee", + "task": "simulation-doc-refresh", + "created": "2026-09-27", + "firstActivatedAt": "2026-09-27T15:57:43.726Z", + "status": "open", + "closedAt": null, + "forcedAt": null, + "forcedIssues": null, + "reviews": [ + { + "kind": "codex", + "engine": "codex", + "scope": "worktree", + "tip": "c210a38764dcb2b019bf241f090be78a207b0fb5", + "at": "2026-09-27T16:07:20.493Z", + "exitCode": 0, + "outputBytes": 2264 + } + ] +} diff --git a/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-plan.md b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-plan.md new file mode 100644 index 00000000..8f8877c2 --- /dev/null +++ b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-plan.md @@ -0,0 +1,20 @@ +# simulation-doc-refresh — Plan + +## 목표 +시뮬레이션 문서 본문을 v0.44.4 현행으로 맞추고 docs:check 현행 문서로 등록한다. + +## 단계 +- [x] 0.40.1~0.44.4 대조표를 artifact에 기록 +- [x] 시뮬레이션 문서 본문·표지 현행화 +- [x] `docs-version-drift.mjs` 레지스트리 이동 + followups 10번 삭제 +- [x] CHANGELOG [Unreleased] 항목 +- [x] `npm test`·`npm run docs:check` green +- [x] codex 리뷰 기록 +- [ ] 커밋·PR·CI green +- [ ] 머지 + +## Ontology 변경 로그 +- (none) + +## 참고 +- 브리프: 머지·종결까지 승인됨(버전 범프·릴리스 금지) diff --git a/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-spec.md b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-spec.md new file mode 100644 index 00000000..80097be2 --- /dev/null +++ b/docs/hslee/simulation-doc-refresh/simulation-doc-refresh-spec.md @@ -0,0 +1,41 @@ +# simulation-doc-refresh — Spec + +## 목적 / 요구사항 +- 문제: `docs/harness-workflow-simulation.html`은 hero·🆕 배너·footer가 v0.40.0이고 본문 시나리오도 0.40.0 기준이다 + (현재 파일 = `-0.40.0.html` 스냅샷과 바이트 동일). 0.40.1~0.44.4 사이 워크스루 단계에 닿는 동작 변경(handoff sweep 규범, + user handoff gitignore, 머지 후 종결 커밋 하나, member 우선순위, stack 고정, 관리 절 init 처방 등)이 반영돼 있지 않다. + 그래서 `scripts/docs-version-drift.mjs`의 `excludedCurrentDocuments`에 명시 제외돼 있다(`docs/followups.md` 10번). +- 영향: 이 문서를 워크스루로 읽는 팀원·소비자 — 틀린 절차(handoff 2파일 커밋, 종결 커밋 셋 등)를 따라 하게 된다. +- 기대 결과: 본문이 v0.44.4 현행 동작과 일치하고, 표지 셋이 package.json 버전과 같으며, docs:check가 이 문서를 + `currentVersionDocuments`로 검사한다. followups 10번은 지운다. +- 제약: 문서·스크립트 레지스트리만 바꾼다(제품 코드 변경 없음). 버전 범프 금지. 미래 버전 번호를 박지 않는다. + 확인 못 한 동작은 쓰지 않는다 — 대조표의 모든 반영 항목은 CHANGELOG + 소스/명령 문서로 확인한다. + +## 설계 / 접근 +- 0.40.1~0.44.4 CHANGELOG 항목을 시나리오(구조·S1~S7·명령 카드)에 매핑한 대조표를 artifact에 남긴다. +- 표지: hero 배지 `v0.44.4`, 최신 🆕 배너 `0.40.1–0.44.4` 묶음(상한 판정), footer `v0.44.4`. +- 본문은 필요한 단계만 고친다(시나리오 재설계 없음). 과거 🆕 배너는 이력이라 그대로 둔다. +- 레지스트리: `excludedCurrentDocuments`를 비우고 `currentVersionDocuments`에 `overviewMarkers`로 등록. +- 스냅샷은 만들지 않는다 — 0.40.0 상태는 `-0.40.0.html`이 이미 보존하고, 새 스냅샷은 릴리스 몫이다. + +## Ontology +- **현행 문서**: `classifyDocument`가 `current`로 분류하는 docs/ 최상위 HTML — 표지 버전이 package.json과 같아야 한다. +- **표지 셋**: hero 배지(`tag-purple`)·최신 🆕 배너 상한·footer의 `v<버전>`. +- 게이트 근거: 목표·제약·완료 기준·영향 파일(문서 1·스크립트 1·followups·CHANGELOG)이 모두 확정됐다. + +## Ambiguity 자가진단 +- [x] **Goal 명확도** (40%) — 목표가 한 문장으로 구체화되었는가? +- [x] **Constraint 명확도** (30%) — 기술/시간/범위 제약이 명시되었는가? +- [x] **Success 기준** (30%) — 완료를 어떻게 측정하는가? +- [x] **Context 명확도** (brownfield 한정) — 영향 받는 기존 코드/파일을 식별했는가? +- [x] **Ambiguity ≤ 0.2** — 위 항목 가중합 ≥ 0.8 + +## Done evidence +```json +{ "version": 1, "review": "required", "tests": "skip" } +``` + +## 참고 +- `scripts/docs-version-drift.mjs` · `tests/docs-version-drift*.test.mjs` +- `commands/harness-task.md` "post-commit handoff"·"머지 후 종결" 절 · `src/commands/task.mjs` (`runHandoffAuto`·`runDone`·`renderUserHandoff`) +- `docs/followups.md` 10번 diff --git a/scripts/docs-version-drift.mjs b/scripts/docs-version-drift.mjs index 1d5c7f0e..6436b0dd 100644 --- a/scripts/docs-version-drift.mjs +++ b/scripts/docs-version-drift.mjs @@ -37,14 +37,11 @@ export const currentVersionDocuments = [ path: 'docs/index.html', markers: [{ name: 'newest what-changes entry', pattern: /href="what-changes-(\d+\.\d+\.\d+)\.html"/ }], }, + // 표지 셋이 overview와 같은 모양이다(hero 배지·🆕 배너·footer의 `v<버전>`). 본문은 사람이 현행화한다. + { path: 'docs/harness-workflow-simulation.html', markers: overviewMarkers }, ]; -export const excludedCurrentDocuments = [ - { - path: 'docs/harness-workflow-simulation.html', - reason: '본문 시나리오가 0.40.0 기준이라 표지만 고칠 수 없다 — 본문 현행화 후 documents로 옮긴다 (docs/followups.md)', - }, -]; +export const excludedCurrentDocuments = []; function versionSurfaces(html) { const tags = [...html.matchAll(/]*\bclass="tag\b[^"]*"[^>]*>([^<]*)<\/span>/g)].map((match) => match[1]);