정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
README, docs/README.md, manual-checklist, starter-experience,
ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
`.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
`docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
문제: 기능 제거 드릴과 template-feature-removal-documents 시험은 repo
사본에서 verify:documentation을 돈다. 사본은 scripts/lib/removal-fixture.ts의
목록만 복사하고, 하네스 PR #13 뒤로 그 목록에 루트 CLAUDE.md가 없다.
docs/README.md 「폴더 밖 문서」가 `../CLAUDE.md`를 마크다운 링크로 가리켜
사본에서 없는 경로로 실패한다(.claude/rules/docs.md가 금하는 꼴).
고른 방법: CLAUDE.md와 PRODUCT.md 두 행을 링크 대신 인라인 코드 이름으로
적는다. 버린 안: 사본 목록에 CLAUDE.md를 더하는 것(목록은 드릴이 지우지
않는 문서만 담는다는 하네스 쪽 결정이다).
위험: 지도에서 그 두 파일로 바로 가는 링크가 없어진다. 이름은 그대로다.
검증: template-feature-removal-documents 시험이 desktop에서 통과한다.
문제: 이 브랜치는 SPEC.md의 공통 완료 기준을
docs/manual/reference/done-criteria.md로 옮겼다. 하네스 PR #13은 같은 기준을
작업 매뉴얼 docs/work/improve.md 5절로 옮겼다. 같은 규칙의 사본이 둘이면
하나만 고쳐져 갈라진다.
고른 방법: 소유자 결정 D5가 말한 「매뉴얼」은 일하는 순서를 정하는 작업
매뉴얼(docs/work/) 쪽이 맞아서 개발 매뉴얼 사본을 지운다. 매뉴얼 README의
그 행과 CHANGELOG 줄을 고친다.
위험: 없음에 가깝다. 사본은 이 브랜치에서 생겼고 다른 문서가 가리키지
않는다.
검증: `git grep -n done-criteria`가 CHANGELOG의 이력 줄 밖에서 0건.
문제: 하네스 PR #13이 더한 작업 매뉴얼·규칙은 이 브랜치가 바꾼 문서
체계의 옛 모습을 적는다.
- 옛 경로: `docs/architecture/decisions/`, `docs/superpowers/`, 루트
`SPEC.md`, 목표 설계였던 `docs/testing/frontend-platform-testing-strategy.md`
- 옛 검사 범위: 「docs/README.md 1절이 링크한 문서, 폴더 링크는 바로 아래
.md만」. 지금 verify:documentation은 살아 있는 문서 전부를 보고 언어·
문체·숫자·머리 블록도 본다
- 옛 docs/README.md 절(1절 묶음 / 2절 목표 설계 / 3절 작업 이력)과 README
절 이름(「Support scope」, 「Updating a copied project」)
- #13의 template-contract-documents 시험은 README 지워도 되는 표를
`docs/superpowers/` 행으로 찾는데, 그 행은 이제 없다
고른 방법: 그 줄만 새 위치·새 절 이름·새 범위로 고친다(.claude/rules/docs.md,
docs/work의 docs-writing·operate·research-design·reference 다섯,
docs/problem-statement.md). 시험은 `docs/history/` 행으로 표를 찾는다.
docs/work/evidence.md는 백엔드처럼 매뉴얼 규칙의 근거 기록이라 고치지 않고
`HISTORY_HOLDERS`에 넣어 참조·숫자 검사에서 뺀다.
위험: 하네스 문서의 다른 문장은 건드리지 않았다. 하네스 세션이 쓴 뜻을
바꾸지 않으려는 것이다.
검증: 문서 검사 여섯이 0건, `git grep -n -E 'docs/superpowers|architecture/decisions'`가
기록·CHANGELOG·출처 표시 밖에서 0건.
하네스 PR #13(main d1b9c087)을 받는다. 충돌은 README.md와 docs/README.md
둘이다. 이 브랜치가 두 파일을 한국어로 다시 썼고, #13이 영어 판에
AGENTS.md·docs/work/·docs/ledger/를 가리키는 줄과 지워도 되는 표 행을 더했다.
이 브랜치 판을 바탕으로 #13이 더한 것을 한국어로 넣었다.
- README: 최상위 표에 AGENTS.md·.claude/, 문서 지도에 AGENTS.md·docs/work/·
docs/vision.md·docs/problem-statement.md·docs/ledger/, 지워도 되는 표에서
CLAUDE.md를 빼고 docs/ledger/estimates.jsonl을 더함, 새 서비스로 시작하기와
규칙과 기여의 CLAUDE.md 줄을 AGENTS.md 기준으로
- docs/README.md: 1절 「처음 읽을 문서」에 ../AGENTS.md·work/·work/reference/
링크(#13의 template-contract-documents 시험이 본다), 지도에 work/·ledger/
행, 폴더 밖 문서에 AGENTS.md·vision.md·problem-statement.md, 2절 살아 있는
문서 목록
main에 들어온 하네스 매뉴얼(docs/work/reference/gates.md, testing.md)이
「새 script·시험 파일이 게이트에 안 걸리면 check:ci가 실패한다」고 적는다.
이 PR의 f6b2b96c가 그 검사를 check:ci에서 떼어 main 단계 FE-GATE-029의
check:ci:gating으로 옮겼다. 두 줄과 생성기 주석 한 줄(merge_gate)을
고친다. 하네스 작업은 끝났고(PR #13 병합) 옮긴 명령을 가리키는 줄만
고쳤다.
검증(desktop): verify:documentation, test:unit.
main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.
충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.
등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.
검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
desktop(트리 04bb0e0e)에서 두 가지가 실패했다.
- FE-GATE-010·020: check:adapter-inventory가 "total does not equal 143
tracked files"로 멈췄다. src/adapters의 AGENTS.md·CLAUDE.md 두 행은
더했지만 INVENTORY.md 끝의 합계 줄(141/141)을 고치지 않았다.
- scripts/verify.sh parts FE-GATE-013: verify:reproducible-build,
build:release-candidate, verify:local-evidence가 "missing required CI build
environment: SOURCE_DATE_EPOCH"로 실패했다. ci:gate는 HEAD에서 이 값을
만들지만 parts·script는 명령을 직접 부른다.
합계를 143/143으로 고치고, ci_env가 HEAD 커밋 시각으로 SOURCE_DATE_EPOCH를
준다(ci:gate와 같은 값).
검증: python3 -m unittest discover -s scripts/tests 통과(ci_env가 HEAD
SHA·커밋 시각·digest 꼴 이미지를 주는 시험 추가). desktop 재실행은 이
커밋 트리에서.
커밋 전 검사 8개, 통합 때 5개, 옛 게이트 11개처럼 config/ci/gates.json과 표가
정하는 개수를 문장에 옮겨 적었다. 표가 바뀌면 문장이 낡는다(문서 체계
검사의 숫자 복사 규칙). 개수를 빼고 표를 가리킨다.
검증: scripts/verify.sh docs rc=0.
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.
src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).
- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
양식을 가리킨다.
버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).
위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).
검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
하네스 자료는 레이어 규칙·훅·스킬과 함께 비전(세 문장)과 문제 정의(고객의
말 그대로, 하지 않는 것, SMART 성공 기준)를 빈 양식으로 템플릿에 두라고
한다. 프론트에는 둘 다 없었다.
claude-harness template/docs/의 두 파일을 옮긴다. 프로젝트 이름 자리표시자는
빼고, 결정 기록 위치는 이 repo의 docs/architecture/decisions/로 바꿨다.
루트 AGENTS.md가 한 줄로 가리킨다(다음 커밋).
위험·한계: 채울 것 자리는 소유자 몫이라 비워 둔다. 문서 검사 범위
(docs/README.md 1절) 밖이다.
검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과.
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.
고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.
위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.
검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
문제: docs/operations의 release-cache-rollback.md와
adapter-remediation-ledger.md는 본문이 영어이고, 나머지 복구 문서와
ci-quality-gates.md에도 영어 문단이 남아 있다.
고른 방법: 뜻을 바꾸지 않고 옮긴다. 원장은 check:remediation-ledger가
읽으므로 같은 변경에서 스크립트를 맞춘다.
- `SECTION_HEADING`을 옮긴 절 제목(`## 세 번째 재검토 (2026-08-14)`)으로
- 「모두 닫혔다」를 잡는 `BLANKET_CLOSURE`에 한국어 대안을 더한다. 영어
대안은 원장이 인용한 옛 문장을 잡도록 그대로 둔다
- 표 구조, id 칸, disposition 칸의 백틱 값, file-transfer 예산 숫자는
그대로다
- ci-quality-gates.md의 advisory 표가 복사한 zod·react-router 버전을
`package.json`·`pnpm-lock.yaml`을 가리키게 바꾼다(number 검사)
위험: check:remediation-ledger는 게이트 밖이라 CI가 돌리지 않는다.
desktop에서 손으로 돌려 확인했다.
검증: dispositions.json의 id 25개가 그 절의 행과 맞는지, 예산 숫자가
있는지를 스크립트로 확인했다. 문서 검사의 language·number 줄이 0이 되어
예외 목록에서 지웠다.
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md,
starter-experience.md, capability-consumer-experience.md,
contract-ownership.md, static-delivery.md, review-evidence.md는 본문이
영어이고, backend-api-and-server-state-contract.md와
optional-adapter-recipes.md에는 영어 문단이 남아 있다.
고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드
주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은
그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서
고친다.
- tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를
자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`)
- 「Ownership declarations」「Adding a feature」를 인용한 주석
(create-feature.ts, generate-product-feature-index.ts, app-module.ts)과
docs/manual의 절 이름 인용
- optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게
바꾼다(number 검사)
위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라
새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다.
review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다.
검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로
비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외
목록에서 지웠다.
문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.
고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
폴더 이름을 적지만 지운 사본에서도 통과하므로
deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
테스트와 검사기 시험에 적었다).
위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).
검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
scripts/check-*.ts 30개(6,351줄)가 게이트 명령의 상당수를 차지한다.
각각을 ESLint 규칙, dependency-cruiser 규칙, vitest 시험으로 옮길 수
있는지 판정 표로 남긴다(design-docs repo-structure/03-ci.md 7.3절 F3).
코드는 바꾸지 않는다.
판정: 시험 8, 일부 이전 9, 스크립트 유지 11, ESLint 규칙 1, 지움 1
(정리 3단계). 위험이 낮고 효과가 큰 후보 5개와, 옮길 때 같이 고칠
증거 계약·drill 목록을 적었다.
위험: 줄 번호는 판정 시점 `ad3a071f` 기준이다. 판정 중에 찾은 가짜 검사
2개(`check-design-system.ts`, `check-diagnostics.ts`의 fixture 표식 검사)는
고치지 않았다.
검증: 문서만. 스크립트를 읽어 판정했고 실행하지 않았다.
Refs: design-docs repo-structure/03-ci.md 7.3절 F3
merge 단계(=PR)가 변경이 아니라 검사기 자신을 시험하는 명령까지 돈다.
검사기가 나쁜 입력을 거부하는지 보는 `*:fixture` 명령 15개, 모든 시험
파일과 검증 script가 게이트에 걸렸는지 보는 ungated 검사, CI 계약의
개수·해시 기준선(`config/ci/contract-baseline.json`)이다. 기준선은 게이트
명령 하나를 더하거나 빼도 OWNER·REASON을 붙여 다시 받아야 했다.
소유자 결정(2026-09-16)은 개수·배선 검사를 main 단계에 두는 것이다.
고른 방법(design-docs repo-structure/03-ci.md 7.3절 F2, README.md 3.3절,
소유자 승인 2026-11-07):
- 새 게이트 FE-GATE-029 `checker-self-tests`, 새 단계 `main`
(`MAIN_READY`, 승격을 막지 않는다), 새 job `main_gate`. 브랜치 push와
`workflow_dispatch`(stage=main)에서만 돈다. PR과 태그에서는 돌지 않는다.
- FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거
산출물 10개를 FE-GATE-029로 옮긴다.
- `check:ci`의 ungated 검사를 `scripts/check-ci-gating.ts`
(`check:ci:gating`)로 떼어 FE-GATE-029에 둔다. `check:ci`는 계약·
workflow 검사만 PR에서 돈다.
- 기준선 파일, `update:ci-contract-baseline`, 그 검사를 지운다(소유자
결정). 계약 모양은 ci-gates.ts의 의미 검사가 지킨다. 개수를 고정하던
단위 시험의 개수 단언도 뺐다.
남긴 것: 음성 타입 fixture(`check:types:fixtures`, FE-GATE-003)는
이름이 `*:fixture`여도 merge에 둔다. 검사기가 아니라 src의 포트·계약
타입을 시험한다. `TelemetryPort.emit`을 넓히는 변경을 PR에서 막는다(정리
3단계 9.3절 변이로 확인). merge 단계 명령 참조 64 → 49.
위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다. 그
대가로 PR이 검사기 자기 시험을 기다리지 않는다(설계 7.5절의 같은 교환).
FE-GATE-029의 명령이 앞 게이트 산출물 없이 새 checkout에서 도는지는
desktop에서 따로 확인했다(PR 본문).
검증(desktop): check:ci, check:ci:gating, check:types, CI 시험 통과.
merge 단계·FE-GATE-029 실행 결과는 PR 본문에 적는다.
Refs: design-docs repo-structure/03-ci.md 7.3·7.4절, README.md 3.3절
`docs/README.md` 표가 수동 a11y 기록을 아직 `artifacts/tests/a11y-manual/`로
가리킨다. 기록은 `docs/accessibility/route-reviews/`로 옮겼다(79dc945a).
`verify:documentation`은 `.gitignore`가 무시하는 경로를 생성 출력으로 보고
넘겨서 이 줄을 잡지 못했다.
검증(desktop): verify:documentation, test:unit.
merge 단계가 게이트마다 job 하나(행렬 14개)라서 PR마다 checkout,
setup-node, `pnpm install`을 14번 하고 브라우저 설치를 2번 한다. Gitea
runner는 소유자 기계 한 대다. 사례(Vite 등)는 설치를 job당 한 번으로
묶는다(design-docs repo-structure/03-ci.md 3.5절).
고른 방법(03-ci.md 7.3절 F1, 소유자 승인 2026-11-07):
- job 종류 `gate-sequence`를 더한다. job 하나가 게이트 여럿을 차례로
돈다. 게이트마다 `FE-GATE-NNN / <이름>` 단계이고 `if: !cancelled()`라
앞 게이트가 실패해도 다음 게이트가 돈다(행렬의 fail-fast: false와 같다).
- merge job 셋: `merge_static`(001·002·003·010·011·012, 소스를 읽고
빌드하는 검사), `merge_test`(004·005·006·007·013·020, 시험),
`merge_browser`(008·009, 브라우저 설치). release 단계는 셋을 모두
기다린다. 게이트 id·명령·증거·승격 공식은 그대로다.
- 증거 업로드는 job마다 하나(`merge-static-<run>` 등)다.
버린 것: 행렬을 두고 `pnpm install`만 캐시하는 방법. runner 한 대에서는
job 수만큼 checkout과 준비가 남는다. 게이트를 job 하나에 모두 넣는
방법은 브라우저 설치를 모든 게이트가 기다린다.
위험: 한 job 안의 게이트가 같은 작업 공간을 쓴다. 앞 게이트의 산출물이
뒤 게이트에 남는다. desktop의 merge 단계 실행(게이트를 한 checkout에서
차례로 도는 것)과 같은 조건이라 그 결과로 확인했다. 실제 Gitea runner의
`!cancelled()` 해석은 Actions를 켠 뒤 확인한다.
검증(desktop): check:ci, check:types, CI 시험 4파일 통과. 합치기
전후 merge 단계 게이트별 결과 비교는 PR 본문에 적는다.
Refs: design-docs repo-structure/03-ci.md 3.5·7.3·7.4절, README.md 3.3절
이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능
만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가
나왔다. 고친 것:
- new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로
받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거
드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는
중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면
묻는다. 초기 JS 기록의 파일을 적는다.
- gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구,
PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과
ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개
(package script)"로.
- review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4·
증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다.
- README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절
이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의
정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외,
스킬의 새 명령 모양.
고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에
시작했다).
검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
`kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
보지 않는다. 산출물 `documentation-review.json`에
`layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
`check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.
위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.
검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
`scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
`config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
`.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
`tests/fixtures/hosting/response-headers.json`.
버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.
위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).
검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
음성 타입 fixture마다 옵션이 같은 tsconfig 하나, package script 하나,
게이트 명령 하나가 있었다(23벌). 옵션은 모두 같고 파일 하나만 달라서
fixture를 더할 때마다 세 곳을 같이 고쳤다. `tsconfig.recipes.json`도
`tsconfig.test.json`과 lib가 같고 types만 하나 적었다.
`tsconfig.web-worker.json`은 `files: []`로 0파일을 검사하고 통과했다
(2026-09-25 리뷰가 기록, FE-GATE-003이 통과로 보였다).
고른 방법(design-docs repo-structure/04-frontend-layout.md 5.3절 (가),
소유자 승인 2026-11-07):
- fixture 첫 줄에 기대(`// expect: TS2322`, `// expect: pass`)를 쓰고
`scripts/check-type-fixtures.ts`가 fixture마다 `.tmp/type-fixtures/`에
한 파일 tsconfig를 써서 tsc를 돈다. 판정은 run-ci-gate.ts가 명령마다
하던 것과 같다(exit 1과 `error TS<code>:`). 결과를 fixture별로 출력한다.
기대 줄이 없는 fixture와 fixture 0개는 실패한다.
- recipes는 `tsconfig.test.json` include로 옮긴다.
- web-worker tsconfig와 script는 지운다(결정 D4). Worker를 들일 때 더하는
단계는 매뉴얼 03에 쓴다(뒤 커밋).
- `scripts/check-typecheck-inputs.ts`를 `check:types` 끝에 둔다. package
script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상인지 본다.
`files: []` tsconfig가 통과로 보이던 구멍을 막는다(R8).
버린 것: TypeScript API로 한 프로세스에서 돌리는 방법. 이 repo의
TypeScript 7.0(네이티브판)은 JS API를 싣지 않는다. 위반마다
`@ts-expect-error`를 쓰는 방법(5.3절 (나))은 오류 코드 고정을 잃는다.
위험: recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다.
recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다
(복사한 제품도 Vite라 가치가 작다, 설계 5.1절). CI 계약 기준선을 다시
받았다(명령 99 → 76).
검증(desktop): `check:types:fixtures` 23개 PASS, 각 fixture의 기대 코드가
출력에 그대로 나온다. `TelemetryPort.emit` 인자를 `string`으로 넓히는
변이(2026-09-25 리뷰 07-05)에서 `invalid-diagnostics-port.ts`가 TS2578로
FAIL, 실행기 rc=1. 되돌린 뒤 작업 트리 0줄. `check:types` rc=0
(Typecheck inputs: app 379, node 312, service-worker 22, test 915).
Refs: design-docs repo-structure/04-frontend-layout.md 5.3·9.2·9.3절, README.md 3.4절 D4
README의 지워도 되는 파일 표가 루트 CLAUDE.md를 "템플릿 repo 자신의
리뷰 지시, 자기 것으로 바꿔라"로 분류했다. 소유자 결정(2026-11-07 Q4)은
루트 지침을 템플릿 계약으로 정했다. 그리고 AGENTS.md와 docs/work/는
verify:documentation 범위 밖이라 그 안의 경로·script·게이트 ID가 틀려도
아무 검사도 알리지 않는다.
- README: 문서 절에 AGENTS.md와 docs/work/ 포인터를 더하고, 지워도 되는
표에서 CLAUDE.md 행을 빼고 docs/ledger/estimates.jsonl("줄을 비운다")을
넣는다.
- docs/README.md 1절: ../AGENTS.md, work/, work/reference/를 링크한다.
- tests/unit/template-contract-documents.test.ts: 지워도 되는 표에
AGENTS.md·CLAUDE.md·.claude·docs/work가 없고, 1절이 셋을 링크하는지
본다. 표는 제목이 아니라 docs/superpowers/ 행으로 찾아 제목을 옮겨도
돈다. 문서를 읽으니 REMOVAL_FIXTURE_DOCUMENT_TESTS에 올렸다.
- deletable-history-documents.test.ts: CLAUDE.md 패턴을 뺀다(이제 지워도
되는 문서가 아니다).
- 제거 드릴의 문서 사본(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과
template-feature-removal-documents.test.ts의 사본에 AGENTS.md를 더한다.
사본 안에서 검사기를 돌리므로, 1절이 링크한 AGENTS.md가 없으면
FE-GATE-020과 그 단위 시험이 실패한다.
버린 대안: AGENTS.md를 링크하지 않고 백틱으로만 적기. 검사가 빠진다.
위험·한계: 문서 체계 세션이 README를 한국어로 옮기면 표 제목이 바뀐다.
새 시험은 행으로 찾지만, verify-documentation-readiness.ts의 지운 이력
목록은 영어 제목을 읽으니 그 세션이 같이 고친다.
검증: 새 시험은 README·docs/README.md를 고치기 전 트리에서 둘 다
실패했고(desktop test:unit), 고친 뒤 통과한다. verify:documentation과
merge 단계는 PR 전 합친 트리에서 돌린다.
Refs: design-docs harness/01-harness-design.md 4.4절·13절 Q4
작업마다 착수할 때의 예측과 끝날 때의 실측을 남길 곳이 프론트에 없었다.
소유자 결정(2026-11-07 Q11)은 repo마다 docs/ledger/estimates.jsonl이다.
docs/ledger/README.md(백엔드와 같은 형식)와 estimates.jsonl을 두고,
여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes가
merge=union을 준다. 첫 줄은 이 작업(fe-c-harness)의 착수 예측이다.
위험·한계: 복사한 프로젝트는 템플릿의 줄을 받는다. README 지워도 되는
표에 "줄을 비운다"로 적는다(뒤 커밋).
검증: python3 -m unittest scripts/tests/test_ledger.py 통과.
Refs: design-docs harness/01-harness-design.md 10절·13절 Q11
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의
리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안
(브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다.
백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고),
playbook 여섯(new-feature, improve, research-design, docs-writing,
operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates,
review-criteria, structure, testing, performance, defect-patterns,
decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는
evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로
옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다.
진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는
evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은
결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛
번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06
리뷰 기준으로 갱신했다.
버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와
진입 경로·검사기가 갈라진다.
위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이
폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read
시험은 하지 않았다.
검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함).
Refs: design-docs harness/01-harness-design.md 13절, PR #6
문제: 링크를 고친 앞 커밋은 옮긴 파일의 옛 위치를 지금 트리에서
찾았다. 그래서 VD와 superpowers 계획서 안에서 나가는 상대 링크
28개(예: VD-14의 `../../operations/…`)는 옛 위치 기준 그대로 남아
없는 곳을 가리킨다.
고른 방법: 옛 위치를 `git diff --name-status -M ad3a071f HEAD`의 이름
바뀜으로 다시 구해, 옮기기 전에는 풀리던 링크만 새 위치 기준으로 다시
쓴다. 옮기기 전에도 깨져 있던 링크 22개는 쓴 때의 글이라 그대로 둔다.
고친 것은 링크 대상뿐이다.
위험: 없음에 가깝다. 기록 본문의 글자는 바뀌지 않는다.
검증: 같은 스크립트를 다시 돌려 「옮기기 전엔 풀리던 깨진 링크」 0건.
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.
고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.
위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.
검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
문제: SPEC.md는 끝난 2026-09-25 리뷰 수정 라운드의 요구사항이다. 기록인데
저장소 루트에 있어 지금 쓰는 문서처럼 보인다.
고른 방법: 공통 완료 기준을 앞 커밋에서 매뉴얼로 옮겼으므로, 내용 변경
없이 같은 라운드의 계획서 폴더로 옮긴다(소유자 결정 D5). 루트 항목
등록부는 이 repo에 없어서 고칠 곳이 없다.
위험: 루트 README와 docs/README.md의 SPEC.md 줄은 뒤 커밋이 다시 쓴다.
검증: git status가 이름 바뀜 하나만 보인다.
문제: 2026-09-25 리뷰 수정 라운드의 요구사항 SPEC.md는 라운드가
0.2.0으로 끝난 기록인데, 그 안의 「공통 완료 기준」(RED→GREEN, 변이
확인, 게이트, INVENTORY, kernel 위치, 포트 추가만, 커밋 하나, 문서
주장의 코드 위치)은 지금도 쓰는 규칙이다. 기록으로 옮기면 규칙이
지울 수 있는 이력 안에만 남는다(소유자 결정 D5, 2026-11-07).
고른 방법: docs/manual/reference/done-criteria.md로 옮기고 매뉴얼
README 표에 더한다. 게이트 여덟 개를 적은 원문 3·4번은 매뉴얼 규칙
(원칙 8, 목록을 복사하지 않음)에 맞춰 정본 config/ci/gates.json과
`ci:gate`를 가리키게 바꿨다. 작업 매뉴얼(docs/work/)은 하네스 세션이
만드는 중이라 이 변경은 개발 매뉴얼에 둔다.
위험: 하네스 세션이 docs/work/에 같은 기준을 두면 둘 중 하나를
가리키게 정리해야 한다.
검증: 문서만 바뀐다. 경로는 뒤의 verify:documentation 실행에서 본다.
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는
상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을
가리킨다.
고른 방법: 기계적으로 바꾼다.
- 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고,
대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다.
옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은
링크 대상뿐이다(백엔드 1단계와 같은 예외).
- 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`,
`docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과
CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와
review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토
작업 공간의 출처 표시라 그대로 둔다.
위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는
없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다.
검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록,
CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시
쓴다) 밖에서 0건.
문제: 프론트 docs/는 지금 동작을 설명하는 문서와 쓴 때의 기록이 한
폴더에 섞여 있다. docs/architecture/에는 현재 계약 10개와 목표 설계
14개, 결정 기록 VD 23개가 같이 있고, 설계서·계획서는 플러그인 이름
폴더(docs/superpowers/)에 있다. 문서 체계 규칙(design-docs
conventions/docs-system.md v1, 2026-11-07 소유자 결정)은 수명으로
나누고 폴더 이름을 백엔드와 같게 하라고 정한다.
고른 방법: 내용 변경 없이 git mv만 담는다. git이 이름 바뀜을 알아보고
리뷰어가 이동과 내용 변경을 따로 볼 수 있게 하려는 것이다. 참조 수정과
머리 블록은 다음 커밋들이 한다.
- docs/superpowers/specs → docs/design/, plans → docs/history/plans/
- docs/architecture/ 목표 설계 13개와 styling·testing의 목표 설계
2개 → docs/design/<작성일>-<이름>-design.md (2026-07-30 결정 정본은
이름 그대로)
- docs/architecture/decisions/VD-* → docs/adr/ (번호 유지)
위험: 이 커밋만으로는 옮긴 문서를 가리키는 링크와 경로가 깨진다.
다음 커밋이 고친다. 게이트가 읽는 파일(review-ledger.json,
review-evidence.md, adapter-remediation-ledger.md, INVENTORY.md)은
옮기지 않았다. docs/history/는 복사한 프로젝트가 지워도 된다는 약속
(tests/unit/deletable-history-documents.test.ts)이 있어서 코드가 읽는
파일을 둘 수 없다. SPEC.md는 공통 완료 기준을 매뉴얼로 옮긴 뒤 따로
옮긴다.
검증: git status가 이름 바뀜(R) 66개만 보인다.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.
참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.
위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.
검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
규모 측정(S4 3.1절 S-6)은 참조 기능을 복사해 이름을 바꿔 잰다.
create:feature의 planFeature로 사본마다 --with-create --keyed 기능
파일을 만든다(자기 계약 패키지와 topic, context당 200개). 초기 JS
기록에 firstFeatureGzipBytes를 더하고, context 비용은 둘째 기능을 새
context에 둘 때와 같은 context에 둘 때의 차이로 잰다. 옛 정의는 기능이
없는 템플릿에서 첫 기능의 공용 코드까지 context 비용으로 세어 5,788B로
상한 512B를 넘었다. 몇 바이트짜리 비용에는 기록 허용치 하한 16B를
둔다(빌드 ID에 따라 gzip이 1~2B 흔들린다). 이 트리(샘플이 아직 있는
상태)의 기록: 204,266B, 27파일, 첫 기능 797B, 기능 521B, context 12B.
위험: 성장 기준선(0·25·100개)은 샘플을 지운 트리에서 뒤 커밋이 다시
잰다. 이 커밋의 기준선 파일은 아직 참조 사본으로 잰 값이다.
검증(desktop): feature-shape-growth 등 4파일 57 passed, test:unit 통과.
매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을
가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는
참조 기능에만 있다.
생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안
코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절,
소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook,
403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다.
tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature
invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어
tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를
돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다.
위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오
forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이
끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에
이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서
실패한다.
검증(desktop): test:unit 213 files 3096 passed(이 커밋까지),
verify:documentation PASS_SCOPED, lint 통과.
src/features/local-draft-feature는 기능이 아니라 IndexedDB recipe의
소비자다. 시험 5개와 recipe가 쓰고, 그래서 생성기에 NOT_A_FEATURE
예외가 있었다(S4 3.1절 S-3).
코드를 tests/fixtures/indexeddb-consumer/로 옮기고 import만 고쳤다.
NOT_A_FEATURE 표식은 이 폴더만 썼고 다운스트림 둘에도 없어 생성기에서
지웠다. 선언 없는 폴더는 밖으로 옮기라는 메시지로 실패한다. 매뉴얼
오류표, README, starter-experience, capability-consumer-experience,
patterns를 고쳤다.
위험: fixture는 기능 폴더 밖이라 기능 계층 규칙(dependency-cruiser)이
걸리지 않는다. recipe가 tests/ 아래 파일을 type import한다.
검증(desktop): test:contract, test:recipes, test:browser-capabilities,
test:unit 통과.
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).
두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.
위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.
검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
문제: docs/operations/release-cache-rollback.md에 nginx 설정이 통째로
있다(보안 헤더 snippet과 server 블록, 「Example: nginx on a single
server」 절). CI는 그것을 돌리지 않고, 호스트 설정은 개발 repo의 일이
아니다(소유자 2026-11-07). ci-quality-gates.md의 runner 요구 절에도
호스트를 바꾸는 절차(AppArmor profile 본문, sysctl 명령)가 있다.
고른 방법:
- nginx 절을 지우고 같은 문서에 「운영 환경이 지켜야 할 조건」 19개를
문장으로 쓴다. 조건마다 재는 쪽을 적었다: FE-GATE-019가 잰다(live
모드, 값은 config/hosting/*.json) / 아무도 재지 않는다. 백엔드와 같은
절 이름·같은 언어(한국어)다.
- 지운 설정을 한 줄씩 대조했다. snippet 6줄 → 6(값), always → 7;
listen 443 ssl·server_name·인증서 → 1; http2 → 2; gzip·gzip_types →
10, gzip_vary → 11; root current와 원자적 symlink 전환 → 17;
index.html → 3·6; try_files fallback → 4·6; config.json·
release-manifest.json → 5·6; 공유 /assets/·기간으로 지우기 → 18;
없는 청크 404 → 12; immutable → 8; service-worker.js → 14·15;
.map 404 → 16; Cache-Control에 always 없음 → 13; 기본 base path / →
1; mime.types에 맡긴 Content-Type → 3·5·9·14. 롤백 때 동작은 19.
- static-delivery.md의 "nginx example" 문장은 이 절을 가리키게 고친다.
- ci-quality-gates.md: runner 요구(바이너리, systemd, cgroup, 비특권
user namespace)는 게이트가 runner에 요구하는 조건이라 남긴다. 고치는
방법 목록과 AppArmor profile 본문만 지우고 "고치는 방법은
scripts/check-system-test-prerequisites.ts가 실패할 때 출력한다"로
바꾼다. 그 스크립트가 같은 세 방법을 출력한다.
버린 대안: nginx 설정을 project-infra나 cicd-platform으로 복사하기.
아무도 시험하지 않는 복사본이 다른 repo에 생긴다(백엔드도 지웠다).
위험·한계: 아무도 재지 않는 부분이 있는 조건이 11개다(7, 8의 나머지 파일,
10의 나머지 청크와 CSS·JSON·SVG, 11, 12, 13, 15, 16의 호스트 쪽, 17의
전환 도중, 18, 19의 호스트 쪽). 지운 nginx 예시도 CI가 돌리지 않았으니
재지 않는 범위는 넓어지지 않았다. AppArmor profile 본문은 이 repo에서
없어진다. 필요하면 runner를 만드는 쪽 인프라 repo가 갖는다.
검증: git grep -n '^```nginx' 0줄. desktop(이 커밋 30a379f 트리, 로그
~/l1-layout-cleanup-logs/): verify:documentation PASS_SCOPED(새 절의
경로·script 이름·FE-GATE ID와 static-delivery.md의 링크 포함),
test:unit 3091 tests 통과.
Refs: design-docs repo-structure/04-frontend-layout.md 4절 I-3·I-4·I-11
문제: 끝난 작업의 기록이 루트 폴더 둘에 따로 있다. tasks/는 2026-09-25
리뷰 수정 라운드(v0.2.0으로 끝남)의 계획·작업 목록·인계·레인 지시서와
레인 준비 스크립트 5개, .superpowers/는 2026-08-01 런타임 정합성 수정의
작업 보고 1개다. 읽는 코드는 없다(tests/unit/deletable-history-
documents.test.ts가 지킨다). 소유자가 2026-11-07 백엔드와 같이 이력
폴더로 옮기기로 정했다.
고른 방법:
- tasks/ → docs/history/plans/2026-09-25-review-fix-round/ (lanes/ 유지),
.superpowers/sdd/2026-08-01-runtime-correctness-remediation/
task-5-report.md → docs/history/evidence/2026-08-01-runtime-correctness-
remediation/. 폴더 이름은 docs-system 2절과 백엔드를 따른다.
- .md 5개 맨 위에 docs-system 4.1절 머리 블록 9줄(빈 줄 포함, 백엔드와
같은 모양)을 단다. 본문은 바꾸지 않았다: 블록 9줄을 빼면 옛 파일과
바이트가 같다(cmp). setup-lane.sh는 실행 파일(첫 줄 shebang)이라 블록을
달지 않고 그대로 옮긴다(R100). 같은 폴더 LANE-BRIEF.md의 블록이 그
파일을 설명한다.
- 상태: 계획서 넷은 끝남. 기계 규칙(체크 상자가 모두 표시돼야 끝남)으로는
plan·todo가 확인 안 함이지만, 이력이 라운드의 끝을 정한다(CHANGELOG
0.2.0, 태그 v0.2.0 2026-09-27). 증거는 보관.
- 작성일: plan·todo는 2026-09-25. git이 처음 더한 날(ea0f01f,
2026-09-24)은 이 파일이 앞 라운드(src 리뷰) 계획이던 때이고, 지금
본문은 c5f379b(2026-09-25)가 통째로 다시 썼다. handoff는 본문 날짜 줄
(2026-09-26 01:10), LANE-BRIEF는 git이 처음 더한 날(54ba358,
2026-09-26), 보고는 git이 처음 더한 날(d9afccd, 2026-08-02).
- docs/README.md: 3절 지도에 history/ 행을 더하고 옛 경로 → 새 경로를
적는다. 블록 첫 줄이 가리키는 「기록 문서의 머리 블록」 절(4절)을
더한다. ../tasks/ 링크는 없앴다. README.md의 "Files you can delete
after copying" 행도 docs/history/로 바꾼다.
- deletable-history-documents.test.ts: docs/history 패턴을 더하고
tasks/ 패턴은 뺀다. 루트 tasks/가 없어져 그 패턴이 지킬 문서가 없고,
남기면 제품의 "tasks/..." 라우트·폴더 문자열을 잘못 잡는다.
버린 대안: 옮긴 파일을 가리키는 다른 기록(docs/superpowers/plans/
2026-08-02-*.md, docs/reviews/2026-09-25-maturity-review/, SPEC.md)의
옛 경로를 고치기. 기록 본문은 고치지 않는다(docs-system 1절). 대신 지도
행에 옛 경로를 적었다.
위험·한계: SPEC.md는 이번에 옮기지 않는다. 27~37줄 「공통 완료 기준」을
작업 매뉴얼(docs/work/improve.md, 뒤 단계)로 옮긴 뒤 같은 폴더로 보낸다.
secret-scan-policy.json의 trackedRoots와 루트 경로 목록 7곳에는 tasks,
.superpowers가 없어 바꿀 것이 없다.
검증:
- 옮긴 .md 5개: 첫 9줄을 빼면 옛 파일과 cmp가 같다. git diff -M이
R091~R100 rename으로 잡고 지운 줄은 0이다.
- desktop(네 커밋의 끝 30a379f, 로그 ~/l1-layout-cleanup-logs/):
deletable-history-documents.test.ts는 지금 트리에서 통과하고, 테스트
폴더에 "docs/history/plans"를 담은 파일 하나를 두면 그 줄을 내며
실패한다. verify:documentation: PASS_SCOPED. test:unit 3091 tests 통과.
Refs: design-docs repo-structure/04-frontend-layout.md 2.1절, 9.2절;
design-docs conventions/docs-system.md 2·4절
문제
리뷰 가이드와 실행 체크리스트는 백엔드·프론트 두 템플릿이 함께 쓰는
리뷰 기준인데 프론트 repo의 docs/reviews/ 안에 있었다. 소유자가
2026-11-06 design-docs로 옮기기로 정했고(위임 루프 설계 결정 D13),
정본이 design-docs main 5f35810에 들어갔다. 이 repo의 사본이 그대로
남으면 두 곳에 본문이 생겨 서로 갈라진다.
고른 방법
- 두 파일을 정본 위치만 적은 포인터로 바꿨다. 정본 경로는 design-docs
저장소 기준(conventions/...)으로, 링크 없이 코드 표기로 적었다.
다른 저장소라 상대 링크는 이 checkout에서 따라갈 수 없다.
- 포인터에 절 번호가 정본에서도 같다는 것과, 옮기기 전 마지막 판을
읽는 git show 명령(가이드 003832b6, 체크리스트 752a61f2)을 적었다.
정본과 이 repo 판의 차이는 맨 위 "옮긴 기록" 블록과 서로 가리키는
링크뿐이라 절 번호는 바뀌지 않았다.
- 파일 이름과 위치는 그대로 뒀다. CLAUDE.md와 지난 리뷰 문서가 이
경로를 가리키므로 링크가 끊기지 않는다.
- docs/README.md의 reviews/ 행을 "가이드는 design-docs로 옮겼고
여기에는 포인터만 있다"로 고쳤다.
- 버린 대안: 두 파일 삭제. CLAUDE.md 링크와 지난 리뷰 문서의 가이드
경로가 끊긴다. CLAUDE.md는 소유자 승인 대상이라 이 커밋에서 바꾸지
않는다.
위험과 한계
- design-docs를 받지 않은 환경(다운스트림 복사본, CI)에서는 정본을
열 수 없다. 이력이 있는 checkout은 git show 명령으로 옛 판을 읽는다.
- CLAUDE.md는 여전히 포인터 파일을 리뷰 기준으로 가리킨다. 링크를
design-docs로 바꿀지는 소유자가 정한다.
- verify:documentation은 docs/README.md 1절에서 링크한 문서만 보므로
포인터 두 파일 안의 경로는 검사하지 않는다.
검증
- desktop에서 corepack pnpm verify:documentation, corepack pnpm
test:unit 통과. 로그는 desktop ~/d13-review-guide-pointer-logs/.
- 기준 브랜치: PR #8 끝 fix/maturity-review-2026-11-06(1141969f).
문제: 리뷰 README 16절에 확인(16.5)이 비어 있다. 그 뒤 diff 리뷰(DR-01~06),
마지막 리뷰(FR-01~05)와 메인 세션 결정 D10 보완·보완 2도 적혀 있지 않다.
고른 방법:
- 16.2절에 D10 보완(`80e7f1d6`)과 보완 2(`b41990cd`) 행을 더한다. 둘 다 메인 세션
결정이고 사용자가 뒤집을 수 있다고 적는다.
- 16.4절의 다섯 발견 행에 DR·FR 수정 해시를 더한다.
- 16.5절: `5cfc3a65`, `f1734913`, DR 수정, `59b2ccb5`, FR-01 수정에서 돌린 검사와
돌리지 않은 것을 적는다.
- 16.6절: 해시 대조를 끝 `8b8b6c54` 기준으로 다시 돌린 결과로 바꾼다.
- 16.7절(diff 리뷰): DR-01~05는 고쳤고 DR-06은 이유와 함께 남긴다. DR-02에 메인
기준보다 하나 더한 규칙(`-`가 든 이름만)과 그 이유, 뒤집는 법을 적는다.
- 16.8절(마지막 리뷰): FR-01은 메인 세션에 먼저 알린 뒤 고쳤다. 등급은 Medium·P2이고,
리뷰어가 High로 본 이유도 같이 적는다. FR-02는 계약 문서 한 줄과 백엔드 pin grep
결과를 적는다. FR-03~05는 남긴다.
위험·한계: 이 커밋 자체의 문서 검사 결과는 이 문서에 적을 수 없다. 메인 세션 보고에
적는다. 1~15절은 리뷰 때 그대로다.
검증: desktop batch에서 확인.
bash /tmp/claude-gates/r6/scripts/docs-check.sh
git merge-base --is-ancestor <해시> 8b8b6c54 (16.6절)
Refs: 1106/03-01 (diff review DR-01, final review FR-01·FR-02), 1106/14-02
문제: b41990c 뒤 같은 키 재전송이 400 VALIDATION_FAILED로 거절되면 훅과 폼이
첫 요청도 거절된 것으로 보고 결과 불명을 푼다. 백엔드가 시각이나 데이터베이스를
읽는 규칙을 VALIDATION_FAILED로 내면, 첫 요청이 적용된 뒤의 재전송도 이 답을
받을 수 있다. 계약 문서 6.1절은 이 전제를 적지 않는다(최종 리뷰 FR-02).
고른 방법: 6.1절의 재전송 규칙 옆에 한 문장을 더한다. VALIDATION_FAILED는
요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는 규칙은 기능이
선언한 code로 내며 그 code는 결과 불명을 풀지 않는다.
버린 대안: 프론트에서 VALIDATION_FAILED도 결과 불명으로 남기기(메인 세션
결정 "D10 보완 2"가 이 code를 푸는 쪽으로 정했다).
위험·한계: 문서 규칙이다. 백엔드에서 이것을 막는 검사는 없다(6.1절 끝의 남은
위험과 같다).
검증: desktop batch에서 확인. corepack pnpm verify:documentation, node
scripts/run-vitest.ts run tests/unit/backend-contract-pin-document.test.ts
Refs: 1106/03-01 (final review FR-02)
문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를
보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는
선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고
(scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와
상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이
선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과
불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로
남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지
않았다(최종 리뷰 FR-01).
고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일
때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind
줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는
상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400
VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다.
테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED +
선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다.
참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과
불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이
다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과
불명과 확인 버튼이 남는 테스트를 더했다.
버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지
폼과 훅에 알리지 않는다).
위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송
뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1
X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts,
리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (final review FR-01)