feat: 가상화 문서들 추가

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

@@ -0,0 +1,160 @@
+---
+name: running-tech-log-pipeline
+description: Use when a codebase must go all the way to a saved Tech Log Studio draft — running the seven stages (SSOT, tree, record, diagram, prose, voice, Studio save) as separate subagents, one skill per stage, with a run ledger that records which skill each stage actually used and which gate it passed.
+---
+
+# Tech Log 파이프라인 실행
+
+## 이 스킬이 하는 일
+
+스킬 일곱 개를 **한 줄기로 잇는다.** 각 스킬은 자기 단계만 알고 앞뒤를 모른다. 이 스킬이
+단계 사이의 인계물과 순서와 관문을 정하고, 단계마다 **서브에이전트를 하나씩 띄운다.**
+
+한 실행이 남기는 것은 산출물과 **런 원장**(`runs/<프로젝트>/<runId>/run.json`) 둘이다.
+원장은 단계마다 어떤 스킬을 실제로 읽었고 어떤 관문을 어떤 종료 코드로 지났는지를 적는다.
+`python3 scripts/verify-pipeline-run.py <원장>` 이 그 원장을 검사한다.
+
+**원장이 이 스킬의 존재 이유다.** 스킬을 안 읽고 쓴 글과 읽고 쓴 글은 결과물만 봐서는
+구분되지 않는다. 원장은 그것을 기계가 구분할 수 있게 만든다.
+
+## 왜 단계마다 서브에이전트인가
+
+한 세션이 일곱 단계를 이어서 하면 앞 단계의 문맥이 뒤 단계로 새어 든다. 그러면 세 가지가
+망가진다.
+
+- **스킬을 안 읽고도 그럴듯하게 쓴다.** 3단계에서 본문 규칙을 읽었으니 5단계에서
+  `rewriting-technical-prose-naturally` 를 열지 않아도 문장이 나온다. 스킬이 적용됐는지
+  확인할 방법이 사라진다.
+- **관문이 형식이 된다.** 자기가 쓴 글을 자기가 검사하면 실패를 「이건 예외」로 넘긴다.
+- **어디서 어긋났는지 못 찾는다.** 결과가 이상할 때 일곱 단계 중 어디가 원인인지 가릴 수 없다.
+
+서브에이전트는 **자기 단계의 입력 파일과 자기 스킬만** 받는다. 다른 단계가 무엇을 했는지
+모른다. 그래서 스킬을 안 읽으면 못 쓰고, 못 쓰면 원장에 남는다.
+
+## 일곱 단계
+
+| # | 단계 | 스킬 | 산출물 |
+|---|---|---|---|
+| S1 | 코드베이스 → SSOT | `analyzing-codebase-for-tech-log` | `docs/<프로젝트>/final/document.md` |
+| S2 | SSOT → 분해 계약 | `deriving-tech-log-root-tree` | `docs/<프로젝트>/tech-log-studio/tech-log-tree.json` |
+| S3 | 글감 → 기록 | `writing-tech-log-records` | `.../<주제>/<종류>/<기록>.md` |
+| S4 | 기록 → 그림 | `technical-visualizer` | `final/assets/<이름>/` · `final/.techviz/<이름>/` |
+| S5 | AI 티 제거 | `rewriting-technical-prose-naturally` | 같은 기록 파일 (제자리 수정) |
+| S6 | 일한 사람의 목소리 | `writing-as-the-person-who-did-it` | 같은 기록 파일 (제자리 수정) |
+| S7 | Studio 저장 | `publishing-tech-log-to-studio` | Studio 작업본 + `studio:` URL. **게시하지 않는다** |
+
+단계마다의 입력·관문·원장 칸은 [references/stage-contracts.md](references/stage-contracts.md).
+서브에이전트에 그대로 넣는 프롬프트는 [references/subagent-prompts.md](references/subagent-prompts.md).
+
+## 순서가 고정된 곳
+
+세 자리는 바꾸면 결과가 틀어진다.
+
+**S3 → S4.** 그림은 기록을 쓴 다음에 만든다. 무엇을 그릴지는 기록 본문이 정하고
+(`writing-tech-log-records/references/choosing-a-diagram.md` 의 세 관문), 그림의 근거는 그
+기록의 `source` 앵커가 가리키는 SSOT 절이다. **기록 본문이 그림의 소재를 고르고, SSOT 절이
+그림의 사실을 댄다.** 기록 `.md` 를 `techviz prepare` 에 넣지 않는다 — 기록은 SSOT 의 인용이라
+줄 번호가 근거가 되지 못한다.
+
+**S4 → S5 → S6.** 문장 손질은 본문이 다 찬 뒤에 한다. 그림을 붙이면 본문에 그림을 읽는 문단이
+한둘 늘고, 그 문단도 같은 손질을 받아야 한다. S5 가 먼저다 — 번역투와 반복 문형을 걷어낸 뒤라야
+S6 이 채울 자리(선택·비교·어긋남)가 보인다. 순서를 뒤집으면 S5 가 S6 이 넣은 목소리를
+「과한 대구」로 다시 깎는다.
+
+**S6 → S7.** Studio 에는 문장 손질이 끝난 것만 넣는다. 저장한 뒤에 고치면 Studio 쪽 `version`
+이 올라가고 검증 산출물이 무효가 된다.
+
+## S5·S6 뒤에는 S3 관문을 다시 돌린다
+
+문장을 고치면 본문 문법과 인용이 함께 움직인다. `check_prose` 가 error 0 이어도 `check_body`
+가 깨지거나, 고쳐 쓴 코드블록 한 줄이 SSOT 와 달라져 `check_evidence` 가 걸린다.
+
+```bash
+python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
+node --experimental-transform-types \
+  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
+node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
+```
+
+원장에서는 이것이 S5·S6 의 관문이지 S3 의 재실행이 아니다.
+
+## 건너뛰어도 되는 단계
+
+이미 있는 것을 다시 만들지 않는다. 건너뛴 단계도 **원장에 `SKIPPED` 와 사유를 적는다.**
+적지 않고 빠뜨린 것과 판단해서 건너뛴 것을 구분해야 한다.
+
+| 단계 | 건너뛰는 조건 |
+|---|---|
+| S1 | `final/document.md` 가 있고 그 안에서 이 글감의 근거를 찾을 수 있다 |
+| S2 | `tech-log-tree.json` 에 이 글감이 `PROMOTE` · `CONFIRMED` 로 이미 있다 |
+| S4 | 그림이 필요 없다(세 관문에 걸린다) 또는 `ssot-assets` 가 배정한 그림이 이미 있다 |
+| S7 | 사용자가 Studio 반입을 요청하지 않았다 |
+
+**S3·S5·S6 은 건너뛰지 않는다.** 기록을 쓰는 단계와 문장을 고치는 두 단계는 이 파이프라인의
+산출물 자체다.
+
+## 실행 절차
+
+### 0. 런을 연다
+
+```bash
+python3 scripts/verify-pipeline-run.py --init runs/<프로젝트>/<runId>/run.json \
+  --project <프로젝트> --record <기록 경로>
+```
+
+`runId` 는 `YYYY-MM-DD-HHMM` 이다. 원장의 틀은
+[templates/run.json](templates/run.json) 이고, `--init` 이 그 틀을 채워 놓는다.
+
+### 1. 단계마다 서브에이전트를 띄운다
+
+프롬프트는 [references/subagent-prompts.md](references/subagent-prompts.md) 의 것을 쓴다.
+프롬프트에 **반드시** 들어가야 하는 넷이 있다.
+
+1. **스킬 이름과 「먼저 그 SKILL.md 를 끝까지 읽어라」** — 요약을 주지 않는다. 요약을 주면
+   에이전트가 스킬을 안 연다.
+2. **자기 단계의 입력 파일 경로만.** 앞 단계가 무엇을 했는지 설명하지 않는다.
+3. **관문 명령 원문과 「error 0 까지 고쳐라」.**
+4. **스킬 영수증** — 그 SKILL.md 에서 자기 단계에 해당하는 규칙 한 줄을 **원문 그대로**
+   인용해 돌려보내게 한다. 이것이 스킬을 열었다는 기계 검증 가능한 증거다
+   (`verify-pipeline-run.py` 가 그 문자열이 실제 SKILL.md 안에 있는지 대조한다).
+
+한 단계가 끝나면 그 결과를 원장에 적고 다음 단계를 띄운다. **단계를 병렬로 띄우지 않는다** —
+S1~S7 은 앞 단계의 산출물이 뒤 단계의 입력이다. 병렬이 되는 것은 같은 단계 안에서
+**서로 다른 기록 여러 건**을 처리할 때뿐이다.
+
+### 2. 원장을 검사한다
+
+```bash
+python3 scripts/verify-pipeline-run.py runs/<프로젝트>/<runId>/run.json
+```
+
+error 0 이어야 런이 끝난 것이다. 이 검사기가 보는 것은 결과물의 품질이 아니라 **절차의
+준수**다 — 단계가 빠졌는지, 스킬 영수증이 그 스킬의 실제 문장인지, 관문이 돌았고 종료 코드가
+0 이었는지, 적어 낸 산출물이 디스크에 있는지.
+
+### 3. 프로젝트 검사기를 돌린다
+
+```bash
+python3 scripts/verify-tech-log-tree.py <프로젝트>
+python3 scripts/verify-project-layout.py <프로젝트>
+python3 scripts/audit-records.py <프로젝트>
+python3 scripts/check-figure-text.py <프로젝트>
+```
+
+## 이 스킬이 하지 않는 것
+
+- **판단을 대신하지 않는다.** 어떤 후보를 `PROMOTE` 할지, 그림이 필요한지, 어떤 종류인지는
+  각 단계의 스킬이 정한다. 이 스킬은 그 스킬이 실제로 불렸는지만 본다.
+- **관문을 완화하지 않는다.** 관문이 error 를 내면 그 단계는 끝나지 않은 것이다. 원장에
+  `FAILED` 로 적고 멈춘다. 다음 단계로 넘기지 않는다.
+- **게시하지 않는다.** S7 은 저장까지다. 게시는 사람이 공개 화면을 보고 판단한다.
+
+## 자주 어긋나는 자리
+
+| 증상 | 원인 | 원장에 남는 모습 |
+|---|---|---|
+| 문장이 여전히 AI 같다 | S5 를 같은 세션이 겸했다 | `skillEcho` 가 비었거나 SKILL.md 에 없는 문장 |
+| 그림 안에 문장이 있다 | S4 가 `check-figure-text.py` 를 안 돌렸다 | 관문 목록에 그 명령이 없다 |
+| SSOT 에 없는 인용이 있다 | S3 이 앞 기록에서 코드를 옮겨 적었다 | `check_evidence` 종료 코드 ≠ 0 |
+| 기록이 색인에 없다 | S2 를 건너뛰고 S3 을 했다 | S2 가 `SKIPPED` 인데 사유가 없다 |
+| Studio 에서 그림이 안 보인다 | S7 이 Asset 을 올리기 전에 본문을 넣었다 | S7 관문에 미리보기 확인이 없다 |

