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
This commit is contained in:
+4
-1
@@ -40,7 +40,10 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
|
||||
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
|
||||
|
||||
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
|
||||
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. `CHANGELOG.md`는
|
||||
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
|
||||
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
|
||||
경로와 링크는 그 checkout이 이 checkout 옆에 있을 때만 확인하고, 없으면 실패 대신 확인하지
|
||||
못한 것으로 출력과 `artifacts/quality/documentation-review.json`에 남긴다. `CHANGELOG.md`는
|
||||
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
|
||||
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
|
||||
`scripts/verify-documentation-readiness.ts`다.
|
||||
|
||||
@@ -88,9 +88,9 @@ Rollout state starts at `NOT_STARTED`; documented-unimplemented items start at
|
||||
| N-03 | Live V3 path | `corepack pnpm exec vitest run tests/unit/http-execution-v3.test.ts -t "retry-time fence"` | `fix: preserve command effect certainty across retries` | `FIXED_NOT_RELEASED` | command effect verdict regression | Red reproduced `SCOPE_FENCED` with `NOT_STARTED` after one dispatched attempt → green `MAYBE_APPLIED`; lattice table 9/9; `check:types` PASS; `lint` PASS |
|
||||
| N-04 | Live composition teardown | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts tests/unit/runtime-adapters.test.ts` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | telemetry delivery loss after teardown change | Red 10 failed (5 lifecycle + 5 capacity) → green 34/34; `check:diagnostics` PASS; `check:types` PASS; `check:architecture` PASS; `lint` PASS |
|
||||
| N-05 | Rollout blocker (sidecar not composed) | `corepack pnpm exec vitest run tests/unit/conditional-validator-store.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | persisted validator key incompatibility | Red collision case (two valid bindings sharing one delimiter-joined key) → green; key is now a bounded validated tuple encoded with `JSON.stringify` |
|
||||
| N-06 | Legacy V2 rollback seam | `corepack pnpm exec vitest run tests/integration/http-client.test.ts` | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy keyed command rejection spike | Red 4 invalid-key cases → green; rejection happens before credentials and fetch (0 credential calls, 0 fetches) |
|
||||
| N-07 | Legacy V2 rollback seam | `corepack pnpm exec vitest run tests/integration/http-client.test.ts tests/integration/auth-recovery.test.ts` | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy credential timeout regression | Red never-settling owner → green; credential wait races the existing attempt controller so no extra timer is added; ownership maps to REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE with zero fetches |
|
||||
| N-08 | Legacy V2 rollback seam | `corepack pnpm exec vitest run tests/unit/bounded-json-compatibility.test.ts` | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy JSON failure-code drift | Green 7/7 including throwing cancel/releaseLock; `readBoundedJson` now delegates to `bounded-body-reader` with the legacy codes preserved |
|
||||
| N-06 | Legacy V2 rollback seam | The V2 client test tests/integration/http-client.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy keyed command rejection spike | Red 4 invalid-key cases → green; rejection happens before credentials and fetch (0 credential calls, 0 fetches) |
|
||||
| N-07 | Legacy V2 rollback seam | The V2 client tests tests/integration/http-client.test.ts and tests/integration/auth-recovery.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy credential timeout regression | Red never-settling owner → green; credential wait races the existing attempt controller so no extra timer is added; ownership maps to REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE with zero fetches |
|
||||
| N-08 | Legacy V2 rollback seam | The V2 bounded JSON test tests/unit/bounded-json-compatibility.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy JSON failure-code drift | Green 7/7 including throwing cancel/releaseLock; `readBoundedJson` now delegates to `bounded-body-reader` with the legacy codes preserved |
|
||||
| N-09 | Live cross-context host | `corepack pnpm exec vitest run tests/unit/cross-tab-invalidation.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | cross-tab invalidation drop | Red foreign-area pulse accepted → green 13/13; localStorage captured once and `StorageEvent.storageArea` compared by object identity; pulse key registered as `CACHE_INVALIDATION_PULSE`; `check:registries` PASS |
|
||||
| N-10 | Cursor runtime `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/cursor-pagination-runtime.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | pagination abort semantics change | Red never-settling loader → green `PAGINATION_ABORTED` with the late page ignored |
|
||||
| N-11 | Live composition | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts -t capacity` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | capacity rejection on valid composition | Red 5/5 capacity cases → green; ceilings documented in VD-07 §7-4 |
|
||||
|
||||
Reference in New Issue
Block a user