refactor: 문서 개선 중

.agents/skills/running-tech-log-pipeline/SKILL.md

@@ -70,15 +70,44 @@ Agent(subagent_type="record-writer", prompt=<references/subagent-prompts.md 의
 그것을 되풀이하지 않아도 되는 것이 이 방식의 값이다 — 프롬프트는 **이번 런의 입력 경로와
 글감**만 준다.
 
-**단계가 아닌 에이전트가 넷 더 있다.** 기록 한 편을 놓고 역할을 가른 것이라 아무 단계에도
-붙지 않는다. 부를지는 사람이 정하고, 원장의 단계 칸에는 안 들어간다.
+**단계 밖의 보조 에이전트도 역할을 고정한다.** 선택적으로 부르는 리뷰와 v3 런에서 절차상
+필요한 command/fact review를 섞지 않는다. `qualityReviews`에 들어가는 역할은 단계 칸과 별도로
+검증기가 확인한다.
 
 | 에이전트 | 언제 | 안 하는 일 |
 |---|---|---|
 | `source-auditor` | S3 앞. 원본의 주장을 `관측`·`추론`·`미검증`으로 가른 표를 만든다 | 기록을 안 쓴다 |
-| `fact-reviewer` | 쓴 뒤. 결과 문장을 원문과 한 글자씩 역대조한다 | 파일을 안 고친다 |
-| `reader-reviewer` | 쓴 뒤. 제목·요약·목차만 보고 30초 안에 읽히는지 본다 | 본문을 안 연다 |
-| `setup-runner` | Setup 을 쓴 뒤. 손으로 끝까지 칠 수 있는지 읽는다 | 실제로 치지는 않는다 |
+| `command-pedagogy-planner` | S3 뒤 initial analysis에 finding이 있을 때 | Markdown을 안 고친다 |
+| `command-pedagogy-editor` | planner가 만든 plan을 command span에 반영할 때 | command block 밖의 산문을 안 고친다 |
+| `command-pedagogy-reviewer` | S6 뒤 final analysis에 shell/CLI block이 있을 때 | 파일을 안 고친다 |
+| `fact-reviewer` | command/prose/voice 수정이 모두 끝난 S6 뒤 | 파일을 안 고친다 |
+| `reader-reviewer` | 필요할 때 제목·요약·목차만 보고 30초 안에 읽히는지 본다 | 본문을 안 연다 |
+| `setup-runner` | Setup을 쓴 뒤 추가 운영성 검토가 필요할 때 | 실제로 치지는 않는다 |
+
+## Command pedagogy lane — S3 직후 초벌, S6 뒤 최종 리뷰
+
+S3이 기록을 만들면 먼저 결정론적 분석을 남긴다.
+
+```bash
+python3 scripts/check-command-pedagogy.py <기록.md> \
+  -o runs/<프로젝트>/<runId>/stage/S3/command-initial.json
+```
+
+- **shell/CLI block이 없으면** command planner/editor/reviewer를 모두 `SKIPPED`로 적고 사유를 남긴다.
+- **finding이 없으면 planner/editor**는 `SKIPPED`다. 단, shell/CLI가 있으므로 최종 reviewer는 S6 뒤에 돈다.
+- finding이 있으면 `command-pedagogy-planner`가 frozen plan을 만들고 `command-pedagogy-editor`가
+  `CommandPatchSet`만 만든다. editor가 기록 전체를 직접 고치지 않는다.
+- patch 적용은 `scripts/apply-command-pedagogy-patch.py`만 쓴다. 이 도구는 initial analysis의
+  hash와 span을 대조해 **원래 command block 밖의 산문을 건드리지 못하게 한다.**
+- S5와 S6은 명령어를 보호 구간으로 취급한다. 둘이 끝난 뒤 같은 deterministic analyzer를 다시
+  돌려 `finalAnalysis`를 남긴다. initial에 command block이 있었는데 final에서 전부 사라지거나
+  `majorFindings > 0`이면 끝난 것이 아니다.
+- final에 shell/CLI가 하나라도 있으면 `command-pedagogy-reviewer`가 독립적으로 `PASS`해야 한다.
+  `FAIL`과 `UNCERTAIN`은 막는다.
+- 마지막으로 `fact-reviewer`가 **모든 command/prose/voice 수정 이후** 기술 사실을 역대조해 `PASS`해야 한다.
+
+이 영수증은 `run.json`의 `qualityReviews.commandPedagogy`와
+`qualityReviews.technicalEvidence`에 남긴다. command/fact review 자체는 schemaVersion 3 계약이다. schemaVersion 4부터는 analysis/plan/patch/review JSON의 repo-relative path+sha256과 최종 기록 `sourceSha256`까지 남긴다. v3 이전/이전 형식 원장에 새 영수증을 소급해 만들지 않는다. `CommandPlan`/`CommandPatchSet`은 `scripts/validate-command-pedagogy-artifact.py`로 검증한다.
 
 ## 순서가 고정된 곳
 
@@ -95,8 +124,9 @@ Agent(subagent_type="record-writer", prompt=<references/subagent-prompts.md 의
 S6 이 채울 자리(선택·비교·어긋남)가 보인다. 순서를 뒤집으면 S5 가 S6 이 넣은 목소리를
 「과한 대구」로 다시 깎는다.
 
-**S6 → S7.** Studio 에는 문장 손질이 끝난 것만 넣는다. 저장한 뒤에 고치면 Studio 쪽 `version`
-이 올라가고 검증 산출물이 무효가 된다.
+**S6 → final command review → fact review → S7.** Studio에는 문장 손질뿐 아니라 command-pedagogy와
+technical-evidence 검토까지 끝난 것만 넣는다. 저장한 뒤에 고치면 Studio 쪽 `version`이 올라가고
+검증 산출물이 무효가 된다.
 
 ## S5·S6 뒤에는 S3 관문을 다시 돌린다
 
@@ -112,6 +142,12 @@ node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로
 
 원장에서는 이것이 S5·S6 의 관문이지 S3 의 재실행이 아니다.
 
+`check_evidence.mjs --repo` 의 exit 의미는 구분한다. `0`은 대조 완료, `1`은 실제 불일치,
+`2`는 검사 대상 자체가 성립하지 않음, `3`은 원본 저장소가 현재 머신에 없어 repo 대조를
+수행하지 못한 상태다. 새 publication run의 관문에서는 `3`을 PASS로 기록하면 안 된다. 반면
+저장소 전체를 dogfooding하는 `verify-pipeline.py`는 기존 문서의 내용 불일치와 실행 환경의
+부재를 섞지 않기 위해 `3`을 `UNVERIFIABLE` WARN으로 따로 센다.
+
 ## 건너뛰어도 되는 단계
 
 이미 있는 것을 다시 만들지 않는다. 건너뛴 단계도 **원장에 `SKIPPED` 와 사유를 적는다.**