.agents/skills/running-tech-log-pipeline/references/stage-contracts.md

@@ -0,0 +1,254 @@
+# 단계 계약
+
+단계마다 넷을 정한다 — **입력 · 스킬 · 관문 · 산출물.** 원장에 적히는 것도 이 넷이다.
+
+관문은 종료 코드가 0 이어야 지난 것이다. 0 이 아니면 그 단계는 `FAILED` 이고 다음 단계로
+넘어가지 않는다.
+
+---
+
+## S1 — 코드베이스 → SSOT
+
+| | |
+|---|---|
+| 스킬 | `analyzing-codebase-for-tech-log` |
+| 입력 | 분석 대상 저장소 경로(사용자가 준다) · 그 저장소의 `AGENTS.md`(있으면) |
+| 산출물 | `docs/<프로젝트>/final/document.md` |
+| 관문 | `python3 scripts/verify-project-layout.py <프로젝트>` |
+
+**분석 대상 저장소는 이 저장소 밖이다.** `docs/<프로젝트>` 는 이 저장소 기준이고, 분석 대상은
+사용자가 준 절대 경로다. 두 저장소를 섞지 않는다 — 대상 저장소를 고치지 않는다.
+
+**`analysis-queue.yaml` 은 여러 프로젝트를 줄 세울 때만 쓴다.** 사용자가 저장소 하나를
+지목했으면 큐 없이 그 하나를 분석한다. 큐가 있으면 큐가 정한 활성 프로젝트를 따른다.
+
+작업 재료(`analysis/` · `notes/` · `checkpoints/` · `state.json` · `source-index.md`)는 분석
+중에만 있고, 끝나면 `final/document.md` 로 합치고 지운다.
+
+```bash
+python3 scripts/fold-analysis-into-final.py <프로젝트>
+```
+
+**S2 가 무엇을 기대하는지 알고 쓴다.** S2 는 `final/document.md` 를 절 단위로 훑어 후보를
+찾는다. 절 제목이 무엇을 다루는지 말하지 않으면 후보가 안 잡힌다. 접어 넣은 문서라면
+제1부(통합 분석)가 후보 범위이고 제2·3부는 근거다.
+
+산출물이 이미 있고 이 글감의 근거가 그 안에 있으면 `SKIPPED` 로 적고 사유를 남긴다.
+
+### 이미 접어 넣은 프로젝트를 다시 볼 때 — 대조 모드
+
+`final/document.md` 가 이미 있는 프로젝트에 S1 을 다시 돌리는 것은 **분석이 아니라 대조**다.
+스킬의 절차(작업 재료를 만들고 → 분석하고 → 접어 넣는다)를 그대로 밟으면 두 곳이 깨진다.
+
+- `docs/<프로젝트>/` 에 `state.json`·`analysis/` 를 만들면 배치 검사기가 error 로 센다.
+  완료된 프로젝트의 폴더는 `final/` 과 `tech-log-studio/` 뿐이다.
+- `final/document.md` 를 고치면 `ssotSha256` 이 어긋나 분해 계약이 통째로 무효가 된다.
+
+그래서 대조 모드는 이렇게 돈다.
+
+| | 분석 모드 | 대조 모드 |
+|---|---|---|
+| 작업 재료 | `docs/<프로젝트>/analysis/` | `runs/<프로젝트>/<runId>/stage/S1/` |
+| SSOT | 만들거나 접어 넣는다 | **고치지 않는다.** 보강 후보만 적는다 |
+| 끝 조건 | fold 하고 재료를 지운다 | 어긋난 것·빠진 것을 목록으로 남긴다 |
+
+SSOT 가 코드와 **어긋나는** 것을 찾으면 그것은 보강 후보가 아니다. 크게 적고 사람에게
+올린다 — 이미 그 SSOT 를 근거로 쓴 기록이 있기 때문이다.
+
+---
+
+## S2 — SSOT → 분해 계약
+
+| | |
+|---|---|
+| 스킬 | `deriving-tech-log-root-tree` |
+| 입력 | `docs/<프로젝트>/final/document.md` **하나** |
+| 산출물 | `docs/<프로젝트>/tech-log-studio/tech-log-tree.json` |
+| 관문 | `python3 scripts/build-tech-log-tree.py <프로젝트>` → `python3 scripts/verify-tech-log-tree.py <프로젝트>` (error 0) |
+
+`analysis/**` 를 후보를 찾으려고 열지 않는다. 분석에만 있는 자료를 발견하면 `final/document.md`
+를 먼저 보강한다.
+
+**검사기나 계약이 요구하는데 스킬의 절차가 안 적는 칸이 있다.** 손으로 채운다.
+
+| 칸 | 무엇 |
+|---|---|
+| `candidateScope` | 후보를 찾은 범위. 적지 않으면 모듈 분석 절 제목이 전부 글감이 된다 |
+| `sourceRepository` | 분석한 저장소의 경로·리비전·그렇게 판단한 근거. 모르면 `null`, 지어내지 않는다 |
+| `ssotSha256` | `build-tech-log-tree.py` 가 채운다. 그래서 build 를 먼저 돌리고 verify 를 돌린다 |
+| `ssot-assets` · `ssot-evidence` | SSOT 가 이미 그린 그림과 이미 돌린 측정을 글감에 배정한다. 계약 문서에만 있고 절차에는 이 단계가 없다 |
+| `candidateScope.excludedAnchorPattern` | 「범위 밖 글감」 검사가 이 칸으로 판정한다. 없으면 그 검사가 통째로 꺼진다 |
+
+`assetLedger` 는 계약이 요구하지만 스크립트 어느 것도 읽지 않는다. 사람이 보는 칸이다.
+
+**`source` 앵커의 형식이 어디에도 적혀 있지 않다.** keycloak 은 「h2 슬러그 + `-ap1`」 같은
+합성 앵커를 쓰고, 제목 슬러그를 쓴 프로젝트도 있다. 검사기는 SSOT 경로를 포함하는지만 보고
+실재하는 heading 으로 풀지 않는다. **한 프로젝트 안에서는 한 형식으로 통일한다** — S4 가
+`--heading` 값을 이 앵커에서 옮기기 때문이다.
+
+**검사기는 「후보 ↔ 글감」만 본다. 「SSOT ↔ 후보」는 안 본다.** 그래서 SSOT 에 있는 재료를
+후보 대장에 올리지도 않고 지나쳐도 error 가 0 이다. 범위의 절을 끝까지 읽는 것은 사람의 일이다.
+
+제외가 0 건인 분해는 선별하지 않은 분해다. 후보마다 처분(`PROMOTE`·`MERGE_INTO`·
+`KEEP_IN_SSOT`·`NEEDS_EVIDENCE`·`NEEDS_DECISION`)을 적고, 사람이 다시 읽은 것만
+`dispositionReview: CONFIRMED` 로 둔다.
+
+---
+
+## S3 — 글감 → 기록
+
+| | |
+|---|---|
+| 스킬 | `writing-tech-log-records` |
+| 입력 | `tech-log-tree.json` 의 노드 하나 · 그 노드의 `source` 앵커가 가리키는 SSOT 절 |
+| 산출물 | `docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<기록>.md` |
+| 관문 | 아래 셋 |
+
+```bash
+python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
+node --experimental-transform-types \
+  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
+node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
+node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
+```
+
+**노드가 `PROMOTE` 이고 `CONFIRMED` 인지 먼저 본다.** 아니면 쓰지 않는다.
+
+**인용한 줄은 SSOT 에서 찾아 대조한다.** 앞선 기록에서 옮겨 적은 것은 확인한 것이 아니다 —
+그렇게 게시된 기록에 SSOT 와 다른 redirect URI 가 네 곳 있었다.
+
+그림이 필요해 보이면 **`final/assets/` 에 이미 있는지부터 본다.** 계약의 `ssot-assets` 가 이
+글감에 배정한 그림이 있으면 그 파일을 그대로 가리킨다. 없을 때만 S4 로 넘긴다.
+
+---
+
+## S4 — 기록 → 그림
+
+| | |
+|---|---|
+| 스킬 | `technical-visualizer` |
+| 입력 | S3 이 쓴 기록 `.md`(무엇을 그릴지) · 그 기록의 `source` 앵커가 가리키는 SSOT 절(그림의 사실) |
+| 산출물 | `final/.techviz/<이름>/{context.json,prompt.md,spec.json}` · `final/assets/<이름>/` |
+| 관문 | `techviz lint` · `check-figure-text.py` · `check-figure-overlap.py` · `preview-figure.py` 로 눈 확인 |
+
+**입력이 둘이라는 것이 이 단계의 전부다.**
+
+- **무엇을 그릴지는 기록 본문이 정한다.** 세 관문(자리가 Case·Concept 인가 · 표가 아닌가 ·
+  옆 문단이 이미 말하지 않았는가)을 지나야 그린다. 그리고 **그림이 주장하는 것을 기록 본문이
+  말해야 한다.** 본문이 안 적은 단계를 그림만 넣으면 설명 없는 주장이 남는다. 순서는
+  본문을 먼저 보강하고 그다음 그림을 붙인다.
+- **그림의 사실은 SSOT 절이 댄다.** 기록은 SSOT 의 인용이라 줄 번호가 근거가 되지 못한다.
+  `techviz prepare` 에는 `final/document.md` 를 넣고, 절은 기록의 `source` 앵커로 지목한다.
+
+```bash
+./scripts/techviz prepare docs/<프로젝트>/final/document.md \
+  --heading "<기록의 source 앵커가 가리키는 절 제목>" \
+  -o docs/<프로젝트>/final/.techviz/<이름>/context.json
+```
+
+`--line` 은 쓰지 않는다. context 는 관리 블록을 접은 좌표를 쓰므로 파일 줄 번호와 어긋난다.
+
+**그림 안에는 이름만 넣는다.** 문장은 `<desc>` 와 옆 문단에 둔다. lint 는 이것을 못 잡는다 —
+`check-figure-text.py` 가 잡는다.
+
+**lint 는 좌표를 안 본다.** 관계가 이어져 있는지만 본다. 그래서 구역 둘이 겹쳐 그려지거나
+라벨이 상자에 먹혀도 통과한다. `check-figure-overlap.py` 가 그것을 본다.
+
+```bash
+python3 scripts/check-figure-overlap.py <프로젝트>
+python3 scripts/check-figure-overlap.py --file 그림.svg
+```
+
+**그래도 마지막에는 눈으로 본다.** 검사기가 보는 것은 배경 사각형의 좌표라, 글자가 상자
+밖으로 조금 나가거나 화살표가 라벨을 지나는 것은 못 잡는다.
+
+기록에 되적는다 — frontmatter `assets:` 에 `key` 와 `file`(=`final/assets/<이름>/<이름>.svg`)
+을 적고, 본문에는 마크다운 이미지로 넣는다. `:::evidence` 는 저장소에 쓰지 않는다. 사본을
+`tech-log-studio/` 쪽에 두지 않는다 — 사본에는 `.techviz/<이름>/` 이 없어 다시 못 만든다.
+
+---
+
+## S5 — AI 티 제거
+
+| | |
+|---|---|
+| 스킬 | `rewriting-technical-prose-naturally` |
+| 입력 | S3·S4 를 지난 기록 `.md` (제자리 수정) |
+| 산출물 | 같은 파일 |
+| 관문 | `check_prose.mjs` error 0 · `style_profile.mjs` · S3 관문 재실행 |
+
+```bash
+S=.agents/skills/rewriting-technical-prose-naturally/scripts
+node $S/check_prose.mjs --warn <기록.md>      # error 0 까지 고친다
+node $S/style_profile.mjs <기록.md>
+```
+
+문서 전체를 다시 쓴 것이 아니면 `--doc` 을 빼고 부른다.
+
+**`density.mjs` 는 본문이 있는 종류에만 건다.** 그 기준은 글 한 편(낱말 1277+ · 코드블록 1+ ·
+수치 13+)을 잰 값이고, Reference·Question·Decision 은 칸이 평문이라 코드블록을 넣는 것 자체가
+규칙 위반이다. 본문 없는 종류에 걸면 구조적으로 통과할 수 없는 관문이 되고, 통과시키려면
+없는 측정값을 지어내야 한다.
+
+**문체 수치를 맞추려고 문장을 넣지 않는다.** 검사기는 표면 패턴만 보고 뜻은 못 본다.
+
+**보호 구간을 건드리지 않는다** — 수치·날짜·버전·단위·코드·명령어·URL·직접 인용·공식 명칭은
+원문과 한 글자도 달라지면 안 된다. 그래서 문장을 고친 뒤 `check_evidence.mjs` 를 다시 돌린다.
+
+---
+
+## S6 — 일한 사람의 목소리
+
+| | |
+|---|---|
+| 스킬 | `writing-as-the-person-who-did-it` |
+| 입력 | S5 를 지난 기록 `.md` · **그리고 그 기록의 상류 자료** (SSOT · 커밋 메시지 · 주석 · `확인하지 못한 것` 칸) |
+| 산출물 | 같은 파일 |
+| 관문 | `check_voice.mjs` · `check_prose.mjs` 재실행 · S3 관문 재실행 |
+
+```bash
+node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
+node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
+```
+
+**S5 다음이다.** 번역투와 반복 문형을 걷어낸 뒤라야 채울 자리가 보인다. 그리고 이 스킬이
+넣은 문장을 `check_prose` 가 다시 본다 — 그래서 재실행이 관문이다.
+
+**자료에 흔적이 없으면 이 단계는 여기서 끝난다.** 없는 사람을 만들지 않는다. 「처음에는」·
+「고민 끝에」·「놀랍게도」를 자료 없이 쓰면 지어낸 것이다. 원장에는 `DONE` 에 「흔적 없음」을
+적는다 — `SKIPPED` 가 아니다. 찾아봤다는 것이 이 단계의 일이다.
+
+**`check_voice.mjs` 는 목소리가 모자란지 재지 않는다.** 지어낸 목소리를 잡는다. 조용하다고
+목소리가 생긴 것은 아니다.
+
+---
+
+## S7 — Studio 저장
+
+| | |
+|---|---|
+| 스킬 | `publishing-tech-log-to-studio` |
+| 입력 | S6 을 지난 기록 `.md` · frontmatter `assets:` 가 가리키는 SVG |
+| 산출물 | Studio 작업본. 기록 frontmatter 의 `id`·`studio:` |
+| 관문 | 상태 레일이 `저장됨` · `python3 scripts/build-tech-log-tree.py` → `verify-tech-log-tree.py` |
+
+**저장까지다. 게시하지 않는다.**
+
+Asset 을 본문보다 먼저 올린다. 순서를 뒤집으면 미리보기가 본문 전체를 막는다.
+
+바뀐 것이 없으면 저장 버튼을 누르지 않는다 — 누를 때마다 `version` 이 올라가고 앞서 만든
+검증·미리보기 산출물이 무효가 된다.
+
+---
+
+## 관문 요약
+
+| 단계 | 명령 |
+|---|---|
+| S1 | `verify-project-layout.py <프로젝트>` |
+| S2 | `build-tech-log-tree.py` → `verify-tech-log-tree.py` (error 0) |
+| S3 | `studio-body.py` → `check_body.mjs` · `check_prose.mjs` · `check_evidence.mjs --repo` |
+| S4 | `techviz lint` · `check-figure-text.py` · `check-figure-overlap.py` · `preview-figure.py` (눈 확인) |
+| S5 | `check_prose.mjs` (error 0) · `style_profile.mjs` · S3 관문 |
+| S6 | `check_voice.mjs` · `check_prose.mjs` · S3 관문 |
+| S7 | `저장됨` 확인 · `build-tech-log-tree.py` → `verify-tech-log-tree.py` |

