Commit Graph
3 Commits
Author SHA1 Message Date
DongHyeonka 16202fd48d fix(docs): 현재 계약 문서의 경로·명령·게이트 ID를 검사한다 (14-05)
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).

고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
  artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
  ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
  (ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
  starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
  가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
  적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
  문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
  작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
  기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
  읽는다), README "Files you can delete after copying"의 이력 중 지워진
  것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
  FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
  적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
  3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
  경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
  ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
  모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.

위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
  링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
  경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
  시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
  계약 문서(README, compatibility.md, starter-experience.md,
  manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
  복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
  본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.

검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
  기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
  "failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
  통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
  tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
  돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
  고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
  EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
  deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
  eslint 통과. check-ci-contract, generate-artifact-schemas --check,
  generate-ci-workflow --check, check-adapter-inventory 통과.
  check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
  이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
2026-11-03 01:13:16 +09:00
DongHyeonka 61baf96682 fix(docs): 입구 문서를 실제 src 폴더 9개와 규칙 이름에 맞추고 검사한다 (14-03)
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.

고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
  목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
  기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
  domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
  실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
  않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
  방향(presentation -> application -> contracts -> platform,
  apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
  platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
  .dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
  나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
  src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
  documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
  하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.

위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
  않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
  계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
  네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
  코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.

검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
  (failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
  모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
  tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
  규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
  platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
  173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
  16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).

Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
2026-11-03 00:54:44 +09:00
DongHyeonka f13ed7bea7 fix(docs): verify:documentation이 실패한 검사와 고칠 파일을 적는다 (1101/14-06)
문제
verify-documentation-readiness.ts는 실패 원인과 상관없이 마지막에
"FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"를
적는다. stderr에 따로 적는 것은 README 빌드 변수 누락뿐이다. 기능을
더해 route가 늘었는데 README나 접근성 체크리스트에 route ID를 안 적으면,
개발자는 diagram 리뷰 기록을 먼저 의심하고 산출물 JSON을 열어야 원인을
안다.

고른 방법
- 검사 네 개(route scope, runtime variables, review report digest,
  diagram reviews)의 실패를 failedChecks로 모으고 passed는 그것이 비었는지로
  정한다. 판정 조건은 그대로다.
- 실패하면 검사마다 고칠 곳을 stderr에 적는다. route scope는 문서별로
  빠진 route ID, diagram review는 어느 diagram이 증거 문서에 PASS로 없는지.
- 마지막 줄은 "FAIL_UNVERIFIED (failed: <검사 이름들>)"이다. 판정 토큰은
  그대로 둬서 이 줄을 읽는 쪽이 바뀌지 않는다.

버린 대안
- route ID 누락만 따로 적기(리뷰의 최소 방향): 다음에 다른 검사가 실패해도
  같은 엉뚱한 문구가 나온다. 검사 네 개 모두 같은 방식으로 적어도 몇 줄이다.

위험·한계
- diagram review 실패는 어느 하위 조건(경로·digest·점수)인지까지는 적지
  않는다. 산출물 JSON의 results에 그대로 있다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
  2 failed. README에서 `EXAMPLES_PLATFORM`을 지운 사본에서 stderr가
  "Documentation readiness: FAIL_UNVERIF…"뿐이라 "README.md does not name
  route IDs: EXAMPLES_PLATFORM"이 없다. 두 검사 실패 때도 실패 이름이 없다
- GREEN: 같은 파일 3 passed(원본 사본 PASS, route 하나 누락,
  route+변수 누락)
- 실제 repo에서 verify-documentation-readiness PASS_SCOPED
- eslint, tsc(node, test), check-ci-contract PASS

Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-06
2026-11-01 22:49:13 +09:00