a135fa8a09f9b88b7ada4dcb2ab65efe096ca314
8
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
fc95672ad5 |
fix(docs): 문서 검사가 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다
문제 verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의 작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은 옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1, 짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면 pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는 "확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지 않았다. 고른 방법 - 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이 작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서). - 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의 트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다. hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다. - checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신 unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다. - `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다. 실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다. - 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만 pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다 `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다. 위험·한계 - pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부 "not verified"다. 실패하지 않는 대신 확인도 하지 않는다. - 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터 바꿔야 한다. - pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다. - 보고서 schema는 그대로다(unverifiedLinks 주석만 고침). 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED + not verified 기대). - RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or the working tree", "reports the references as not verified when the checkout does not have the pinned commit", "fails a link out of the repository into a repository that is not paired". Refs: 1105/12-02 |
||
|
|
4401ffa1ac |
test(docs): 문서 검사 보고서 타입에 missingPaths 칸을 적는다
문제 직전 커밋(짝 저장소 참조 테스트 범위 축소)이 보고서의 missingPaths를 읽지만, 테스트가 JSON을 읽을 때 쓰는 타입에 그 칸이 없어 check:types가 TS2339로 실패한다. vitest는 타입을 보지 않아 테스트는 통과했다. 고른 방법 - 보고서 타입에 missingPaths?: string[]를 더한다. 검증 - check:types 통과, documentation-readiness 테스트 19건 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05 |
||
|
|
e979c494b3 |
test(docs): 짝 저장소 참조 검사 테스트가 고친 문서만 본다
문제 fix/r1103-gates(12-05)의 테스트는 옆 checkout을 흉내 낸 stub(백엔드 문서 1개)을 두고 verify:documentation 전체가 통과하기를 기대한다. 다른 브랜치를 합치자 실제 문서(매뉴얼 02·04, 백엔드 계약 문서)가 stub에 없는 백엔드 경로를 가리켜, 테스트가 status 1로 실패한다. 결함은 문서가 아니라 테스트 범위에 있다. 그 경로 14개는 실제 옆 checkout에 모두 있다. 고른 방법 - "있는 경로" 경우에서 전체 status 대신, 테스트가 고친 문서 (CI_DOC)에 빠진 경로가 없는지만 본다(stderr와 보고서 missingPaths). - 버린 대안: stub에 실제 문서가 가리키는 백엔드 경로를 모두 만든다. 문서가 바뀔 때마다 테스트도 같이 바뀌어야 한다. 위험·한계 - 다른 문서의 짝 저장소 경로가 틀리면 이 테스트로는 잡지 않는다. 실제 옆 checkout이 있는 개발 환경의 verify:documentation이 잡는다. 검증 - tests/unit/documentation-readiness.test.ts 19건 통과. - 실제 백엔드 checkout에서 문서가 가리키는 경로 14개 존재 확인. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05 |
||
|
|
b6bfc9b7d9 |
fix(removal): sample 제거 fixture의 문서 검사를 fixture 전용 삭제와 맞춘다
문제 |
||
|
|
b4e4f98c03 |
fix(docs): 문서 검사가 명령 안 경로와 짝 저장소 참조를 본다
문제 verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서 `corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의 명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장 docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께 지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도 알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger 사유는 "It passes at this commit"이라는 시점 문장을 담았다. 고른 방법 - 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서 명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash, sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고, --flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로 경로로 보지 않는다. - 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick 경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이 있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다. 보고서 schema에 그 칸을 더했다. - 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고, ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을 고쳤다. - 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고 오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛 경로를 적어 예외가 늘어난다. 위험·한계 - 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다. - 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이 있는 개발 환경에서만 된다. - 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다. 검증 - RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소 없음 보고) 실패. - 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가 "names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified). check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05 |
||
|
|
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: 새 테스트를 기준(
|
||
|
|
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: 새 검사를 기준 커밋(
|
||
|
|
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 |