.agents/skills/running-tech-log-pipeline/references/subagent-prompts.md

@@ -0,0 +1,275 @@
+# 서브에이전트 프롬프트
+
+단계마다 에이전트를 하나 띄운다. 아래를 그대로 쓰고 `<...>` 만 바꾼다.
+
+## 모든 프롬프트에 들어가는 넷
+
+1. **스킬 이름과 「SKILL.md 를 끝까지 먼저 읽어라」.** 요약을 주지 않는다. 요약을 주면
+   스킬을 안 연다.
+2. **자기 단계의 입력 경로만.** 앞 단계가 무엇을 했는지 설명하지 않는다.
+3. **관문 명령 원문.** 「검사해라」가 아니라 붙여 넣을 수 있는 명령을 준다.
+4. **스킬 영수증** — SKILL.md 에서 한 줄을 **원문 그대로** 인용해 돌려보내게 한다.
+   `verify-pipeline-run.py` 가 그 문자열이 실제 파일 안에 있는지 대조한다.
+
+## 돌려받는 형식 (모든 단계 공통)
+
+```json
+{
+  "stage": "S3",
+  "skill": "writing-tech-log-records",
+  "skillEcho": "<SKILL.md 에서 그대로 옮긴 한 줄>",
+  "status": "DONE",
+  "outputs": ["docs/keycloak/tech-log-studio/.../case-x.md"],
+  "gates": [{"cmd": "node ... check_body.mjs /tmp/studio-body.md", "exit": 0}],
+  "notes": "<판단한 것과 못 한 것>"
+}
+```
+
+`skillEcho` 를 지어내지 말라고 프롬프트에 적는다. 파일에 없는 문장이면 검사기가 잡는다.
+
+## 파일을 쓰라고 할 때는 방법을 함께 준다
+
+서브에이전트의 `Write` 는 「보고는 파일이 아니라 글로 돌려라」는 기본 정책에 막힐 수 있다.
+S1 처럼 산출물이 `.md` 인 단계는 그래서 한 줄을 더한다.
+
+```
+파일을 쓸 때 Write 툴이 막히면 Bash heredoc (`cat > 경로 <<'EOF'`) 을 써라.
+```
+
+이것을 안 적으면 에이전트가 산출물을 만들지 못하고 본문에 통째로 붙여 돌려준다.
+
+---
+
+## S1 — 코드베이스 → SSOT
+
+```
+너는 Tech Log 파이프라인의 1단계를 맡는다.
+
+먼저 .agents/skills/analyzing-codebase-for-tech-log/SKILL.md 를 끝까지 읽어라.
+references/ 아래 문서도 그 스킬이 읽으라는 것을 읽어라. 요약본은 주지 않는다.
+
+대상 저장소: <절대 경로>
+쓸 곳: docs/<프로젝트>/
+
+analysis-queue.yaml 이 없으면 이 저장소 하나만 분석한다. 큐가 없다는 이유로 멈추지 마라.
+대상 저장소를 고치지 마라. 읽기만 한다.
+
+끝나면 분석 재료를 SSOT 로 합쳐라:
+  python3 scripts/fold-analysis-into-final.py <프로젝트>
+합친 뒤 analysis/ · notes/ · checkpoints/ · state.json · source-index.md 를 지운다.
+
+관문:
+  python3 scripts/verify-project-layout.py <프로젝트>
+error 0 이 될 때까지 고쳐라.
+
+돌려줄 것 (JSON):
+  stage, skill, skillEcho, status, outputs, gates, notes
+skillEcho 는 방금 읽은 SKILL.md 에서 네 작업에 해당하는 규칙 한 줄을 원문 그대로 옮긴 것이다.
+지어내지 마라 — 파일에 그 문자열이 있는지 기계가 대조한다.
+```
+
+---
+
+## S2 — SSOT → 분해 계약
+
+```
+너는 Tech Log 파이프라인의 2단계를 맡는다.
+
+먼저 .agents/skills/deriving-tech-log-root-tree/SKILL.md 를 끝까지 읽어라.
+references/candidate-disposition.md 와 references/decomposition-checklist.md 도 읽어라.
+출력 계약은 .agents/skills/writing-tech-log-records/references/tech-log-tree-contract.md 다.
+
+입력: docs/<프로젝트>/final/document.md — 이것 하나다.
+analysis/** 를 후보를 찾으려고 열지 마라.
+
+출력: docs/<프로젝트>/tech-log-studio/tech-log-tree.json
+
+검사기가 error 로 요구하는데 스킬 본문이 안 적는 칸 셋을 손으로 채워라:
+  candidateScope   — 후보를 찾은 범위
+  sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 모르면 null 로 두고 지어내지 마라
+  ssotSha256       — build 가 채운다. 그래서 build 를 먼저 돌린다
+
+제외가 0 건인 분해는 선별하지 않은 분해다. 후보마다 처분을 적고, 다시 읽은 것만
+dispositionReview: CONFIRMED 로 둬라.
+
+관문:
+  python3 scripts/build-tech-log-tree.py <프로젝트>
+  python3 scripts/verify-tech-log-tree.py <프로젝트>
+error 0 까지 고쳐라.
+
+돌려줄 것: 위 JSON 형식. skillEcho 포함.
+```
+
+---
+
+## S3 — 글감 → 기록
+
+```
+너는 Tech Log 파이프라인의 3단계를 맡는다.
+
+먼저 .agents/skills/writing-tech-log-records/SKILL.md 를 끝까지 읽어라.
+그 스킬이 가리키는 references/ 중 네 종류에 해당하는 것을 읽어라 —
+record-kinds.md · writing-each-kind.md · body-syntax.md · code-tables-diagrams.md ·
+explaining.md · ai-tells.md · choosing-a-diagram.md.
+
+글감: docs/<프로젝트>/tech-log-studio/tech-log-tree.json 의 <주제> / <종류> / "<제목>"
+그 노드가 PROMOTE 이고 dispositionReview 가 CONFIRMED 인지 먼저 확인해라. 아니면 쓰지 마라.
+
+근거: 그 노드의 source 앵커가 가리키는 docs/<프로젝트>/final/document.md 의 절.
+인용하는 줄은 SSOT 에서 찾아 대조해라. 기억이나 다른 기록에서 옮겨 적지 마라.
+
+쓸 곳: docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<파일>.md
+
+그림이 필요해 보이면 docs/<프로젝트>/final/assets/ 에 이미 있는지부터 봐라.
+없으면 이 단계에서 만들지 말고 notes 에 "그림 필요: <무엇을>" 이라고 적어라. 4단계가 만든다.
+
+관문:
+  python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
+  node --experimental-transform-types \
+    .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
+  node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
+  node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
+error 0 까지 고쳐라.
+
+돌려줄 것: 위 JSON 형식. skillEcho 포함.
+```
+
+---
+
+## S4 — 기록 → 그림
+
+```
+너는 Tech Log 파이프라인의 4단계를 맡는다.
+
+먼저 두 개를 읽어라:
+  .agents/skills/technical-visualizer/SKILL.md — 끝까지
+  .agents/skills/writing-tech-log-records/references/choosing-a-diagram.md
+
+기록: <기록.md>
+이 기록을 읽고 무엇을 그릴지 정해라. 세 관문을 지나야 그린다 —
+자리가 Case·Concept 인가 / 표로 될 것이 아닌가 / 옆 문단이 이미 말하지 않았는가.
+그리고 그림이 주장하는 것을 이 기록 본문이 말하고 있어야 한다. 본문이 안 적은 단계를
+그림만으로 넣지 마라.
+
+그림의 근거는 기록이 아니라 기록의 source 앵커가 가리키는 SSOT 절이다:
+  ./scripts/techviz prepare docs/<프로젝트>/final/document.md \
+    --heading "<그 절 제목>" \
+    -o docs/<프로젝트>/final/.techviz/<이름>/context.json
+--line 은 쓰지 마라.
+
+그림 안의 <text> 는 전부 이름이어야 한다. 문장은 <desc> 와 옆 문단에 둬라.
+
+관문:
+  ./scripts/techviz lint docs/<프로젝트>/final/.techviz/<이름>/spec.json \
+    --context docs/<프로젝트>/final/.techviz/<이름>/context.json
+  python3 scripts/check-figure-text.py <프로젝트>
+  python3 scripts/check-figure-overlap.py <프로젝트>
+  python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs
+마지막 것은 PNG 로 떠서 라벨이 상자를 덮지 않는지 눈으로 봐라. lint 는 그것을 못 잡는다.
+
+기록에 되적어라 — frontmatter assets: 에 key 와 file, 본문에는 마크다운 이미지.
+:::evidence 를 저장소 .md 에 쓰지 마라.
+
+돌려줄 것: 위 JSON 형식. skillEcho 포함. 그리지 않기로 했으면 status 를 SKIPPED 로 하고
+어느 관문에 걸렸는지 적어라.
+```
+
+---
+
+## S5 — AI 티 제거
+
+```
+너는 Tech Log 파이프라인의 5단계를 맡는다.
+
+먼저 .agents/skills/rewriting-technical-prose-naturally/SKILL.md 를 끝까지 읽어라.
+그 스킬이 "첫 rewrite 전에 읽으라"고 지정한 references 세 개도 읽어라 —
+document-skeleton.md · article-shape.md · korean-tech-blog-register.md.
+
+고칠 파일: <기록.md>  (제자리에서 고친다)
+
+너의 일은 문체다. 사실을 만들지 마라. 분류가 틀렸거나 근거가 모자란 것은 네 일이 아니다 —
+발견하면 고치지 말고 notes 에 적어라.
+
+보호 구간을 건드리지 마라: 수치 · 날짜 · 버전 · 단위 · 코드 · 명령어 · URL · 직접 인용 ·
+공식 명칭. 한 글자도 달라지면 안 된다.
+
+관문:
+  S=.agents/skills/rewriting-technical-prose-naturally/scripts
+  node $S/check_prose.mjs --warn <기록.md>     # error 0 까지
+  node $S/style_profile.mjs <기록.md>
+그리고 문장을 고쳤으니 본문 문법과 인용을 다시 본다:
+  python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
+  node --experimental-transform-types \
+    .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
+  node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
+
+수치를 맞추려고 문장을 넣지 마라. 검사기는 표면 패턴만 본다.
+
+돌려줄 것: 위 JSON 형식. skillEcho 포함.
+```
+
+---
+
+## S6 — 일한 사람의 목소리
+
+```
+너는 Tech Log 파이프라인의 6단계를 맡는다.
+
+먼저 .agents/skills/writing-as-the-person-who-did-it/SKILL.md 를 끝까지 읽어라.
+references/voice-moves.md 도 읽어라. 그 스킬이 "이것보다 먼저 본다"고 한
+../rewriting-technical-prose-naturally/references/article-shape.md 를 먼저 읽어라.
+
+고칠 파일: <기록.md>  (제자리에서 고친다)
+상류 자료: docs/<프로젝트>/final/document.md · <대상 저장소의 커밋 메시지·주석·README>
+
+찾을 것은 자료에 남아 있는 사람의 흔적이다 — 무엇을 골랐고 무엇과 견주었나,
+확인하지 못한 것이 무엇이고 그것이 어느 주장에 걸리나, 처음 생각과 어긋난 자리가 있나.
+
+없는 사람을 만들지 마라. 「처음에는」·「고민 끝에」·「놀랍게도」를 자료 없이 쓰면 지어낸 것이다.
+넣은 문장마다 그것이 어느 파일 어느 줄에서 왔는지 댈 수 있어야 한다.
+자료에 흔적이 없으면 아무것도 넣지 말고 그렇게 보고해라. 그것도 이 단계를 한 것이다.
+
+관문:
+  node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
+  node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
+  python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
+  node --experimental-transform-types \
+    .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
+  node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
+
+check_voice.mjs 는 목소리가 모자란지 재지 않는다. 지어낸 목소리를 잡는다.
+
+돌려줄 것: 위 JSON 형식. skillEcho 포함. 흔적이 없었으면 status DONE 에 notes 로 적어라.
+```
+
+---
+
+## S7 — Studio 저장
+
+```
+너는 Tech Log 파이프라인의 7단계를 맡는다.
+
+먼저 .agents/skills/publishing-tech-log-to-studio/SKILL.md 를 끝까지 읽어라.
+references/studio-form-map.md 와 references/playwright-recipes.md 도 읽어라.
+
+넣을 기록: <기록.md>
+도구: Playwright MCP (mcp__playwright__browser_*)
+
+저장까지만 한다. 게시 버튼을 누르지 마라. 한 번 게시한 문서는 취소해도 삭제가 409 로 거절된다.
+
+상태 레일 aside[class*="studio-document-status"] 가 25초 안에 안 뜨면 인증이 안 된 것이다.
+로그인 화면에 자격증명을 입력하지 말고 거기서 멈추고 사용자에게 알려라.
+
+frontmatter 의 id 와 studio: 가 이미 있으면 그 주소로 가라. 새로 만들지 마라.
+
+그림이 있으면 Asset 을 본문보다 먼저 올려라. 순서를 뒤집으면 미리보기가 본문을 막는다.
+
+관문:
+  상태 레일의 글자가 저장됨 으로 바뀌는 것을 확인 (최대 30초)
+  python3 scripts/build-tech-log-tree.py <프로젝트>
+  python3 scripts/verify-tech-log-tree.py <프로젝트>
+
+저장됨 이 안 뜨면 버튼을 다시 누르지 말고 레일의 글자를 그대로 보고해라.
+
+돌려줄 것: 위 JSON 형식. skillEcho 포함. gates 에 저장 전후 version 을 적어라.
+```

