refactor: 문서 개선 중
This commit is contained in:
donghyeon-ka
@@ -121,6 +121,24 @@ node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs
|
||||
node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
|
||||
```
|
||||
|
||||
`--repo`는 선택 옵션이 아니다. S3와 S3 관문을 다시 실행하는 S5·S6 모두 live source
|
||||
reconciliation을 시도해야 한다. 현재 기계에 `sourceRepository.path`가 없어서 명령이 exit 3을
|
||||
돌려주면 그 결과를 exit 0으로 바꾸거나 `--repo`를 빼지 않는다. schemaVersion 5 원장에는
|
||||
다음처럼 **대조 불가 자체를 영수증으로 남긴다.**
|
||||
|
||||
```text
|
||||
semanticId: evidence-repo
|
||||
status: UNVERIFIABLE
|
||||
exit: 3
|
||||
reason: source repository unavailable on current machine
|
||||
acceptedByProjectReview: true
|
||||
```
|
||||
|
||||
`verify-pipeline-run.py`는 v5부터 S3·S5·S6 각각에 `semanticId=evidence-repo` 관문이 정확히
|
||||
하나 있는지, 실제 명령에 `check_evidence.mjs <프로젝트> --repo`가 들어 있는지까지 확인한다.
|
||||
`UNVERIFIABLE`은 실패를 숨긴 PASS가 아니다. 실제 exit 3, 대조 불가 이유, 프로젝트 리뷰의
|
||||
명시적 수용이 모두 있을 때만 완료를 막지 않는 별도 상태다.
|
||||
|
||||
**노드가 `PROMOTE` 이고 `CONFIRMED` 인지 먼저 본다.** 아니면 쓰지 않는다.
|
||||
|
||||
**인용한 줄은 SSOT 에서 찾아 대조한다.** 앞선 기록에서 옮겨 적은 것은 확인한 것이 아니다 —
|
||||
@@ -129,6 +147,47 @@ node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로
|
||||
그림이 필요해 보이면 **`final/assets/` 에 이미 있는지부터 본다.** 계약의 `ssot-assets` 가 이
|
||||
글감에 배정한 그림이 있으면 그 파일을 그대로 가리킨다. 없을 때만 S4 로 넘긴다.
|
||||
|
||||
### S3-C — command-pedagogy 보조 흐름
|
||||
|
||||
S3가 쓴 기록은 command의 **기술적 정답**과 **사람이 따라갈 수 있는 표현**을 분리해서 본다.
|
||||
먼저 deterministic `initialAnalysis`를 만든다.
|
||||
|
||||
```bash
|
||||
python3 scripts/check-command-pedagogy.py <기록.md> \
|
||||
-o runs/<프로젝트>/<runId>/stage/S3/command-initial.json
|
||||
```
|
||||
|
||||
`initialAnalysis.shellBlocks == 0`이면 planner/editor/reviewer는 모두 `SKIPPED`다. shell block은
|
||||
있지만 finding이 0이면 planner/editor만 `SKIPPED`하고 reviewer는 S6 뒤 최종본을 본다.
|
||||
|
||||
finding이 하나라도 있으면 역할을 나눈다.
|
||||
|
||||
1. `command-pedagogy-planner`가 분석이 지목한 block만 대상으로 `CommandPlan`을 만든다.
|
||||
2. `command-pedagogy-editor`는 기록을 직접 다시 쓰지 않고 `CommandPatchSet`만 만든다.
|
||||
3. 아래 적용기로 patch를 적용한다.
|
||||
|
||||
```bash
|
||||
python3 scripts/apply-command-pedagogy-patch.py \
|
||||
<기록.md> <command-initial.json> <command-patch-set.json> \
|
||||
-o <수정본.md>
|
||||
```
|
||||
|
||||
적용기는 initial source hash, block id, block hash를 대조한다. 따라서 editor가 **command block 밖의 산문**을
|
||||
직접 바꾸는 경로가 없다. stale hash나 unknown block이면 적용하지 않고 기록을 다시 분석한다.
|
||||
|
||||
S5·S6이 끝난 뒤 최종 기록에 같은 분석을 다시 실행해 `finalAnalysis`를 남긴다. initial에 shell block이
|
||||
있었는데 final이 0이면 command를 없애서 문제를 숨긴 것으로 보고 실패한다. `finalAnalysis.majorFindings`
|
||||
(`majorFindings`)가 1 이상이어도 실패한다. minor finding은 전역 금지 규칙이 아니므로 reviewer가 문맥을 본다.
|
||||
|
||||
최종 shell/CLI block이 있으면 `command-pedagogy-reviewer`가 독립적으로 `PASS`해야 한다. 그 다음
|
||||
`fact-reviewer`가 command/prose/voice 변경이 모두 끝난 결과를 SSOT/evidence와 역대조해 `PASS`해야 한다.
|
||||
두 reviewer는 파일을 고치지 않는다.
|
||||
|
||||
원장 위치는 `qualityReviews.commandPedagogy.{initialAnalysis,finalAnalysis,planner,editor,reviewer}`와
|
||||
`qualityReviews.technicalEvidence`다. command/fact review 기본 계약은 schemaVersion 3부터 적용한다.
|
||||
|
||||
schemaVersion 4부터는 command lane의 first-class artifact도 강제한다. `initialAnalysis`/`finalAnalysis`와 DONE 상태의 planner/editor/reviewer는 repository 내부 JSON artifact의 `path`+`sha256` 영수증을 남긴다. `CommandPlan`과 `CommandPatchSet`은 각각 `schemas/command-plan.schema.json`, `schemas/command-patch-set.schema.json` 계약을 따르고 `scripts/validate-command-pedagogy-artifact.py`로 frozen analysis와 대조한다. command reviewer와 `technicalEvidence`의 `sourceSha256`은 모든 repair가 끝난 최종 기록 파일의 SHA256과 같아야 한다. v3에는 이 새 영수증을 소급 요구하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## S4 — 기록 → 그림
|
||||
|
||||
@@ -156,6 +156,92 @@ error 0 까지 고쳐라.
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함.
|
||||
```
|
||||
|
||||
### S3-C1 — initial command analysis
|
||||
|
||||
S3가 끝나면 항상 deterministic **initial command analysis**를 만든다.
|
||||
|
||||
```bash
|
||||
python3 scripts/check-command-pedagogy.py <기록.md> --mode <문서 mode> \
|
||||
-o runs/<프로젝트>/<runId>/stage/S3/command-initial.json
|
||||
```
|
||||
|
||||
shell/CLI block이 0이면 아래 세 command agent를 부르지 않고 원장의 planner/editor/reviewer를
|
||||
`SKIPPED`로 적는다. block은 있지만 finding이 0이면 planner/editor만 `SKIPPED`다.
|
||||
|
||||
### S3-C2 — CommandPlan (finding이 있을 때만)
|
||||
|
||||
```
|
||||
Agent(subagent_type="command-pedagogy-planner", prompt=<아래 command planner 프롬프트>)
|
||||
```
|
||||
|
||||
```text
|
||||
너는 command-pedagogy planner다.
|
||||
|
||||
먼저 .agents/skills/writing-practitioner-guides/SKILL.md 를 끝까지 읽고
|
||||
references/command-pedagogy.md 도 읽어라.
|
||||
|
||||
기록: <기록.md>
|
||||
initial command analysis: runs/<프로젝트>/<runId>/stage/S3/command-initial.json
|
||||
근거: <이 기록의 source가 가리키는 SSOT 절>
|
||||
|
||||
분석이 지목한 block만 계획해라. Markdown을 수정하지 마라.
|
||||
SSOT/evidence에 없는 alias, prerequisite, 성공 결과를 만들지 마라.
|
||||
compact syntax 자체를 금지하지 말고 문서 모드와 관찰 가능성으로 판단해라.
|
||||
|
||||
돌려줄 것: CommandPlan JSON + skillEcho.
|
||||
skillEcho는 writing-practitioner-guides/SKILL.md에서 원문 한 줄을 그대로 옮긴 것이다.
|
||||
```
|
||||
|
||||
CommandPlan을 `runs/<프로젝트>/<runId>/stage/S3/command-plan.json`에 저장한 뒤 frozen analysis와 검증한다.
|
||||
|
||||
```bash
|
||||
python3 scripts/validate-command-pedagogy-artifact.py plan \
|
||||
runs/<프로젝트>/<runId>/stage/S3/command-plan.json \
|
||||
--analysis runs/<프로젝트>/<runId>/stage/S3/command-initial.json
|
||||
```
|
||||
|
||||
### S3-C3 — bounded command editor (finding이 있을 때만)
|
||||
|
||||
```
|
||||
Agent(subagent_type="command-pedagogy-editor", prompt=<아래 command editor 프롬프트>)
|
||||
```
|
||||
|
||||
```text
|
||||
너는 command-pedagogy editor다.
|
||||
|
||||
먼저 .agents/skills/writing-practitioner-guides/SKILL.md 를 끝까지 읽고
|
||||
references/command-pedagogy.md 도 읽어라.
|
||||
|
||||
기록: <기록.md>
|
||||
initial command analysis: <command-initial.json>
|
||||
CommandPlan: <command-plan.json>
|
||||
근거: <이 기록의 source가 가리키는 SSOT 절>
|
||||
|
||||
기록 파일을 직접 수정하지 마라. frozen plan의 block_id에 대한 CommandPatchSet JSON만 만들어라.
|
||||
command block 밖의 산문, 기술 주장, target host/session, file meaning, security boundary를 바꾸지 마라.
|
||||
|
||||
돌려줄 것: CommandPatchSet JSON + skillEcho.
|
||||
```
|
||||
|
||||
CommandPatchSet을 `runs/<프로젝트>/<runId>/stage/S3/command-patch-set.json`에 저장하고 검증한다.
|
||||
|
||||
```bash
|
||||
python3 scripts/validate-command-pedagogy-artifact.py patch \
|
||||
runs/<프로젝트>/<runId>/stage/S3/command-patch-set.json \
|
||||
--analysis runs/<프로젝트>/<runId>/stage/S3/command-initial.json
|
||||
```
|
||||
|
||||
editor 결과는 에이전트가 직접 적용하지 않는다. host orchestrator가 bounded applier를 쓴다.
|
||||
|
||||
```bash
|
||||
python3 scripts/apply-command-pedagogy-patch.py \
|
||||
<기록.md> <command-initial.json> <command-patch-set.json> \
|
||||
-o /tmp/command-repaired.md
|
||||
mv /tmp/command-repaired.md <기록.md>
|
||||
```
|
||||
|
||||
그 다음 S3 관문을 다시 실행하고 S4로 간다.
|
||||
|
||||
---
|
||||
|
||||
## S4 — 기록 → 그림
|
||||
@@ -270,6 +356,102 @@ check_voice.mjs 는 목소리가 모자란지 재지 않는다. 지어낸 목소
|
||||
돌려줄 것: 위 JSON 형식. skillEcho 포함. 흔적이 없었으면 status DONE 에 notes 로 적어라.
|
||||
```
|
||||
|
||||
### R1 — final command analysis + independent command review
|
||||
|
||||
S6가 끝나면 **final command analysis**를 다시 만든다.
|
||||
|
||||
```bash
|
||||
python3 scripts/check-command-pedagogy.py <기록.md> --mode <initial과 같은 문서 mode> \
|
||||
-o runs/<프로젝트>/<runId>/review/command-final.json
|
||||
```
|
||||
|
||||
initial analysis에 shell block이 있었는데 final이 0이면 멈춘다. final `majorFindings`가 남아도
|
||||
멈춘다. final shell/CLI block이 하나라도 있으면 다음 reviewer를 부른다.
|
||||
|
||||
```
|
||||
Agent(subagent_type="command-pedagogy-reviewer", prompt=<아래 command reviewer 프롬프트>)
|
||||
```
|
||||
|
||||
```text
|
||||
너는 final command-pedagogy reviewer다. 파일을 고치지 마라.
|
||||
|
||||
먼저 .agents/skills/writing-practitioner-guides/SKILL.md 를 끝까지 읽고
|
||||
references/command-pedagogy.md 도 읽어라.
|
||||
|
||||
최종 기록: <기록.md>
|
||||
initial command analysis: <command-initial.json>
|
||||
final command analysis: <command-final.json>
|
||||
CommandPlan: <있으면 command-plan.json, 없으면 null>
|
||||
근거: <이 기록의 source가 가리키는 SSOT/evidence>
|
||||
|
||||
최종 command가 기술적으로 같은 일을 하면서 사람이 실행·관찰·진단할 수 있는지 독립적으로 판정해라.
|
||||
직접 수정하지 마라. PASS / FAIL / UNCERTAIN 중 하나만 낸다.
|
||||
FAIL과 UNCERTAIN은 acceptance를 막는다.
|
||||
|
||||
돌려줄 것: reviewer, verdict, findings, notes + skillEcho.
|
||||
```
|
||||
|
||||
### R2 — final technical-evidence review
|
||||
|
||||
command/prose/voice 수정이 모두 끝난 뒤 마지막으로 fact reviewer를 부른다. command가 없는 글도
|
||||
이 검토는 생략하지 않는다.
|
||||
|
||||
```
|
||||
Agent(subagent_type="fact-reviewer", prompt=<아래 fact reviewer 프롬프트>)
|
||||
```
|
||||
|
||||
```text
|
||||
너는 최종 technical-evidence reviewer다. 파일을 고치지 마라.
|
||||
|
||||
최종 기록: <기록.md>
|
||||
SSOT: docs/<프로젝트>/final/document.md
|
||||
추가 evidence: <tech-log-tree node가 가리키는 증거와 원본 가이드 경로>
|
||||
|
||||
모든 command repair, prose rewrite, voice edit가 끝난 이 최종본을 원문과 역대조해라.
|
||||
수치·단위·경로 결합·미검증→확정 전환·유무 오기·비밀 노출을 본다.
|
||||
|
||||
돌려줄 것은 fact-reviewer 계약의 VERDICT: PASS | FAIL 형식이다.
|
||||
PASS만 S7로 갈 수 있다.
|
||||
```
|
||||
|
||||
두 결과를 각각 `qualityReviews.commandPedagogy.reviewer`와
|
||||
`qualityReviews.technicalEvidence`에 적은 뒤 S7로 간다.
|
||||
|
||||
|
||||
### R3 — schemaVersion 4 artifact / hash receipt
|
||||
|
||||
v4 원장은 “호출했다”는 문자열만으로 command lane을 통과시키지 않는다. 아래 JSON artifact를
|
||||
repository 안의 run 디렉터리에 보존하고 각각의 **repo-relative path + sha256**을 `run.json`에 적는다.
|
||||
|
||||
- `command-initial.json` → `qualityReviews.commandPedagogy.initialAnalysis.artifact`
|
||||
- `command-plan.json` → planner가 DONE일 때 `planner.artifact`
|
||||
- `command-patch-set.json` → editor가 DONE일 때 `editor.artifact`
|
||||
- `command-final.json` → `finalAnalysis.artifact`
|
||||
- `command-review.json` → reviewer가 DONE일 때 `reviewer.artifact`
|
||||
|
||||
영수증 형식은 다음이다.
|
||||
|
||||
```json
|
||||
{"path":"runs/<프로젝트>/<runId>/review/command-final.json","sha256":"<64 hex>"}
|
||||
```
|
||||
|
||||
파일을 저장한 뒤 `sha256sum <artifact>`로 실제 digest를 구한다. planner/editor를 조건상 SKIPPED한
|
||||
경우 해당 `artifact`는 `null`이다. command reviewer를 실행했다면 reviewer 결과 JSON에는
|
||||
`source_sha256`을 넣고, `run.json`의 reviewer `sourceSha256`에도 **최종 기록 파일의 SHA256**을
|
||||
같이 적는다.
|
||||
|
||||
```bash
|
||||
sha256sum <기록.md>
|
||||
sha256sum runs/<프로젝트>/<runId>/stage/S3/command-initial.json
|
||||
sha256sum runs/<프로젝트>/<runId>/review/command-final.json
|
||||
```
|
||||
|
||||
`fact-reviewer`도 같은 최종 기록을 검토했다는 증거로
|
||||
`qualityReviews.technicalEvidence.sourceSha256`에 동일한 최종 기록 SHA256을 적는다. 그 뒤에 기록
|
||||
파일을 한 글자라도 바꾸면 reviewer/fact-review를 다시 실행해야 한다.
|
||||
|
||||
schemaVersion 3 원장은 이 artifact/hash 필드가 생기기 전 계약이므로 소급해서 채우지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## S7 — Studio 저장
|
||||
|
||||
Reference in New Issue
Block a user