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
89 lines
3.3 KiB
TypeScript
89 lines
3.3 KiB
TypeScript
import { readdir, readFile } from "node:fs/promises";
|
|
import path from "node:path";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
/**
|
|
* README.md, "Files you can delete after copying", tells a new project that
|
|
* the build and the gates read none of the history documents except
|
|
* `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same
|
|
* promise: they do not copy `docs/`. A test that opens a review document broke
|
|
* all three removal checks (fix of 11-04), so the promise is checked here.
|
|
* The root instruction files left the list on 2026-11-07: they are the
|
|
* template's contract, which a copy keeps (template-contract-documents.test.ts).
|
|
*/
|
|
const CODE_ROOTS = ["src", "tests", "scripts", "config", "recipes", "schemas", ".gitea"];
|
|
const ROOT_FILES = [
|
|
"package.json",
|
|
"vite.config.ts",
|
|
"vitest.config.ts",
|
|
"eslint.config.ts",
|
|
"playwright.config.ts",
|
|
".dependency-cruiser.json",
|
|
];
|
|
|
|
// Built from pieces so that this file does not match itself.
|
|
const REVIEWS = ["docs", "reviews", ""].join("/");
|
|
const KEPT = `${REVIEWS}adapters/INVENTORY.md`;
|
|
// The 2026-09-25 round's task folder moved into the history folder on
|
|
// 2026-11-07 (docs/README.md §3), so the history pattern covers it. A pattern
|
|
// for the old root folder would now only catch a product's own route or
|
|
// folder of that name.
|
|
const DELETABLE = [
|
|
new RegExp(`${REVIEWS}(?!adapters/INVENTORY\\.md)`, "u"),
|
|
new RegExp(["docs", "superpowers"].join("/"), "u"),
|
|
new RegExp(["docs", "history"].join("/"), "u"),
|
|
new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"),
|
|
];
|
|
/**
|
|
* 1101/14-01. A section number without a document name cannot be followed,
|
|
* and the scale design it meant used to live only in the history bundle a
|
|
* copy deletes. Cite it as `scale-architecture.md §N`
|
|
* (docs/architecture/scale-architecture.md, a current contract).
|
|
*/
|
|
const UNNAMED_SECTION = new RegExp(`\\b${"spec"} ?§`, "iu");
|
|
|
|
async function codeFiles(directory: string): Promise<string[]> {
|
|
const entries = await readdir(directory, { withFileTypes: true }).catch(
|
|
() => [],
|
|
);
|
|
const files = await Promise.all(
|
|
entries.map(async (entry) => {
|
|
const target = path.join(directory, entry.name);
|
|
if (entry.isDirectory())
|
|
return entry.name === "node_modules" ? [] : codeFiles(target);
|
|
return /\.(?:[cm]?[jt]sx?|json|ya?ml)$/u.test(entry.name) ? [target] : [];
|
|
}),
|
|
);
|
|
return files.flat();
|
|
}
|
|
|
|
async function linesMatching(patterns: readonly RegExp[]): Promise<string[]> {
|
|
const files = [
|
|
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(),
|
|
...ROOT_FILES,
|
|
];
|
|
const matches: string[] = [];
|
|
for (const file of files) {
|
|
const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
|
|
lines.forEach((line, index) => {
|
|
if (patterns.some((pattern) => pattern.test(line)))
|
|
matches.push(`${file}:${index + 1}`);
|
|
});
|
|
}
|
|
return matches;
|
|
}
|
|
|
|
describe("deletable history documents", () => {
|
|
it("are read by no code, test, script or configuration", async () => {
|
|
expect(await linesMatching(DELETABLE), `only ${KEPT} may be read`).toEqual([]);
|
|
});
|
|
|
|
it("are not cited as an unnamed design section", async () => {
|
|
expect(
|
|
await linesMatching([UNNAMED_SECTION]),
|
|
"name the document: scale-architecture.md §N",
|
|
).toEqual([]);
|
|
});
|
|
});
|