.agents/skills/running-tech-log-pipeline/templates/run.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 1,
+  "runId": "<YYYY-MM-DD-HHMM>",
+  "project": "<프로젝트>",
+  "record": "<docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<기록>.md — 이 런이 만드는 기록>",
+  "startedAt": "<ISO-8601>",
+  "finishedAt": null,
+  "stages": [
+    {
+      "id": "S1",
+      "name": "코드베이스 → SSOT",
+      "skill": "analyzing-codebase-for-tech-log",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    },
+    {
+      "id": "S2",
+      "name": "SSOT → 분해 계약",
+      "skill": "deriving-tech-log-root-tree",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    },
+    {
+      "id": "S3",
+      "name": "글감 → 기록",
+      "skill": "writing-tech-log-records",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    },
+    {
+      "id": "S4",
+      "name": "기록 → 그림",
+      "skill": "technical-visualizer",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    },
+    {
+      "id": "S5",
+      "name": "AI 티 제거",
+      "skill": "rewriting-technical-prose-naturally",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    },
+    {
+      "id": "S6",
+      "name": "일한 사람의 목소리",
+      "skill": "writing-as-the-person-who-did-it",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    },
+    {
+      "id": "S7",
+      "name": "Studio 저장",
+      "skill": "publishing-tech-log-to-studio",
+      "runBy": "subagent",
+      "status": "PENDING",
+      "skipReason": "",
+      "skillEcho": "",
+      "inputs": [],
+      "outputs": [],
+      "gates": [],
+      "notes": ""
+    }
+  ]
+}