문제: 이 브랜치는 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건.
문제: 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이 되어 예외
목록에서 지웠다.
문제: 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건.
매뉴얼 예제 칸 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 통과.
문제
create:feature는 "모든 merge 게이트를 통과하는 가장 작은 기능"을 만든다고
적고, test:feature-scaffold(FE-GATE-020)가 그 주장을 지키는 유일한 드릴이다.
그런데 드릴은 손으로 적은 15개 명령만 돌았고 merge 단계는 명령 참조가
88개다. 그 범위 밖(시각 회귀, a11y, 번들, 계약·스키마·시나리오 테스트 등)에서
생성 기능을 깨는 템플릿 변경이 생겨도 FE-GATE-020은 통과했다(12-01·12-03이
실제로 그렇게 생겼다). 또 제품 기능 제거 드릴
(test:sample-removal -- --feature=<id>)은 어떤 게이트도 돌지 않아, 빈 사유
결함(16-02)이 드러나지 않았다.
고른 방법
- 새 scripts/lib/feature-scaffold-drill.ts가 fixture의 config/ci/gates.json
merge 단계를 단계 순서대로, 명령마다 한 번 뽑는다. 음성 fixture 명령은
run-ci-gate.ts처럼 등록된 종료 코드와 진단 ID로 판정한다.
- 돌지 않는 명령은 SCAFFOLD_DRILL_EXCLUDED_SCRIPTS에 이유와 함께 둔다:
브라우저 명령 7개(FE-GATE-020 job에 브라우저가 없다. merge_gate matrix
browser: false), test:system(bubblewrap·systemd·cgroup 필요, 기능과 무관한
provider 샌드박스 검사), verify:lockfile(연결한 node_modules에 install한다),
제거 드릴 5개(저장소를 다시 복사한다. 이 드릴 자신 포함). merge 단계에 없는
스크립트를 제외 목록에 두면 실패한다.
- 생성 기능을 merge 명령 뒤에 test:sample-removal -- --feature=scaffold-feature로
다시 지운다(16-02 둘째 절반).
- 생성 명령의 주석·Next 출력과 매뉴얼 두 곳의 주장을 실제 범위로 고쳤다.
- 버린 대안: 손 목록에 빠진 명령 더하기. 다음 merge 명령이 다시 빠진다. 복사본
에서 브라우저 게이트까지 전부(리뷰 5.1 (d)). 드릴 job에 브라우저가 없고 수십
분이 든다. 생성 경로만 도는 chromium a11y·시각 1회(5.1 (c)). 12-01·12-03을
고치는 다른 작업이 진행 중이라 지금 넣으면 그 수정 전까지 드릴이 실패한다.
그 둘이 들어오면 제외 목록에서 빼는 것을 다시 본다.
위험·한계
- 드릴 시간이 크게 는다(빌드·release candidate·coverage·제거 드릴 한 번).
FE-GATE-020 job(45분)의 임계 경로를 넘으면 리뷰 5.1 재검토 조건대로 줄인다.
tests/unit이 한 merge에서 도는 횟수(1101/10-06)도 는다.
- 이 커밋 메시지에는 드릴 전체 실행 결과를 적지 않았다(공유 잠금 대기).
검증
- RED: 새 tests/unit/feature-scaffold-drill.test.ts의 "is what
test:feature-scaffold runs"가 수정 전 실패.
- 수정 뒤 feature-scaffold-drill 5건(merge 명령 전부가 실행 또는 제외, 음성
fixture 기대 유지, merge 단계에 명령을 더하면 드릴이 돈다, 낡은 제외 거부,
드릴이 이 목록을 씀), create-feature, removal-fixture 합계 43건 통과.
verify:documentation PASS_SCOPED, check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는
SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을
여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의
브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야
안다.
고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다.
- 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig,
security.yml, application-local.yml, realm JSON).
- 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처
http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는
복사(import 금지).
- jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함),
제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시,
하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint).
- redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기,
프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건.
- 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인.
매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter-
recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만
적었다(매뉴얼 README 규칙).
위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서
첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다.
검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로·
명령·게이트 ID 누락 0).
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
문제: 프론트 업로드 레시피(PRESIGNED_MULTIPART_V1, 브라우저가 object
store에 직접 PUT)를 받는 서버가 짝 백엔드 템플릿에 없다. 짝 백엔드는
2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일은 자기
Fileserver가 직접 받는다(POST /v1/files, POST /v1/files:raw, tus). 그런데
서버 handoff 문서는 아직 "서버 구현 대기", "이후 서버 template에서 구현"
이라고 적고, docs/manual에는 업로드 언급이 없다. 팀은 조립 단계에서야
짝이 아님을 안다.
고친 방법(리뷰 D1 (다)):
- server-file-capability-infrastructure.md 상태 줄을 "짝 백엔드 템플릿은
구현하지 않음(2026-09-25 제거)"으로, 대상을 "제품 backend가 직접 구현"
으로 고치고 짝 아님 안내를 머리에 둔다.
- presigned-transfer-and-image-cdn.md 머리에 같은 안내를 둔다. presigned
다운로드와 private Image CDN descriptor 발급 서버도 짝 백엔드에 없다.
- 레시피 카탈로그 file-transfer의 fallback에 짝 백엔드 경로(Fileserver
POST /v1/files)를 적는다.
- docs/manual/02-decision-tables.md에 7절 "파일 업로드"를 더한다. 두 경로
비교와 고르는 기준이다. 매뉴얼 README의 목차 줄도 고친다.
위험·한계: 문서만 바꾼다. 짝 백엔드로 파일을 올리는 프론트 client는 이
커밋에 없다(다음 커밋, D1 (나-1)). 백엔드 매뉴얼에 같은 안내를 적는 일은
백엔드 repo 몫이라 하지 않았다.
검증:
- verify:documentation PASS_SCOPED
- check:optional-recipes:source PASS (file-transfer 56,084/57,800)
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
문제
- 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와
폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미,
결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패
메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다.
리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다.
- create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일
(a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다.
고른 방법
- docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과
안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일,
reference/ 4개(create-feature, global-ids, patterns, errors).
- 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다
정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을
적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트
밖 라우트는 이제 앱 모듈이 적재 때 거부한다).
- 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로
바꿨다.
- 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY,
게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿
docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은
design-docs의 conventions/feature-design-principles.md를 번호로만
가리킨다.
- 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지
않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는
것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만
더한다.
- 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조
페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다.
- 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고
지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기
(입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기
(메시지로 문서를 검색할 수 없다).
위험·한계
- docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는
verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래
.md만 검사하므로 reference/도 따로 링크해야 한다.
- 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절
번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다.
- 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만
둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능
테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다.
- "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시
돌리지 않았다.
검증
- docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고
node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서
모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다.
- 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두
말하며 FAIL_UNVERIFIED.
- 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고,
42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩
코드에서 확인했다.
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
tests/unit/deletable-history-documents.test.ts
tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과.