fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다

문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.

고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
  적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
  적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
  복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
  verify:documentation, check:i18n, check:design-system을 돈다
  (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
  (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
  수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.

위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
  않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).

검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
  sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
  PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
  documentation-readiness 14건 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
This commit is contained in:
DongHyeonka
2026-11-04 21:02:14 +09:00
parent f08c93ab2e
commit c4d587052e
11 changed files with 42 additions and 24 deletions
+17 -1
View File
@@ -18,6 +18,8 @@ import {
pruneRemovalFixtureCiContract,
pruneScriptOrchestration,
regenerateRemovalFixtureWorkflow,
REMOVAL_FIXTURE_COPY_TARGETS,
REMOVAL_FIXTURE_DOCUMENT_TARGETS,
renderRemovalJunit,
requireRemovalFixtureEnvironment,
runRemovalFixtureCheck,
@@ -201,7 +203,14 @@ function outcome(name: string, findings: readonly string[], label: string): Remo
}
try {
await prepareRemovalFixture(fixtureRoot);
// 1103/14-04. The documents come too: removing a feature must leave them
// valid, and the fixture used to leave them out with the tests that read
// them, so a manual naming the sample's files passed here and then failed
// FE-GATE-017 in the product that removed it.
await prepareRemovalFixture(fixtureRoot, [
...REMOVAL_FIXTURE_COPY_TARGETS,
...REMOVAL_FIXTURE_DOCUMENT_TARGETS,
]);
for (const excludedFixtureTest of [
"tests/unit/ci-workflow-generation.test.ts",
"tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap",
@@ -395,6 +404,13 @@ try {
}
const gateChecks = (prefix: string): RemovalCheck[] => [
check(`${prefix}typecheck`, "check:types"),
// 1103/14-04 (FOLLOW-UP 09-07). Merge and documentation gates the drill
// did not run: the documents, lint, screen text and design tokens can
// name or use what the removal deleted.
check(`${prefix}lint`, "lint"),
check(`${prefix}documentation`, "verify:documentation"),
check(`${prefix}i18n`, "check:i18n"),
check(`${prefix}design-system`, "check:design-system"),
check(`${prefix}architecture`, "check:architecture"),
check(`${prefix}registries`, "check:registries"),
check(`${prefix}unit-integration`, "test:all"),