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에서 금지).
This commit is contained in:
DongHyeonka
2026-11-03 01:13:16 +09:00
parent 3e58cade5d
commit 16202fd48d
10 changed files with 373 additions and 116 deletions
+11 -15
View File
@@ -82,16 +82,14 @@ list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-ga
## Included starter experience
The default build mounts a domain-neutral application shell with a header,
responsive sidebar, route focus management, session integration status, and a
persistent `system` / `light` / `dark` theme selector.
responsive sidebar, route focus management, session integration status, a
persistent `system` / `light` / `dark` theme selector, and a language selector.
| Route | Purpose |
| --- | --- |
| `/` | implementation readiness and starter links |
| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
| `/examples/auth` | reactive external-auth integration seam |
| `/examples/reference-resources` | removable, session-required reference feature |
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
the platform routes of `src/contracts/routes.ts` plus the routes of every
installed feature, the removable reference feature included. The platform
overview page (`/examples/platform`) shows the composed list at runtime, so
this README keeps no copy of it and adding a feature does not edit it.
`AUTH_MODE=demo` is credential-free and accepted only in local/development
environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
@@ -295,12 +293,10 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
keyboard/focus/screen-reader review for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
`EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`, `NOT_FOUND`,
`REFERENCE_RESOURCE_LIST`, `REFERENCE_RESOURCE_DETAIL`,
`REFERENCE_RESOURCE_FORM` and `REFERENCE_RESOURCE_STATUS`.
`verify:documentation` derives that list from the route registry and fails if
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
keyboard/focus/screen-reader review of every registered route, one record
per route at `artifacts/tests/a11y-manual/<ROUTE_ID>.md`. The routes are
`ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a
registered route has no record. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
keeps the template's fields, reviewed or still pending.
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
+8 -1
View File
@@ -37,11 +37,18 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. `CHANGELOG.md`는
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
`scripts/verify-documentation-readiness.ts`다.
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) |
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
| repo 루트의 `artifacts/tests/a11y-manual/` 라우트별 기록 | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
+11 -13
View File
@@ -1,14 +1,12 @@
# Manual accessibility review checklist
Automated axe checks do not establish WCAG conformance. A human reviewer must
review all ten route records in `artifacts/tests/a11y-manual/` against one
release candidate and sign them. The required scope is derived from the route
registry: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`,
`EXAMPLES_AUTH`, `NOT_FOUND`, `REFERENCE_RESOURCE_LIST`,
`REFERENCE_RESOURCE_DETAIL`, `REFERENCE_RESOURCE_FORM` and
`REFERENCE_RESOURCE_STATUS`. Copy the template fields exactly; the gate rejects
blank identity/timestamp/signature fields, pending verdicts, mismatched release
IDs, or missing routes.
review every route record in `artifacts/tests/a11y-manual/` against one
release candidate and sign them. The required scope is the route registry
(`ROUTE_REGISTRY` in `src/features/installed-feature-contracts.ts`): one
record per route, named `<ROUTE_ID>.md`. Copy the template fields exactly; the
gate rejects blank identity/timestamp/signature fields, pending verdicts,
mismatched release IDs, or missing routes.
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
it is required once per release candidate, not on every merge. The merge gate
@@ -16,11 +14,11 @@ FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
and a record marked `reviewed` must be complete.
This list is not maintained by hand: `verify:documentation` compares it against
the installed route registry and fails when a registered route is absent. It
said six routes while ten were registered, which put the platform overview and
the three reference-resource screens outside the declared manual review scope
without anyone deciding they should be.
This document keeps no route list. A list here once said six routes while ten
were registered, and keeping it current made every new feature edit this file.
Instead `verify:documentation` fails, naming the route ID, when a registered
route has no record file. A new route starts from a copy of a pending record
with its title and `Route ID` changed.
Allowed item verdicts:
+10 -10
View File
@@ -20,15 +20,15 @@ reader that accepts it must ship before any writer sends it.
| Boundary | Reader policy | Adding a field or value | Code |
|---|---|---|---|
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` |
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` |
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` |
| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` |
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` |
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` |
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` |
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` |
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:148-150` |
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `runtimeConfigV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `capabilityOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
| Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/schema-registry.ts` |
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in `src/features/reference-feature/contracts/reference-schemas.ts` |
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` |
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` |
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` |
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
vary per build because each downstream project installs its own features, and
@@ -39,7 +39,7 @@ addition.
## Schema change classifier and FE-GATE-014
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts`) answers
for a reader built against `before`. It is fail-closed: only a new property
under a reader without `additionalProperties: false` is `additive`. A removed
or changed property (type, enum, nullable, format, ...), a different required
+13 -8
View File
@@ -5,6 +5,11 @@
>
> Plan: [2026-08-13 adapter remediation](../superpowers/plans/2026-08-13-adapter-remediation.md).
> Baseline revision: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
>
> Test paths are given at their current location. Two suites moved after
> these runs: `ci-artifact-contract.test.ts` from `tests/unit/` to
> `tests/system/ci-runner/`, and `provider-guardian-transaction.test.ts` from
> `tests/unit/` to `tests/integration/`.
## Containment state (plan Task 1, Step 1)
@@ -44,7 +49,7 @@ Captured on the baseline revision before any source change.
### `test:unit` failure attribution
The single failing file is `tests/unit/ci-artifact-contract.test.ts`. All 19 failures come from
The single failing file is `tests/system/ci-runner/ci-artifact-contract.test.ts`. All 19 failures come from
child-process, cgroup, and filesystem-permission behavior of the sandboxed execution
environment, not from adapter code. Verbatim causes recorded from the run log:
@@ -208,7 +213,7 @@ No finding remains `NOT_STARTED`.
| Gate | Status | Attribution |
| --- | --- | --- |
| `tests/unit/ci-artifact-contract.test.ts` | 19 failed | Identical to the baseline capture. Sandbox child-process, cgroup and `/tmp` permission behavior; unrelated to adapters. Count did not change across any task. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 failed | Identical to the baseline capture. Sandbox child-process, cgroup and `/tmp` permission behavior; unrelated to adapters. Count did not change across any task. |
| `corepack pnpm test:browser-capabilities` (webkit) | 6 failed / 24 passed | WebKit cannot launch: missing `libevent-2.1-7t64` and `libavif16`. Chromium passes. **UNVERIFIED**, not PASS. |
| `corepack pnpm test:browser-file-storage-removal` | exit 1 | The reduced-removal-fixture prunes the CI contract to 77/89/102 while `scripts/contracts/ci-gates.ts:481` demands exactly 81/93/105. That file, the CI contract and `scripts/lib/removal-fixture.ts` are **unchanged since the baseline revision** (`git diff --name-only 4dc033c..HEAD` outside `src/`, `tests/` and `docs/` lists only the two Service Worker build scripts), so this is pre-existing, not a regression from this work. |
| `corepack pnpm test:realtime-removal` | exit 1 | Same pre-existing reduced-fixture arithmetic. |
@@ -336,8 +341,8 @@ Run on the landed tree. Only what actually passed is claimed as passing.
| Gate | Status | Attribution |
| --- | --- | --- |
| `tests/unit/ci-workflow-generation.test.ts` | 82 failed / 325 passed | Identical on the pre-change baseline (`git stash` comparison). The subprocess gates it spawns cannot run in this sandbox. |
| `tests/unit/ci-artifact-contract.test.ts` | fails | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
| `tests/unit/security-followup.test.ts`, `tests/unit/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | flaky under full-suite load | Historical baseline result. All three passed in a fresh process (78 passed together). |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | fails | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
| `tests/unit/security-followup.test.ts`, `tests/integration/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | flaky under full-suite load | Historical baseline result. All three passed in a fresh process (78 passed together). |
> Current classification update (2026-09-18): the provider guardian transaction
> suite moved to `tests/integration/provider-guardian-transaction.test.ts`.
@@ -356,7 +361,7 @@ fixture with a single directory symlink at `<fixture>/node_modules`:
- `scripts/lib/removal-fixture.ts`
- `scripts/check-supply-chain-provider-fixtures.ts`
- `tests/integration/security-followup-archive.test.ts`
- `tests/unit/ci-artifact-contract.test.ts`
- `tests/system/ci-runner/ci-artifact-contract.test.ts`
Each fixture then runs `pnpm` inside itself. pnpm does not recognise the modules
directory it finds there and purges it; with `CI=true` it does so without a
@@ -380,9 +385,9 @@ files above plus the two flaky-under-load ones:
| File | Failed | Attribution |
| --- | ---: | --- |
| `tests/unit/ci-workflow-generation.test.ts` | 82 | Identical on the pre-change baseline (`git stash` comparison). Its subprocess gates cannot run in this sandbox. |
| `tests/unit/ci-artifact-contract.test.ts` | 19 | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
| `tests/unit/security-followup.test.ts` | 2 | Passes in isolation. |
| `tests/unit/provider-guardian-transaction.test.ts` (historical path; now `tests/integration/provider-guardian-transaction.test.ts`) | 1 | Historical baseline: passed in isolation; current suite is classified as process integration. |
| `tests/integration/provider-guardian-transaction.test.ts` | 1 | Historical baseline: passed in isolation; current suite is classified as process integration. |
1619 passed / 1723 total, and `tests/unit/removal-fixture.test.ts`,
`tests/unit/supply-chain.test.ts` and
@@ -465,7 +470,7 @@ forward as if it were green.
The full `tests/unit` + `tests/integration` run is **1,845 passed / 1,864**,
128 of 129 files green. Every one of the 19 failures is in
`tests/unit/ci-artifact-contract.test.ts` and is the pre-existing sandbox,
`tests/system/ci-runner/ci-artifact-contract.test.ts` and is the pre-existing sandbox,
cgroup, RLIMIT and `/tmp` permission behaviour already recorded above — the same
file failed identically before this work. No adapter test fails.
+9 -4
View File
@@ -126,11 +126,16 @@ DOCUMENTATION_READY (off-chain)
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
(`scripts/verify-documentation-readiness.ts`).
- diagram 리뷰 ledger(`docs/architecture/review-ledger.json`)와
`review-evidence.md`가 같은 경로·해시·점수를 담는지
- README와 `docs/accessibility/manual-checklist.md`가 설치된 route ID를 모두
적는지
- 설치된 라우트마다 수동 접근성 기록 `artifacts/tests/a11y-manual/<ROUTE_ID>.md`가
있는지. 없으면 route ID를 적고 실패한다
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
적는지
- `docs/README.md` 1절의 현재 계약 문서에 적힌 repo 경로·링크·package script·
FE-GATE ID가 실제로 있는지
- 2026-07-18 diagram 리뷰 기록의 두 사본(`docs/architecture/review-ledger.json`,
`review-evidence.md`)이 같은 해시·점수를 담는지. 원본 diagram은 repo 밖에
있으므로 이 항목은 구조가 바뀌어도 통과한다
문서의 다른 내용(수치, 목록, 설명)이 코드와 맞는지는 검사하지 않는다(리뷰 14-07).
+27 -3
View File
@@ -1,8 +1,32 @@
# Design-token styling contract
`src/presentation/styles/theme.css` is the styling SSOT. Components consume
semantic color, spacing, typography, status, and radius tokens through static
classes. `/examples/ui` is the executable token and primitive gallery.
Tokens are defined in three layers under `src/presentation/design-system/tokens/`:
`primitive.css` holds the raw palette and scales, `semantic.css` maps them to
roles (surface, content, border, action, status) and overrides those roles for
the dark theme, and `component.css` maps roles to per-component values.
`src/presentation/styles/theme.css` only imports the three files and the style
files under `src/presentation/styles/theme/`. Components consume semantic
color, spacing, typography, status, and radius tokens through static classes.
`/examples/ui` is the executable token and primitive gallery.
## Rules a rebrand must keep
`check:design-system` (`scripts/check-design-system.ts`) fails when a token
edit breaks one of these. The reasons are next to each rule in
`scripts/lib/design-system-rules.ts`.
- UI-01: `--color-focus` has at least 3:1 contrast against every surface a
focus ring can sit on, in both themes. Those tokens must resolve to opaque
`oklch()` values so the contrast can be computed.
- UI-02: `color-mix()` mixes in `oklab`, never in a hue-based space.
- UI-03: every component token is read by some style.
- UI-05: `--font-sans` starts with a generic family or one the repository
ships with `@font-face`.
The same check requires the token names in `token-contract.ts`, the dark
overrides of the core semantic roles, a forced-colors fallback in
`component.css`, no raw palette values outside the token files, and no direct
headless-library imports.
## Theme contract
+22 -4
View File
@@ -1393,9 +1393,9 @@ export const documentationReviewArtifactSchema = z
.strict(),
reportDigestValid: z.boolean(),
/**
* The declared review scope, derived from the installed route registry
* rather than read off a sentence. Both scope documents claimed six routes
* while ten were registered.
* The manual accessibility review scope: the installed routes that have no
* record file under artifacts/tests/a11y-manual/. It is derived from the
* route registry, not read off a document (1101/14-05).
*/
routeScope: z.array(
z
@@ -1421,6 +1421,18 @@ export const documentationReviewArtifactSchema = z
})
.strict(),
).min(1),
// 1101/14-05: repo paths, package scripts and gate IDs that the current
// contract documents (docs/README.md §1) name but that do not exist.
documentReferences: z.array(
z
.object({
path: nonEmptyString,
missingPaths: z.array(nonEmptyString),
missingScripts: z.array(nonEmptyString),
unknownGateIds: z.array(nonEmptyString),
})
.strict(),
).min(1),
results: z.array(
z
.object({
@@ -1466,9 +1478,15 @@ export const documentationReviewArtifactSchema = z
entry.unknownFolders.length === 0 &&
entry.missingRules.length === 0,
) &&
artifact.documentReferences.every(
(entry) =>
entry.missingPaths.length === 0 &&
entry.missingScripts.length === 0 &&
entry.unknownGateIds.length === 0,
) &&
artifact.results.every(({ passed }) => passed))
) {
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure and review results" });
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references and review results" });
}
});
+172 -39
View File
@@ -1,24 +1,22 @@
import { access, mkdir, readdir, readFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import { mkdir, readdir, readFile } from "node:fs/promises";
import { dirname, join, matchesGlob, normalize } from "node:path/posix";
import { fileURLToPath } from "node:url";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts";
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
/**
* Documents that state the review scope. The route registry is the source of
* truth for what that scope is, so these have to enumerate exactly the
* installed routes.
*
* Both said "six routes" while ten were registered: the four newest — the
* platform overview and three reference-resource screens — were outside the
* declared manual accessibility scope without anybody deciding they should be.
* A hand-typed count drifts silently, so it is derived here instead.
* The manual accessibility review scope is one record per installed route.
* README and the checklist used to list the route IDs and this script checked
* the lists (they had said six routes while ten were registered). That made
* every new feature edit two template-owned documents (1101/14-05), so the
* documents now name this folder and the record files are what is checked.
*/
const ROUTE_SCOPE_DOCUMENTS = Object.freeze([
"README.md",
"docs/accessibility/manual-checklist.md",
]);
const MANUAL_A11Y_RECORDS = "artifacts/tests/a11y-manual/";
type DocumentationReview = Readonly<{
sourcePath: string;
@@ -77,25 +75,13 @@ const reportDigestValid =
/^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) &&
evidence.includes(ledger.evidenceReport.canonicalSha256);
const installedRouteIds = Object.values(ROUTE_REGISTRY)
.map((route) => route.routeId)
.sort();
const routeScope = [];
for (const path of ROUTE_SCOPE_DOCUMENTS) {
let text: string;
try {
await access(path);
text = await readFile(path, "utf8");
} catch {
routeScope.push({ path, missingRouteIds: [...installedRouteIds], documented: false });
continue;
}
const missingRouteIds = installedRouteIds.filter(
(routeId) => !text.includes(routeId),
);
routeScope.push({ path, missingRouteIds, documented: missingRouteIds.length === 0 });
}
const routeScopeDocumented = routeScope.every((entry) => entry.documented);
const missingRouteIds = MANUAL_A11Y_ROUTE_IDS.filter(
(routeId) => !existsSync(`${MANUAL_A11Y_RECORDS}${routeId}.md`),
).sort();
const routeScope = [
{ path: MANUAL_A11Y_RECORDS, missingRouteIds, documented: missingRouteIds.length === 0 },
];
const routeScopeDocumented = missingRouteIds.length === 0;
// 13-15. README is where a project learns how to build for production. It
// named none of the variables the build and admission read, so each one is
@@ -164,16 +150,150 @@ const sourceStructureDocumented = sourceStructure.every(
entry.missingRules.length === 0,
);
// 1101/14-05. docs/README.md §1 says the gates check the current contract
// documents, while only the checks above did. Every repo path, package script
// and FE-GATE ID that the index and the documents its §1 links name must
// exist. Documents are read from the working directory; what they name is
// looked up in this repository, as for the src structure above.
const DOCUMENT_INDEX = "docs/README.md";
// Past states are its subject: it names removed scripts and paths on purpose.
const UNCHECKED_DOCUMENTS = new Set(["CHANGELOG.md"]);
const NOT_CREATED = new Set([
// Reserved by generic-worker-has-no-network-or-credentials. The generic CPU
// worker is NOT_SELECTED (tsconfig.web-worker.json).
"src/adapters/web-worker",
]);
// pnpm's own commands, which are not package scripts.
const PNPM_COMMANDS = new Set(["add", "dlx", "exec", "install", "list", "why"]);
const rootDirectory = fileURLToPath(repositoryRoot);
const exists = (file: string) => existsSync(join(rootDirectory, file));
const topLevelEntries = new Set(await readdir(rootDirectory));
const scripts = new Set(
Object.keys(
(JSON.parse(await readFile(join(rootDirectory, "package.json"), "utf8")) as { scripts: Record<string, string> })
.scripts,
),
);
const scriptPrefixes = new Set([...scripts].map((name) => name.split(":")[0]));
const gateIds = new Set([
...(
JSON.parse(await readFile(join(rootDirectory, "config/ci/gates.json"), "utf8")) as { gates: { id: string }[] }
).gates.map((gate) => gate.id),
...RETIRED_GATE_IDS,
]);
// Generated output is what git ignores, so a document may name it before a
// run has written it.
const ignorePatterns = (await readFile(join(rootDirectory, ".gitignore"), "utf8").catch(() => ""))
.split("\n")
.map((line) => line.trim())
.filter((line) => line !== "" && !line.startsWith("#"));
function generated(file: string): boolean {
let ignored = false;
for (const line of ignorePatterns) {
const pattern = line.replace(/^!/u, "").replace(/^\/|\/$/gu, "");
const glob = pattern.includes("/") ? pattern : `**/${pattern}`;
if (matchesGlob(file, glob) || matchesGlob(file, `${glob}/**`)) ignored = !line.startsWith("!");
}
return ignored;
}
// A copy may delete the history README lists under "Files you can delete
// after copying". A path under an entry that is gone is not drift.
const deletedHistory = [
...(readme.match(/^### Files you can delete after copying\n[\s\S]*?(?=^#)/mu)?.[0] ?? "").matchAll(
/^\| (.+?) \|/gmu,
),
]
.flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, "")))
.filter((entry) => !exists(entry));
// A backtick span is a path when it starts at a top-level entry or at an
// entry beside the document; line numbers and anchors are dropped.
function namedPath(token: string, document: string): string | null {
const candidate = token.replace(/#.*$/u, "").replace(/:\d[\d,:-]*$/u, "");
if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|]|\.\.\./u.test(candidate)) return null;
const first = candidate.split("/")[0] ?? "";
if (topLevelEntries.has(first)) return candidate;
return first !== "." && first !== ".." && exists(join(dirname(document), first))
? join(dirname(document), candidate)
: null;
}
function linkedPath(target: string, document: string): string | null {
if (/^(?:[a-z][a-z+.-]*:|#)/iu.test(target)) return null;
const resolved = normalize(join(dirname(document), target.replace(/#.*$/u, "")));
return resolved.startsWith("../") ? null : resolved;
}
const index = await readFile(DOCUMENT_INDEX, "utf8").catch(() => "");
const contractDocuments = new Set([DOCUMENT_INDEX]);
for (const [, target = ""] of (index.match(/^## 1\.[\s\S]*?(?=^## )/mu)?.[0] ?? "").matchAll(/\]\(([^)#\s]+)\)/gu)) {
const linked = normalize(join(dirname(DOCUMENT_INDEX), target));
const entries = await readdir(linked).catch(() => null);
const documents =
entries === null ? [linked] : entries.filter((name) => name.endsWith(".md")).map((name) => join(linked, name));
for (const document of documents) if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document);
}
const documentReferences = [];
for (const document of contractDocuments) {
const text = await readFile(document, "utf8").catch(() => null);
if (text === null) {
// A linked document that is gone is reported as the index's broken link.
if (document === DOCUMENT_INDEX) {
documentReferences.push({ path: document, missingPaths: [document], missingScripts: [], unknownGateIds: [] });
}
continue;
}
const named = [
...[...text.matchAll(/`([^`\n]+)`/gu)].map(([, token = ""]) => namedPath(token, document)),
...[...text.matchAll(/\]\(([^)\s]+)\)/gu)].map(([, target = ""]) => linkedPath(target, document)),
];
const missingPaths = new Set<string>();
for (const file of named) {
if (file === null) continue;
const trimmed = file.replace(/\/$/u, "");
if (
!exists(trimmed) &&
!NOT_CREATED.has(trimmed) &&
!generated(trimmed) &&
!deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`))
) {
missingPaths.add(trimmed);
}
}
const missingScripts = new Set<string>();
for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) {
if (!PNPM_COMMANDS.has(name) && !scripts.has(name)) missingScripts.add(name);
}
for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) {
if (scriptPrefixes.has(name.split(":")[0]) && !scripts.has(name)) missingScripts.add(name);
}
documentReferences.push({
path: document,
missingPaths: [...missingPaths].sort(),
missingScripts: [...missingScripts].sort(),
unknownGateIds: [...new Set([...text.matchAll(/\bFE-GATE-\d+\b/gu)].map(([id]) => id))]
.filter((id) => !gateIds.has(id))
.sort(),
});
}
const documentReferencesValid = documentReferences.every(
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
);
// 1101/14-06. Each failed check is named, so the stderr points at the file to
// fix rather than at the diagram review whatever failed.
// fix rather than at the diagram review whatever failed. 1101/14-05: the last
// two only compare the two hand-kept copies of the 2026-07-18 diagram review;
// the diagrams are outside this repository, so they pass whatever the
// structure becomes, and their names say so.
const failedChecks = [
...(routeScopeDocumented ? [] : ["route scope"]),
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
...(sourceStructureDocumented ? [] : ["source structure"]),
...(reportDigestValid ? [] : ["review report digest"]),
...(documentReferencesValid ? [] : ["document references"]),
...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]),
...(results.length === 2 && results.every((result) => result.passed)
? []
: ["diagram reviews"]),
: ["2026-07-18 diagram review copies"]),
];
const passed = failedChecks.length === 0;
await mkdir("artifacts/quality", { recursive: true });
@@ -192,14 +312,14 @@ await writeValidatedJsonArtifact({
routeScopeDocumented,
missingRuntimeVariables,
sourceStructure,
documentReferences,
results,
passed,
},
});
if (!passed) {
for (const entry of routeScope) {
if (entry.documented) continue;
process.stderr.write(`${entry.path} does not name route IDs: ${entry.missingRouteIds.join(", ")}\n`);
if (!routeScopeDocumented) {
process.stderr.write(`${MANUAL_A11Y_RECORDS} has no record for route IDs: ${missingRouteIds.join(", ")}\n`);
}
if (missingRuntimeVariables.length > 0) {
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
@@ -217,6 +337,19 @@ if (!passed) {
);
}
}
for (const entry of documentReferences) {
if (entry.missingPaths.length > 0) {
process.stderr.write(`${entry.path} names paths that do not exist: ${entry.missingPaths.join(", ")}\n`);
}
if (entry.missingScripts.length > 0) {
process.stderr.write(`${entry.path} names package scripts that do not exist: ${entry.missingScripts.join(", ")}\n`);
}
if (entry.unknownGateIds.length > 0) {
process.stderr.write(
`${entry.path} names gate IDs that config/ci/gates.json does not define: ${entry.unknownGateIds.join(", ")}\n`,
);
}
}
if (!reportDigestValid) {
process.stderr.write(
`${ledger.evidenceReport.repoPath} does not contain the ledger's canonicalSha256\n`,
+90 -19
View File
@@ -5,23 +5,25 @@ import path from "node:path";
import { describe, expect, it } from "vitest";
const INPUTS = [
"README.md",
"docs/accessibility/manual-checklist.md",
"docs/architecture/review-ledger.json",
"docs/architecture/review-evidence.md",
"docs/architecture/layers.md",
"docs/architecture/overview.md",
"docs/architecture/frontend-application-foundation.md",
];
const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual"];
/** Runs verify:documentation on a copy of its inputs, `mutate` applied to `document`. */
async function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
/**
* Runs verify:documentation on a copy of its inputs, each `changes` entry
* applied to its document and every `removed` file deleted. Code facts (src,
* package.json, gates.json) are read from this repository, not the copy.
*/
async function verify(
changes: Readonly<Record<string, (text: string) => string>>,
removed: readonly string[] = [],
) {
const root = await mkdtemp(path.join(tmpdir(), "documentation-readiness-"));
try {
for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true });
const target = path.join(root, document);
await writeFile(target, mutate(await readFile(target, "utf8")));
for (const [document, mutate] of Object.entries(changes)) {
const target = path.join(root, document);
await writeFile(target, mutate(await readFile(target, "utf8")));
}
for (const file of removed) await rm(path.join(root, file));
return spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
cwd: root,
encoding: "utf8",
@@ -31,32 +33,101 @@ async function verifyWithReadme(mutate: (readme: string) => string, document = "
}
}
function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
return verify({ [document]: mutate });
}
// 1101/14-06. A route missing from a scope document used to fail with only
// "canonical scoped-review evidence is incomplete", which points at the
// diagram review instead of the document to fix.
// diagram review instead of the file to fix.
describe("verify:documentation failure output (1101/14-06)", () => {
it("passes the documents as they are", async () => {
const result = await verifyWithReadme((readme) => readme);
expect(result.status, result.stderr).toBe(0);
});
it("names the document and the route ID it is missing", async () => {
const result = await verifyWithReadme((readme) => readme.replaceAll("`EXAMPLES_PLATFORM`", ""));
it("names the route ID that has no manual review record", async () => {
const result = await verify({}, ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"]);
expect(result.status).toBe(1);
expect(result.stderr).toContain("README.md does not name route IDs: EXAMPLES_PLATFORM");
expect(result.stderr).toContain("artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_PLATFORM");
expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u);
expect(result.stderr).not.toContain("scoped-review evidence");
});
it("names every failed check", async () => {
const result = await verifyWithReadme((readme) =>
readme.replaceAll("`EXAMPLES_PLATFORM`", "").replaceAll("`RELEASE_TARGET`", ""),
const result = await verify(
{ "README.md": (readme) => readme.replaceAll("`RELEASE_TARGET`", "") },
["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"],
);
expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET");
expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u);
});
});
// 1101/14-05. README and the manual checklist listed every route ID, so each
// new feature edited two template-owned documents. The scope is the record
// files now, and the current contract documents (docs/README.md §1) may only
// name paths, package scripts and gate IDs that exist.
describe("verify:documentation current contract documents (1101/14-05)", () => {
const ROUTE_IDS = /`(?:APP_HOME|EXAMPLES_[A-Z]+|NOT_FOUND|REFERENCE_RESOURCE_[A-Z]+)`/gu;
it("does not need README or the checklist to list route IDs", async () => {
const result = await verify({
"README.md": (readme) => readme.replaceAll(ROUTE_IDS, ""),
"docs/accessibility/manual-checklist.md": (checklist) => checklist.replaceAll(ROUTE_IDS, ""),
});
expect(result.status, result.stderr).toBe(0);
});
it.each([
["README.md", "scripts/verify-documentation-readiness.ts", "scripts/verify-documentation-readyness.ts"],
["docs/contracts/compatibility.md", "scripts/check-compatibility.ts", "scripts/check-compatibilty.ts"],
// reached through the `operations/` directory link
["docs/operations/release-cache-rollback.md", "scripts/lib/hosting-probe.ts", "scripts/lib/hosting-prob.ts"],
])("fails when %s names a path that does not exist", async (document, before, after) => {
const result = await verifyWithReadme((text) => text.replace(`\`${before}\``, `\`${after}\``), document);
expect(result.status).toBe(1);
expect(result.stderr).toContain(`${document} names paths that do not exist: ${after}`);
expect(result.stderr).toMatch(/\(failed: document references\)/u);
});
it("fails when docs/README.md links a document that does not exist", async () => {
const result = await verifyWithReadme(
(index) => index.replace("(architecture/layers.md)", "(architecture/layer.md)"),
"docs/README.md",
);
expect(result.status).toBe(1);
expect(result.stderr).toContain("docs/README.md names paths that do not exist: docs/architecture/layer.md");
});
it("fails when a document names a package script or a gate ID that does not exist", async () => {
const result = await verify({
"README.md": (readme) => readme.replace("`verify:documentation` fails", "`verify:documentaton` fails"),
"docs/README.md": (index) => index.replace("(FE-GATE-017)", "(FE-GATE-099)"),
});
expect(result.status).toBe(1);
expect(result.stderr).toContain("README.md names package scripts that do not exist: verify:documentaton");
expect(result.stderr).toContain("docs/README.md names gate IDs that config/ci/gates.json does not define: FE-GATE-099");
});
it("does not ask generated output to exist", async () => {
const result = await verifyWithReadme((readme) => `${readme}\nSee \`artifacts/quality/not-generated-yet.json\`.\n`);
expect(result.status, result.stderr).toBe(0);
});
it("accepts a path under history a copy deleted, and only that", async () => {
const naming = (readme: string) => `${readme}\nSee \`docs/retired-notes/plan.md\`.\n`;
const deleted = await verifyWithReadme((readme) =>
naming(readme).replace("| Path | Contents |\n| --- | --- |\n", "$&| `docs/retired-notes/` | deleted |\n"),
);
expect(deleted.status, deleted.stderr).toBe(0);
const missing = await verifyWithReadme(naming);
expect(missing.status).toBe(1);
expect(missing.stderr).toContain("README.md names paths that do not exist: docs/retired-notes/plan.md");
});
});
// 1101/14-03. The entry documents drew a top-level domain layer that does not
// exist, left out three of the nine src folders, and layers.md named a
// minority of the architecture rules while claiming it could not drift.