refactor: 문서 개선 중
This commit is contained in:
donghyeon-ka
@@ -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