docs(docs): AGENTS.md와 docs/work를 문서 검사에 넣고 템플릿 계약으로 둔다
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
This commit is contained in:
@@ -215,6 +215,9 @@ and executable gates pass.
|
||||
target designs and work history.
|
||||
[`docs/manual/`](docs/manual/README.md) is the step-by-step guide (Korean) for
|
||||
adding a feature, starting from `corepack pnpm create:feature <id>`.
|
||||
[`AGENTS.md`](AGENTS.md) is the rule book and map that people and coding agents
|
||||
start from, and [`docs/work/`](docs/work/README.md) is the work manual: one
|
||||
playbook per kind of task (Korean). Both are part of the template a copy keeps.
|
||||
|
||||
### Files you can delete after copying
|
||||
|
||||
@@ -227,7 +230,7 @@ reads them, except the one file noted below
|
||||
| `docs/superpowers/` | past plans and specs |
|
||||
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/`: `check:adapter-inventory` (FE-GATE-010) reads its `INVENTORY.md`, whose rows link to the adapter reviews beside it, and `docs/operations/adapter-remediation-ledger.md` cites those reviews |
|
||||
| `SPEC.md`, `docs/history/` | requirements of the 2026-09-25 review fix round (`SPEC.md`), and the plans and evidence of finished work, that round's task list included |
|
||||
| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own |
|
||||
| `docs/ledger/estimates.jsonl` | the template's own task estimates and measurements; empty it and add your project's lines (`docs/ledger/README.md`) |
|
||||
| `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's |
|
||||
|
||||
A feature is not in this list: deleting its directory alone leaves tests,
|
||||
|
||||
@@ -30,6 +30,7 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
|
||||
입구 문서가 가리키는 세부 규칙:
|
||||
|
||||
- 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다
|
||||
- 루트 지침과 작업 매뉴얼(꼭 지킬 것·지도·검증 진입점 `scripts/verify.sh`, 맡은 일마다의 playbook과 기준): [`../AGENTS.md`](../AGENTS.md), [`work/`](work/), [`work/reference/`](work/reference/). 한국어다
|
||||
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
|
||||
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
|
||||
- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다
|
||||
|
||||
@@ -57,6 +57,9 @@ export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([
|
||||
"README.md",
|
||||
"CHANGELOG.md",
|
||||
"docs",
|
||||
// The root rule book. docs/README.md section 1 links it, so verify:documentation
|
||||
// in the fixture reads it as a current contract document.
|
||||
"AGENTS.md",
|
||||
] as const);
|
||||
|
||||
/**
|
||||
@@ -86,6 +89,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
|
||||
"tests/unit/manual-paired-backend-settings.test.ts",
|
||||
// Reads the marked code blocks of docs/manual.
|
||||
"tests/unit/manual-code-blocks.test.ts",
|
||||
// Reads the README deletable-files table and the docs/README.md index.
|
||||
"tests/unit/template-contract-documents.test.ts",
|
||||
] as const);
|
||||
|
||||
/** The tests a fixture copied from `copyTargets` cannot run. */
|
||||
|
||||
@@ -9,6 +9,8 @@ import { describe, expect, it } from "vitest";
|
||||
* `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 = [
|
||||
@@ -32,7 +34,6 @@ const DELETABLE = [
|
||||
new RegExp(["docs", "superpowers"].join("/"), "u"),
|
||||
new RegExp(["docs", "history"].join("/"), "u"),
|
||||
new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"),
|
||||
new RegExp(`\\b${"CLAUDE"}\\.md\\b`, "u"),
|
||||
];
|
||||
/**
|
||||
* 1101/14-01. A section number without a document name cannot be followed,
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
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/"]));
|
||||
});
|
||||
});
|
||||
@@ -23,7 +23,7 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.
|
||||
*/
|
||||
const CHECKER = "scripts/verify-documentation-readiness.ts";
|
||||
/** What verify:documentation reads besides the code. */
|
||||
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "artifacts/tests/a11y-manual"]);
|
||||
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "AGENTS.md", "artifacts/tests/a11y-manual"]);
|
||||
|
||||
const LISTED_SAMPLE = Object.freeze({
|
||||
featureId: "listed-sample-feature",
|
||||
|
||||
Reference in New Issue
Block a user