README의 지워도 되는 파일 표가 루트 CLAUDE.md를 "템플릿 repo 자신의
리뷰 지시, 자기 것으로 바꿔라"로 분류했다. 소유자 결정(2026-11-07 Q4)은
루트 지침을 템플릿 계약으로 정했다. 그리고 AGENTS.md와 docs/work/는
verify:documentation 범위 밖이라 그 안의 경로·script·게이트 ID가 틀려도
아무 검사도 알리지 않는다.
- README: 문서 절에 AGENTS.md와 docs/work/ 포인터를 더하고, 지워도 되는
표에서 CLAUDE.md 행을 빼고 docs/ledger/estimates.jsonl("줄을 비운다")을
넣는다.
- docs/README.md 1절: ../AGENTS.md, work/, work/reference/를 링크한다.
- tests/unit/template-contract-documents.test.ts: 지워도 되는 표에
AGENTS.md·CLAUDE.md·.claude·docs/work가 없고, 1절이 셋을 링크하는지
본다. 표는 제목이 아니라 docs/superpowers/ 행으로 찾아 제목을 옮겨도
돈다. 문서를 읽으니 REMOVAL_FIXTURE_DOCUMENT_TESTS에 올렸다.
- deletable-history-documents.test.ts: CLAUDE.md 패턴을 뺀다(이제 지워도
되는 문서가 아니다).
- 제거 드릴의 문서 사본(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과
template-feature-removal-documents.test.ts의 사본에 AGENTS.md를 더한다.
사본 안에서 검사기를 돌리므로, 1절이 링크한 AGENTS.md가 없으면
FE-GATE-020과 그 단위 시험이 실패한다.
버린 대안: AGENTS.md를 링크하지 않고 백틱으로만 적기. 검사가 빠진다.
위험·한계: 문서 체계 세션이 README를 한국어로 옮기면 표 제목이 바뀐다.
새 시험은 행으로 찾지만, verify-documentation-readiness.ts의 지운 이력
목록은 영어 제목을 읽으니 그 세션이 같이 고친다.
검증: 새 시험은 README·docs/README.md를 고치기 전 트리에서 둘 다
실패했고(desktop test:unit), 고친 뒤 통과한다. verify:documentation과
merge 단계는 PR 전 합친 트리에서 돌린다.
Refs: design-docs harness/01-harness-design.md 4.4절·13절 Q4
47 lines
2.2 KiB
TypeScript
47 lines
2.2 KiB
TypeScript
import { readFile } from "node:fs/promises";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
/**
|
|
* Owner decision 2026-11-07 (docs/work/reference/decisions.md): the root
|
|
* AGENTS.md and CLAUDE.md, `.claude/` and `docs/work/` are the template's
|
|
* contract, which a copy keeps. So the README table of files a copy may delete
|
|
* must not list them, and docs/README.md section 1 links the rule book and the
|
|
* work manual, which makes verify:documentation check the paths, scripts and
|
|
* gate IDs they name.
|
|
*/
|
|
const CONTRACT = Object.freeze(["AGENTS.md", "CLAUDE.md", ".claude", "docs/work"]);
|
|
/** A row only the deletable-files table has; found by content so a translated heading still finds it. */
|
|
const DELETABLE_ROW = "| `docs/superpowers/` |";
|
|
|
|
/** The paths in the first cells of the README table that holds DELETABLE_ROW. */
|
|
function deletablePaths(readme: string): string[] {
|
|
const lines = readme.split("\n");
|
|
const row = lines.findIndex((line) => line.startsWith(DELETABLE_ROW));
|
|
if (row === -1) throw new Error(`README.md has no table row starting with ${DELETABLE_ROW}`);
|
|
let start = row;
|
|
while (start > 0 && lines[start - 1]?.startsWith("|")) start -= 1;
|
|
let end = row;
|
|
while (lines[end + 1]?.startsWith("|")) end += 1;
|
|
return lines
|
|
.slice(start + 2, end + 1)
|
|
.flatMap((line) => [...(line.split("|")[1] ?? "").matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry))
|
|
.map((entry) => entry.replace(/\/$/u, ""));
|
|
}
|
|
|
|
describe("template contract documents", () => {
|
|
it("are not in the README table of files a copy may delete", async () => {
|
|
const listed = deletablePaths(await readFile("README.md", "utf8"));
|
|
expect(listed).toContain("docs/superpowers");
|
|
expect(listed.filter((entry) => CONTRACT.some((kept) => entry === kept || entry.startsWith(`${kept}/`))))
|
|
.toEqual([]);
|
|
});
|
|
|
|
it("are linked from the current-contract section of docs/README.md", async () => {
|
|
const index = await readFile("docs/README.md", "utf8");
|
|
const section = /^## 1\.[\s\S]*?(?=^## )/mu.exec(index)?.[0] ?? "";
|
|
const links = [...section.matchAll(/\]\(([^)#\s]+)\)/gu)].map(([, target = ""]) => target);
|
|
expect(links).toEqual(expect.arrayContaining(["../AGENTS.md", "work/", "work/reference/"]));
|
|
});
|
|
});
|