diff --git a/README.md b/README.md index 8b0d536b..17a661f1 100644 --- a/README.md +++ b/README.md @@ -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 `. +[`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, diff --git a/docs/README.md b/docs/README.md index fc22ea81..e9af868a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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). 같은 문서의 나머지 절은 목표 설계다 diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index f3246247..056cd120 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -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. */ diff --git a/tests/unit/deletable-history-documents.test.ts b/tests/unit/deletable-history-documents.test.ts index 77dcdf98..0029792d 100644 --- a/tests/unit/deletable-history-documents.test.ts +++ b/tests/unit/deletable-history-documents.test.ts @@ -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, diff --git a/tests/unit/template-contract-documents.test.ts b/tests/unit/template-contract-documents.test.ts new file mode 100644 index 00000000..e8bd5564 --- /dev/null +++ b/tests/unit/template-contract-documents.test.ts @@ -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/"])); + }); +}); diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts index f0ba8b96..886b2657 100644 --- a/tests/unit/template-feature-removal-documents.test.ts +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -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",