crumbs-spec 0.1.0 → 0.3.0

package/README.md

@@ -2,68 +2,77 @@
 
 [한국어](README.ko.md) · **English**
 
-crumbs-spec leaves breadcrumbs (links) on every document so an agent never gets lost, and keeps a **living spec** that leads from the index to the detail document in one path. It describes how the repository behaves *right now* in responsibility-sized documents, checks with one command that those documents are properly linked, and fixes the procedures an agent follows to write, find, ask about and ingest them as skills.
+[![CI](https://github.com/Sienna94/crumbs-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/Sienna94/crumbs-spec/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/crumbs-spec)](https://www.npmjs.com/package/crumbs-spec)
+
+crumbs-spec leaves breadcrumbs (links) on every document so an agent never gets lost, and keeps a **living spec** that leads from the index to the detail document in one path. It describes how the repository behaves *right now* in responsibility-sized documents, checks with one command that those documents are properly linked, and ships the procedures an agent follows to write, find, ask about and ingest them as skills.
 
 ## Why we built it
 
-Running dozens of spec documents together with agents on a real app repository, the same three things kept happening.
+While we ran dozens of spec documents with agents on a real app repository, the same three things kept happening.
 
 1. Specs only survived as change units (per-feature `spec.md`, tickets), so months later there was no document that answered "what is the rule right now?".
 2. Piling them up like a wiki put the same rule into several documents with slightly different wording, and nobody knew which one was right. A later benchmark had an agent find three such contradictions.
 3. When agents read documents they leaned on folder structure and search, so they wandered into other areas or fell back to grep. One question cost eight documents.
 
-"Write better documents" did not fix it. We needed **a tool that enforces structure by machine**. Give every policy exactly one owner, check the link graph, and make the unknown a question instead of a guess, and both agents and people reach the document by the same path. So we started scattering breadcrumbs.
+"Write better documents" did not fix it. We needed **a tool that enforces structure by machine**. When every policy has exactly one owner, the link graph is checked by a machine, and the unknown is written as a question instead of a guess, agents and people reach the document by the same path. So we started scattering breadcrumbs.
 
 ## How it differs from other tools
 
-Spec Kit is good at pre-implementation planning and LLM Wiki at accumulating sources. crumbs-spec takes the gap between them: **the current state that must survive after implementation**. It complements them rather than replacing them.
+Spec Kit is good at pre-implementation planning and LLM Wiki at accumulating sources. crumbs-spec fills the gap between them: **the current state that must survive after implementation**. It complements them rather than replacing them.
 
 | | GitHub Spec Kit | OpenSpec | Karpathy's LLM Wiki | **crumbs-spec** |
 |---|---|---|---|---|
 | Document unit | One change (feature): `spec.md`, `plan.md`, `tasks.md` | Current-state spec + change deltas | Entity, concept and source-summary pages | **One responsibility (user flow)**. Each policy is owned by exactly one document |
-| Point in time | Before implementation | Before and after | When a source is ingested | **Current behaviour after implementation** |
-| Existing code | States that it "does not infer" | Has onboarding, but no code-to-spec drafting | Targets sources, not code | **Drafts from code and tests; the unknown becomes a `[확인 필요]` question** |
+| Point in time | Before implementation | Before and after | When a source is ingested | **Current behavior after implementation** |
+| Existing code | States that it "does not infer" | Has onboarding, but no code-to-spec drafting | Targets sources, not code | **The crumbs-writer skill drafts from code and tests; the unknown becomes a `[needs confirmation]` question** |
 | Navigation | Folders and file names | Folders and file names | Index first | **Index → overview → detail by links only**. No IDs, no front matter |
-| Machine checks | Consistency across spec, plan and tasks | Delta merge | Orphan page and broken link lint (with LLM judgement) | **15 deterministic rules**: links, anchors, reachability, backlinks, duplicate policies, evidence paths, section order, flow diagrams, log format |
-| Sync after implementation | The team picks a maintenance model | `archive`/`sync` for the change in hand | Feeds query results back into the wiki | **Agent rule ("update the owning document in the same change, even unasked") + decision log + planned `drift`** |
+| Machine checks | Consistency across spec, plan and tasks | `openspec validate` (structure) and delta merge on archive | Orphan page and broken link lint (with LLM judgment) | **16 structural rules**: links, anchors, reachability, backlinks, duplicate policy names, evidence paths, section order, flow diagrams, log format, unterminated comments |
+| Sync after implementation | The team picks a maintenance model | `archive`/`sync` for the change in hand | Feeds query results back into the wiki | **Agent rule ("update the owning document in the same change, even unasked") and a decision log** |
 | Human readability | Prose | Prose | Prose | **Flow diagrams (Mermaid) and branch tables in the template** |
-| Measurement | None | None | None | **Compares navigation cost of two document systems with the same questions** |
 
-From LLM Wiki we kept the raw/wiki/schema split, index-first navigation, the append-only log and human-supervised ingest. Three things are deliberately different: documents are organised by responsibility rather than entity (only concepts that several flows branch on get a page under `concepts/`), documents are maintained by agents but owned by people, and lint is deterministic with no LLM judgement. See section 1 of [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) (Korean) for the full comparison.
+Kiro specs and BMAD sit close to Spec Kit (per-feature, before implementation) and are not listed separately; the Korean plan document compares all five.
+
+From LLM Wiki we kept the raw/wiki/schema split, index-first navigation, the append-only log and human-supervised ingest. Three things are deliberately different: documents are organized by responsibility rather than entity (only concepts that several flows branch on get a page under `concepts/`), documents are maintained by agents but owned by people, and lint is deterministic with no LLM judgment. See section 1 of [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) (Korean) for the full comparison.
 
 ## What we cared about
 
 - **A single source of truth for the current state.** No change directories. Documents explain "how it behaves now", not "what changed".
-- **No guessing.** A rule not confirmed by code, tests or approved sources is written only as "right now it behaves like this" plus a `[확인 필요]` (needs confirmation) question. `check` counts the questions for you.
+- **No guessing.** A rule not confirmed by code, tests or approved sources is written only as "right now it behaves like this" plus a `[needs confirmation]` (`[확인 필요]` with `lang: ko`) question. `check` reports one `open-question` warning per document that still has questions. Whether a statement is a guess is the skill's rule and the reviewer's job; `check` cannot tell.
+- **One owner per policy, checked at the name level.** `check` rejects the same policy name in two documents (or twice in one). Two policies that say the same thing under different names are not detected; the writer skill's naming rules exist for that.
 - **People-first prose.** No IDs, no status tables, no enforced grammar. Navigation lives in links and headings only.
-- **Deterministic checks, human judgement.** `check` looks at structure only. Style, content and staleness are for skill guidance and people.
+- **Deterministic checks, human judgment.** `check` looks at structure only. Style, content and staleness are for skill guidance and people.
 - **Decisions in one place.** When a question gets its answer, a `decision` entry goes into the log and the document points at it with a single dated link.
 - **Two languages.** `lang` in `crumbs.json` selects the language of the templates, skills, messages and AGENTS block for the whole repository. It defaults to English (`en`); `ko` gives Korean. This README is the English guide.
 
-## What happened when we used it
+## Does it work on code it has never seen? (RealWorld experiment)
 
-We rewrote three areas of a real app repository (about 40,000 lines of code) with the crumbs-writer skill without showing it any existing spec document. Then we asked the same 18 questions of the existing spec system and the crumbs system and let an agent answer from documents only.
+We ran the writer skill on two open-source backends of the [RealWorld](https://github.com/realworld-apps/realworld) "Conduit" API and graded the documents against the project's official API test suite. The generated documents, prompts, ground truth and every grading row are published in [crumbs-spec-conduit](https://github.com/Sienna94/crumbs-spec-conduit).
 
-**Cost of writing from zero** (one agent per domain, three in parallel)
+- **Setup.** Two pinned implementations of the same API: [Nitro + Prisma](https://github.com/realworld-apps/nitro-prisma-zod-realworld-example-app) (TypeScript) and [Django Ninja](https://github.com/c4ffein/realworld-django-ninja) (Python). One Opus 5.5 agent per implementation wrote the documents from code and tests only. The official spec repository was not in the experiment repository while they wrote; it was added in a later commit.
+- **Ground truth.** Each request in the official Hurl suite, at the version both implementations pin, is one row: 130 rows after dropping setup and cleanup requests.
+- **Grading.** A different model (Sonnet 5.5) graded every row. `correct` means the documents state the status and every essential asserted value, `partial` that one is left out, `wrong` that the documents contradict it, `missing` that no document covers it. It also checked every policy against the code.
 
-| Domain | Code | Documents | Policies | Confirmed by tests / questions | Agent tokens | Writing time |
-|---|---|---|---|---|---|---|
-| Payment | ~20k lines | 19 | 100 | 5 / 95 | 570k | 1 h 7 min |
-| Viewer | ~23k lines | 40 | 194 | 29 / 165 | 850k | 1 h 7 min |
-| Auth | ~10k lines | 35 | 195 | 64 / 131 | 790k | 1 h 13 min |
+| | Nitro + Prisma | Django Ninja |
+|---|---|---|
+| Code / tests in the repository | ~1,400 lines / 2 unit test files | ~2,300 lines / endpoint tests for each app |
+| Documents / policies | 28 / 51 | 26 / 91 |
+| Policies confirmed by tests / left as questions | 6 / 45 | 50 / 41 |
+| Suite rows correct | **125 / 130** | **116 / 130** |
+| Suite rows partial / wrong / missing | 5 / 0 / 0 | 14 / 0 / 0 |
+| Invented policies (code does not do it) | 0 | 0 |
+| Policies partly overstated | 1 | 6 |
+| Writer tokens / wall time | 165k / 2 h 40 min | 202k / 2 h 47 min |
 
-Writing time is the actual working time from the agent transcripts' timestamps, excluding idle gaps longer than ten minutes. With the three domains in parallel everything finished in about 1 h 15 min. Not one policy was invented, and all six places where the existing spec disagreed with the code were written as the code behaves. The documents were later regrouped by user flow into 38.
+- **Nothing contradicted the suite and nothing was invented.** Every miss is a detail left out. Nitro's five partials are `null` inputs the documents never mention and the order of tags. Twelve of Django's fourteen come from one honest question: the app's error handler and its tests disagree on the 401 body, so the writer stated both and asked.
+- **Statements under a question were mostly right.** 12 Nitro rows and 32 Django rows were graded correct on a statement still marked `[needs confirmation]`. "This is what it does now" plus a question kept the documents useful without claiming more than the tests prove.
+- **Fewer tests, more questions.** Nitro has two unit test files, so 45 of its 51 policies stayed questions. The suite answers 29 of them, which is the list a maintainer would confirm first.
+- **The writers raised what no suite row tests.** As questions: Django's article list ignores the token and reads the session user, and its `createUser` command looks users up by a field a migration renamed. The Nitro documents also say plainly that the email format is not checked, which a newer version of the suite does test.
 
-**Navigation cost on the same 18 questions** (documents only; reading code was forbidden)
+Limits: one run per implementation and one writer model. The grader is also a model; the author checked that every cited anchor exists and spot-checked rows. RealWorld is well known, so the writer may have seen it in training even without the spec in the repository. The suite asserts only part of what the documents say: 20 of Nitro's and 41 of Django's policies were checked against the code alone. The Django grader ran the code with unpinned dependencies, so some of its "partly" verdicts may depend on library versions.
 
-| | Existing spec system | crumbs-spec |
-|---|---|---|
-| Correct answers | 17 / 18 (1 partial) | 15 / 18 (3 partial) |
-| Files read in total | 70 (avg 3.9, max 8) | 64 (avg 3.6, max 6) |
-| Fell back to grep | 3 | 1 |
-| Tokens in total | 2.32M | 1.89M (−18%) |
+### An earlier run on a private app (anecdote)
 
-The existing system's partial answer came from failing to find the owning document; the three crumbs partials all reached the owning document in 3–5 files but the writer had dropped details such as screen numbers and channel branches. That cause is now fixed by a skill rule ("do not drop values that carry a condition"). Note the bias: the questions were drawn from the existing specs, which favours the existing system.
+Before this we rewrote three areas of a private app (about 40,000 lines) and asked the existing spec system and crumbs the same 18 questions, documents only. crumbs answered 15 against 17, read 64 files against 70 and used 18% fewer tokens. Its three partial answers were details the writer had dropped, which led to the skill rule "do not drop values that carry a condition". The author graded it, the questions came from the existing specs, and the data cannot be published, so read it as an anecdote. The navigation comparison has not been repeated on public code yet.
 
 ## Install and quick start
 
@@ -77,7 +86,7 @@ npx crumbs-spec check               # check the link graph and structure
 
 Korean repositories: pass `--lang ko`.
 
-`init` creates these seven files and never overwrites an existing one.
+`init` creates these files and never overwrites one that exists. With `--skills all` it also writes eight SKILL.md files, and in AGENTS.md it only ever replaces its own block between `<!-- crumbs:start -->` and `<!-- crumbs:end -->`.
 
 ```
 crumbs.json                      configuration
@@ -89,7 +98,9 @@ docs/raw/README.md               raw sources directory (read-only)
 AGENTS.md                        crumbs block (agent rules)
 ```
 
-Until the package is on npm, run it from the repository with `npm run build` and then `node dist/src/cli.js <command>`.
+If `crumbs.json` already exists, `init` keeps its settings and ignores `--spec-dir` and `--lang` (it says so). The last line of `init` is the next command to run: `npx crumbs-spec check`.
+
+The package is on npm as [`crumbs-spec`](https://www.npmjs.com/package/crumbs-spec). To run it from a clone instead, use `npm run build` and then `node dist/src/cli.js <command>`.
 
 ## Adding it to an existing project
 
@@ -101,22 +112,22 @@ The order for a repository that already has code and documents. Start with one d
    npx crumbs-spec init --spec-dir docs/crumbs --skills claude
    ```
 
-2. **Let the agent read the rules.** Claude Code only reads the crumbs block if `CLAUDE.md` contains the line `@AGENTS.md`. Skills are found automatically under `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex).
+2. **Let the agent read the rules.** Codex and Claude Code (v2.1.277 or later) read `AGENTS.md` on their own. In a repository that also has a `CLAUDE.md` (or `.claude/CLAUDE.md` or `CLAUDE.local.md`), Claude Code reads only that file, so add the line `@AGENTS.md` to it to pull in the crumbs block. `init` prints a guide line in that case. Skills are found automatically under `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex).
 
 3. **Do not migrate existing documents.** The writer treats code and tests as the only sources and does not read existing wikis, design notes or READMEs unless you name them as sources, because there is no way to know whether they still match the code. Copy the ones worth using as evidence (plans, contracts, decision records) into `docs/raw/` and ingest them one at a time with `crumbs-ingest`.
 
-4. **Write the first domain from code.** Pick the area people ask about most and hand it to the writer's "document existing code" mode. The `[확인 필요]` questions in the result become the list of things a person has to decide for that area.
+4. **Write the first domain from code.** Pick the area people ask about most and hand it to the writer's "document existing code" mode. The `[needs confirmation]` questions in the result become the list of things a person has to decide for that area.
 
    ```
    Document the code under src/billing/ with crumbs-writer in "document existing code" mode.
    The domain directory is docs/crumbs/billing/. Leave unconfirmed policies as questions and finish the whole thing.
    ```
 
-5. **Put `check` in CI.** Fail only on errors (broken links and anchors, unreachable documents, missing backlinks, missing code paths, duplicate policy names) and leave warnings alone. Directories under the spec root that are not crumbs documents yet go into `exclude` in `crumbs.json`.
+5. **Put `check` in CI.** Fail only on errors (every rule marked error in the check rules table below) and ignore warnings. Markdown under the spec root that is not a crumbs document yet goes into `exclude` in `crumbs.json`: entries are paths relative to the spec root, an entry ending in `/` excludes that directory, there are no glob patterns, and `check` tells you when a document has none of the required sections.
 
 6. **Change the document in the same change as the code.** The AGENTS block tells the agent to "update the owning document in the same change, even when nobody asked", so every PR brings `check` and a log entry with it. The index fills in as domains are added one by one.
 
-If you already have a spec system, try asking both systems the same questions. Files read and correct answers show at once which one is easier to navigate (the step-5 benchmark runner will automate this).
+If you already have a spec system, try asking both systems the same questions. Files read and correct answers show at once which one is easier to navigate.
 
 ## How a spec gets written
 
@@ -126,10 +137,10 @@ The order the writer skill follows in "document existing code" mode. In "reflect
 flowchart TD
     A["Read the index and templates"] --> B["Follow code and tests from the entry point"]
     B --> C["Draw the responsibility boundary: one user flow = one document"]
-    C --> D["Write 현재 동작 (current behaviour), steps as ### subheadings"]
+    C --> D["Write the Current behavior section, steps as ### subheadings"]
     D --> E{"Is the rule confirmed by a test"}
     E -->|yes| F["Write it as a policy"]
-    E -->|no| G["Statement of current behaviour + 확인 필요 question"]
+    E -->|no| G["Statement of current behavior + [needs confirmation] question"]
     F --> H["Flow diagram and branch tables"]
     G --> H
     H --> I["Evidence paths and mutual related-document links"]
@@ -154,62 +165,57 @@ docs/specs/concepts/             concepts shared by several domains (optional)
 docs/raw/                        immutable sources such as contracts and plans
 ```
 
-The sections of a detail document are fixed. Headings follow `lang` (English by default, Korean with `lang: ko`) and can be renamed through `headings` in `crumbs.json`.
+The sections of a detail document are fixed. Headings follow `lang` (English by default, Korean with `lang: ko`) and can be renamed through `headings` in `crumbs.json`. With `lang: ko` the headings are 목적, 현재 동작, 흐름, 정책, 근거, 확인 필요 사항, 관련 문서.
 
 | Section | Content |
 |---|---|
-| 목적 (purpose) | The one responsibility this document owns and what it does not cover |
-| 현재 동작 (current behaviour) | As the user experiences it, in the present tense; three or more steps become `###` subheadings |
-| 흐름 (flow) | A Mermaid diagram for two or more steps; a table when there are two or more comparison axes |
-| 정책 (policies) | `### policy name` (unique across the repository) and the rule; if unconfirmed, a statement of current behaviour followed by a `[확인 필요]` question |
-| 근거 (evidence) | Backticked code paths with a description; `check` verifies the path exists |
-| 확인 필요 사항 (open questions) | `- [확인 필요] [policy name](#anchor) — question` |
-| 관련 문서 (related) | Link to the overview and neighbouring documents; backlinks must be mutual |
+| Purpose | The one responsibility this document owns and what it does not cover |
+| Current behavior | As the user experiences it, in the present tense; three or more steps become `###` subheadings |
+| Flow | A Mermaid diagram for two or more steps; a table when there are two or more comparison axes |
+| Policies | `### policy name` (unique across the repository) and the rule; if unconfirmed, a statement of current behavior followed by a `[needs confirmation]` question |
+| Evidence | Backticked paths that contain a `/`, each with a description; `check` verifies the path exists |
+| Open questions | `- [needs confirmation] [policy name](#anchor) — question` |
+| Related | Link to the overview and neighboring documents; backlinks must be mutual |
 
-Example (`docs/specs/shopping/장바구니.md`, "cart"):
+Example: a detail document the writer produced from the Nitro code in [the RealWorld experiment](#does-it-work-on-code-it-has-never-seen-realworld-experiment), unedited ([source](https://github.com/Sienna94/crumbs-spec-conduit/blob/main/nitro/docs/specs/api/articles/tag-list.md)). Usage example 3 below answers its question and adds a flow diagram.
 
 ````markdown
-# 장바구니
-<!-- ../index.md를 먼저 읽는다. 이 문서를 바꾼 뒤 ../log.md에 항목을 추가한다 -->
-
-## 목적
-사용자가 상품을 담고 수량을 바꾸고 비울 때까지의 흐름을 맡는다. 쿠폰 적용은 [쿠폰 할인](쿠폰-할인.md)이 맡는다.
-
-## 현재 동작
-- 사용자가 같은 상품을 다시 담으면 앱은 수량을 더한다.
-- 수량이 99를 넘으면 앱은 "최대 99개까지 담을 수 있습니다." 안내를 보이고 담지 않는다.
-
-## 흐름
-```mermaid
-flowchart TD
-    A["상품 담기"] --> B{"같은 상품이 있나"}
-    B -->|예| C["수량 합산"]
-    B -->|아니오| D["새 줄 추가"]
-    C --> E{"99 초과"}
-    E -->|예| F["안내 후 담지 않음"]
-```
-
-## 정책
-### 수량 상한
-장바구니 한 줄의 수량은 99 이하다.
-
-### 최소 주문 금액
-지금은 합계가 10,000원 미만이면 결제 버튼을 비활성화한다.
-[확인 필요] 10,000원이라는 기준의 근거는 무엇인가?
-
-## 근거
-- `src/cart/cart.ts:12-48` — 담기와 수량 합산
-- `test/cart/cart.test.ts` — 수량 상한
-
-## 확인 필요 사항
-- [확인 필요] [최소 주문 금액](#최소-주문-금액) — 10,000원이라는 기준의 근거는 무엇인가?
-
-## 관련 문서
-- [쇼핑 개요](overview.md)
-- [쿠폰 할인](쿠폰-할인.md)
+# Tag list
+<!-- Read ../../index.md first. After changing this document, add an entry to ../../log.md -->
+
+## Purpose
+This document owns GET /api/tags, which returns the most used tag names. How tags are attached to articles is owned by [Article creation](article-create.md#article-tag-name-handling). The endpoint allows anonymous viewers as described in [Authentication token](../authentication-token.md), and the list is the same for anonymous and signed-in viewers.
+
+## Current behavior
+- The server considers only tags that at least one article uses.
+- The server sorts those tags by the number of articles that use them, most used first.
+- The server returns at most 10 tag names.
+- The server responds with status 200 and {"tags": ["<name>"…]}.
+- If no article uses a tag, the list is empty.
+
+## Flow
+None
+
+## Policies
+### Popular tag list
+The tag list holds at most 10 names of tags used by at least one article, sorted by the number of articles that use each tag, most used first. The order of tags used by the same number of articles is not defined, and the list has no pagination. No test covers this rule.
+[needs confirmation] What is the basis of the 10-tag limit, and what should order tags with the same usage count?
+
+## Evidence
+- `server/routes/api/tags/index.get.ts` — selects tags used by at least one article, sorts them by usage and returns at most 10 names
+- `prisma/schema.prisma` — unique tag names and the relation between tags and articles
+
+## Open questions
+- [needs confirmation] [Popular tag list](#popular-tag-list) — What is the basis of the 10-tag limit, and what should order tags with the same usage count?
+
+## Related
+- [Articles API overview](overview.md)
+- [Article creation](article-create.md)
+- [Article update](article-update.md)
+- [Article deletion](article-delete.md)
 ````
 
-The overview's `## 용어` (terms) section is a list of aliases linked to the owning policy (`- 정액권(정액제) — [정액권 이용 중 판정](정액권.md#정액권-이용-중-판정)`). A term that is only a definition stops there; only concepts that several flows branch on (channel, currency, member state) get an owning document under `concepts/`.
+The overview's "Terms" section is a list of aliases linked to the owning policy (`- Subscription pass(flat-rate pass) — [Pass active check](pass.md#pass-active-check)`). A term that is only a definition stops there; only concepts that several flows branch on (channel, currency, member state) get an owning document under `concepts/`.
 
 ## Commands
 
@@ -224,57 +230,72 @@ Common options are `--root <dir>` (repository root, default: current directory),
 `check` prints one line per finding as `file:line severity rule: message`, and a summary last.
 
 ```
-docs/specs/shopping/장바구니.md:34 error broken-anchor: 앵커가 없음: 쿠폰-할인.md#적용-순서
-docs/specs/shopping/장바구니.md:20 warning open-question: 미해결 질문 표시 2개
-
-crumbs check: 문서 4개, 오류 1개, 경고 1개
+docs/specs/api/articles/tag-list.md:31 error broken-link: link target not found: ../log.md#2026-11-03-decision--popular-tag-list-most-used-first-stays-ties-are-undefined-10-tags-are-cut-after-sorting-and-every-viewer-gets-the-same-unpaginated-list
+docs/specs/api/articles/article-delete.md:44 warning open-question: 1 open question(s)
+…
+crumbs check: 28 documents, 1 error, 20 warnings
 ```
 
+This is the check from usage example 3 before the writer fixed its decision link; the other 19 warnings are left out.
+
+**Supported Markdown.** Headings must be ATX (`#` to `######`); setext headings are not recognized. Inline links and reference links (`[text][label]`, and `[label][]` with a `[label]: path` definition) are checked; a shortcut reference such as `[label]` alone is not a link. Heading anchors follow github-slugger: each space becomes `-`, punctuation other than `-` and `_` is dropped, and nothing is collapsed, so `### Quantity & limits` becomes `#quantity--limits`. Symlinked files and directories under the spec root are followed. Evidence paths are resolved against `codeRoot` (the repository root by default), except paths under `rawDir`, which are always resolved against the repository root. An evidence path must contain a `/`, so a repository-root file is written `./package.json`; line suffixes such as `:12`, `:12-48`, `:12:5` and `:12-48,60-70` are accepted. Entries in `exclude` are paths relative to the spec root, and an entry ending in `/` excludes that directory. Every finding carries a `line` (1 when there is no better position), so JSON output always includes it.
+
 ### Check rules
 
 | Rule | Severity | What it catches |
 |---|---|---|
 | `index-missing` | error | The index document is missing (no other rule runs) |
 | `missing-title` | error | The first heading is not an H1 |
-| `broken-link` / `broken-anchor` | error | The link target file or heading does not exist |
+| `broken-link` | error | The link target file does not exist, or its spelling differs from the file on disk |
+| `broken-anchor` | error | The link points to a heading that does not exist |
 | `unreachable` | error | A document that cannot be reached from the index by links |
 | `missing-section` | error | A required section for the role is missing |
 | `missing-backlink` | error | No link back to the parent (overview or index), or a detail A→B link without B→A |
 | `missing-code-path` | error | An evidence code path does not exist |
-| `duplicate-policy` | error | The same policy name appears in two documents |
-| `log-format` | error | A log entry is not in the form `## [YYYY-MM-DD] kind \| title` |
-| `open-question` | warning | Number of `[확인 필요]` markers in a document |
+| `duplicate-policy` | error | The same policy name appears in two documents, or twice in one |
+| `log-format` | error | A log entry is not in the form `## [YYYY-MM-DD] kind \| title`, or the date is more than a day in the future |
+| `unterminated-comment` | error | An HTML comment is opened and never closed, hiding the rest of the document |
+| `open-question` | warning | One warning per document that still has open questions (the count is the number of questions) |
 | `log-order` | warning | Log dates are out of order |
-| `missing-flow` | warning | Current behaviour has six or more steps but no diagram or table |
+| `missing-flow` | warning | Current behavior has six or more steps but no diagram or table |
 | `section-order` | warning | Sections are not in template order |
 | `log-body` | warning | A `decision` entry has no document link |
 
 ## Log
 
-The log is appended in one place (`docs/specs/log.md`) in chronological order. The title is **one sentence about the user outcome**, not the task name, and the body has three lines.
+The log is appended in one place (`docs/specs/log.md`) in chronological order. The title is **one sentence about the user outcome**, not the task name, and the body has three lines. `log add` writes the entry and refuses titles or bodies that contain `<!--`.
 
 ```bash
-npx crumbs-spec log add --kind change "장바구니 수량 상한을 99로 올림" \
-  --body "결과: 한 줄에 99개까지 담을 수 있다. 이유: 요청 SHOP-42. 문서: [수량 상한](shopping/장바구니.md#수량-상한)"
+npx crumbs-spec log add --kind change "<one sentence about the user outcome>" \
+  --body "Result: <what changed>. Reason: <why>. Document: [<policy>](<domain>/<document>.md#<anchor>)"
+```
+
+The entry written in usage example 5:
+
+```markdown
+## [2026-11-03] change | A malformed email on registration, login and account update is rejected with 422 and is invalid
+Result: a malformed email on registration, login and account update gets status 422 with {"errors": {"email": ["is invalid"]}}; 3 api documents updated and 1 open question remains about accepted address forms. Reason: code change in server/schemas/user.schema.ts, reported by the user. Document: [Email format](api/users/registration.md#email-format)
 ```
 
-When a `[확인 필요]` question gets its answer, add a `decision` entry and put one decision link at the end of the confirmed policy. Instead of change-history tables inside documents, decisions accumulate in the log and documents only point at them.
+When a `[needs confirmation]` question gets its answer, add a `decision` entry and put one decision link at the end of the confirmed policy. Instead of change-history tables inside documents, decisions accumulate in the log and documents only point at them. The slug drops the brackets, `|`, commas and colons, so the `|` leaves a double dash in the anchor. From usage example 3:
 
 ```markdown
-## [2026-11-02] decision | 최소 주문 금액: 10,000원은 배송비 정책에서 온 값이다
-결과: 합계 10,000원 미만이면 결제 버튼이 비활성이다. 이유: 2026-11-02 기획 확인. 문서: [최소 주문 금액](shopping/장바구니.md#최소-주문-금액)
+## [2026-11-03] decision | Popular tag list: most used first stays, ties are undefined, 10 tags are cut after sorting, and every viewer gets the same unpaginated list
+Result: GET /api/tags keeps the most-used-first order, leaves the order of equally used tags undefined, applies the 10-tag limit after sorting, and returns the same list without pagination to every viewer. Reason: answers from the maintainer; existing clients may rely on most-used-first and the limit keeps the tag sidebar short. Document: [Popular tag list](api/articles/tag-list.md#popular-tag-list)
 ```
 
 ```markdown
-### 최소 주문 금액
-합계가 10,000원 미만이면 결제 버튼을 비활성화한다. (결정: [2026-11-02](../log.md#2026-11-02-decision-최소-주문-금액-10000원은-배송비-정책에서-온-값이다))
+### Popular tag list
+The tag list holds at most 10 names of tags used by at least one article, sorted by the number of articles that use each tag, most used first, and the server applies the 10-tag limit after sorting. … (decision: [2026-11-03](../../log.md#2026-11-03-decision--popular-tag-list-most-used-first-stays-ties-are-undefined-10-tags-are-cut-after-sorting-and-every-viewer-gets-the-same-unpaginated-list))
 ```
 
 The kinds are `ingest` (a source was applied), `query` (an answer fed back), `lint`, `drift`, `change` (a document changed) and `decision` (a question was settled).
 
 ## Skills
 
-`init --skills` installs the procedures an agent follows into `.claude/skills/<name>/SKILL.md` (Claude Code) and `.agents/skills/<name>/SKILL.md` (Codex). An existing `SKILL.md` is never overwritten; delete it and run `init --skills` again to upgrade. Claude Code reads the crumbs block only when `CLAUDE.md` contains `@AGENTS.md`.
+`init --skills` installs the procedures an agent follows into `.claude/skills/<name>/SKILL.md` (Claude Code) and `.agents/skills/<name>/SKILL.md` (Codex). An existing `SKILL.md` is never overwritten; delete it and run `init --skills` again to upgrade. When Claude Code reads the crumbs block is described in step 2 of [Adding it to an existing project](#adding-it-to-an-existing-project).
+
+Each generated SKILL.md starts with a comment naming the crumbs-spec version that produced it. Skills and templates follow the package version: a minor release may change their text, a patch release does not. To upgrade, delete the file and run `init --skills` again.
 
 | Skill | What it does |
 |---|---|
@@ -285,57 +306,70 @@ The kinds are `ingest` (a source was applied), `query` (an answer fed back), `li
 
 ## Usage examples
 
+Every example below was actually run on the Nitro backend from the experiment, in the [`usage/`](https://github.com/Sienna94/crumbs-spec-conduit/tree/main/usage) workspace of crumbs-spec-conduit. Example 1 is the experiment's Opus 5.5 writer. Examples 2–5 are a Claude Sonnet 5.5 agent that got only the request, read `AGENTS.md` and picked the skill itself; the author answered its questions as the maintainer would. Each example that changed files is one commit, linked below.
+
 ### 1. Document existing code for the first time
 
 ```
-Document the code under src/cart/ with crumbs-writer in "document existing code" mode.
-The domain directory is docs/specs/shopping/. Leave unconfirmed policies as questions and finish the whole thing.
+Document the code under ../vendor/nitro with crumbs-writer in "document existing code" mode,
+from code and tests only. Leave unconfirmed policies as questions and finish the whole thing.
 ```
 
-The agent reads the index and templates, follows code and tests from the entry point, and produces `shopping/overview.md` plus the detail documents. Rules confirmed by tests become policies; rules that exist only in code become "right now …" statements with `[확인 필요]` questions. It ends by running `check`, clearing errors and adding a log entry.
+This is a shortened form of the experiment's [writer prompt](https://github.com/Sienna94/crumbs-spec-conduit/blob/main/eval/prompts/writer.md). The writer followed the code from the route handlers, split the API into four subdirectories and produced 21 detail documents with their overviews. The repository has only two unit test files, so 6 policies came out confirmed by tests and 45 as `[needs confirmation]` questions. It ended with `check` and a log entry ([commit](https://github.com/Sienna94/crumbs-spec-conduit/commit/572b0db)).
 
 ```
-crumbs check: 문서 5개, 오류 0개, 경고 3개
+crumbs check: 28 documents, 0 errors, 21 warnings
 ```
 
-The warnings are the questions left behind. Skimming the open-questions section is enough to see what has to be decided.
+The 21 warnings are the 21 detail documents that still have open questions. Their "Open questions" sections are the list of things the maintainer has to decide.
 
-### 2. Reflect a code change
+### 2. Find an answer
 
 ```
-I raised the cart quantity limit from 99 to 199. Update the docs.
+How many tags does GET /api/tags return, and in what order?
 ```
 
-The writer finds the owning document with `grep -rl 'src/cart/cart.ts' docs/specs` (the evidence section names the path), fixes the current-behaviour section and the `### 수량 상한` policy, updates the value in the flow diagram, and logs `change | 장바구니 수량 상한을 199로 올림`. If two documents look like owners it stops and asks which one is.
+The finder went index → API overview → articles overview → [tag-list.md](https://github.com/Sienna94/crumbs-spec-conduit/blob/main/nitro/docs/specs/api/articles/tag-list.md), four spec documents and no code. It answered: at most 10 names, most used first, only tags that at least one article uses, no pagination. It also said that two points are still `[needs confirmation]`: the order of tags with the same count and the basis of the limit. No file changed.
 
 ### 3. Ask about what is unknown and record the answer as a decision
 
 ```
-I want to change the coupon stacking rule. What do I need to confirm first?
+I want to change how the tag list is ordered. What do I need to confirm first?
 ```
 
-The interview skill lists the policies the request touches, separates those confirmed by code, tests or sources from those that are not, and turns the unconfirmed ones into questions. Once you answer, the writer rewrites the policy as confirmed and leaves a `decision` log entry and a decision link.
+The interview skill listed the eight policies the request touches, marked three as confirmed by code, and turned the rest into seven questions, from "does 'tag list' mean GET /api/tags or the tagList inside articles" to "do existing clients depend on the current order". It stopped without editing anything. The answer: only GET /api/tags; keep most used first; ties stay undefined on purpose; the 10-tag limit stays and applies after sorting. The writer then confirmed the policy and added a `decision` entry and the decision link (see [Log](#log)). `check` caught two things on the way: the decision link pointed at `../log.md` instead of `../../log.md` (`broken-link`), and current behavior grew to seven steps without a diagram (`missing-flow`), so the writer added one ([commit](https://github.com/Sienna94/crumbs-spec-conduit/commit/7b86052)).
 
 ### 4. Ingest a source document
 
 ```
-Apply docs/raw/coupon-policy-v3.pdf.
+The upstream API spec changed. Apply docs/raw/realworld-b8a37f1-validate-email-format.diff.
 ```
 
-The ingest skill reads the source, finds the affected documents through the index, backlinks and evidence, and shows the list of intended changes first. Only after confirmation does it edit the owning documents and add an `ingest` entry. There is no automatic merge.
+The source is the real upstream commit that added email-format validation to the RealWorld spec. The ingest skill read it, found the registration, login and account-update documents through the index and listed four claims. Then it stopped on a conflict: the source expects 422 "is invalid" for a malformed email, while the documents and the code say the format is not checked. Asked whether the source or the code wins, we chose the code, because documents describe current behavior. The skill wrote one `Email format` policy in the registration document with the current behavior and a question that cites the upstream spec, added one linking sentence to the login and update documents, and logged an `ingest` entry ([commit](https://github.com/Sienna94/crumbs-spec-conduit/commit/130946a)). Nothing was edited before the change list was confirmed.
 
-### 5. Find an answer
+### 5. Reflect a code change
 
 ```
-How many items can go into the cart?
+I added email format validation to registration, login and account update
+(server/schemas/user.schema.ts, not committed yet). A malformed email now gets 422
+with {"errors":{"email":["is invalid"]}}. Update the docs.
 ```
 
-The finder goes index → shopping overview → cart document and answers with `### 수량 상한` as the source. For term or concept questions it checks the terms section of `concepts/overview.md` first. If the documents do not answer, it says "not in the documents" and names the closest one.
+The writer found the owning document with `grep -rl 'user.schema' docs/specs`, since all three documents name that file under Evidence. It rewrote `Email format` as a confirmed policy, which closed the question from example 4, and updated the linking sentences in login and update and two flow diagrams. What the code did not settle, which addresses count as valid and whether a blank email also reports "is invalid", became a new question instead of a guess; a blank email does get both messages. The code and the documents are one commit ([commit](https://github.com/Sienna94/crumbs-spec-conduit/commit/32fd2f3)).
 
 ### 6. Check in CI
 
+A GitHub Actions job that fails on errors:
+
 ```yaml
-- run: npx crumbs-spec check --format json > crumbs-report.json
+jobs:
+  specs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npx crumbs-spec check --format json > crumbs-report.json
 ```
 
 Exit code 1 means there are errors. Warnings (`open-question`, `missing-flow` and so on) do not fail the build.
@@ -353,7 +387,11 @@ Exit code 1 means there are errors. Warnings (`open-question`, `missing-flow` an
 - Requirement IDs, front matter and enforced grammar such as EARS. Navigation lives in links and headings only.
 - Change-history tables inside documents and one file per decision. Decisions go into the single log and documents point at them.
 - Definition-only term pages. The overview's terms section is enough.
-- Style and content judgement in `check`. Style is handled by the skill guidance and the markdownlint sample under [docs/lint/](docs/lint/README.md).
+- Style and content judgment in `check`. Style is handled by the skill guidance and the markdownlint sample under [docs/lint/](docs/lint/README.md).
+
+## Tests and compatibility
+
+`npm test` runs the node:test suite on Linux and macOS in CI (see `.github/workflows/ci.yml`). Changes are listed in [CHANGELOG.md](CHANGELOG.md). Until 1.0, a minor version may change check rules, templates and skill text; a patch version only fixes bugs.
 
 ## Roadmap
 
@@ -363,6 +401,6 @@ Exit code 1 means there are errors. Warnings (`open-question`, `missing-flow` an
 | 2 | Four skills, `log add`, flow section, responsibility-size rules, terms and concept pages, decision log | done |
 | 3 | `crumbs reverse <path>` — a command that drafts from code (the writer skill does this today) | planned |
 | 4 | `crumbs drift --base <ref>` — finds documents whose evidence changed in a diff | planned |
-| 5 | Example app and a navigation-cost benchmark runner | planned |
+| 5 | Public example ([crumbs-spec-conduit](https://github.com/Sienna94/crumbs-spec-conduit)) and a navigation-cost benchmark runner | example done, runner planned |
 
 The `lang` setting (`en` by default, `ko` for Korean) selects the language of the templates, skills and messages, so one repository uses one language.

package/dist/src/check.js

@@ -14,21 +14,23 @@ import { missingSection } from './rules/missing-section.js';
 import { openQuestion } from './rules/open-question.js';
 import { sectionOrder } from './rules/section-order.js';
 import { unreachable } from './rules/unreachable.js';
+import { unterminatedComment } from './rules/unterminated-comment.js';
 import { finding } from './model.js';
-// 모든 문서는 첫 제목이 H1이어야 한다.
+// 모든 문서는 첫 제목이 H1이어야 한다. 제목이 없는 문서는 1줄을 가리킨다.
 function missingTitle(graph) {
     return graph.docs
         .filter((doc) => doc.headings[0]?.level !== 1)
-        .map((doc) => finding('missing-title', 'error', doc.file, MESSAGES[graph.lang].h1Title, doc.headings[0]?.line));
+        .map((doc) => finding('missing-title', 'error', doc.file, MESSAGES[graph.lang].h1Title, doc.headings[0]?.line ?? 1));
 }
 function checkGraph(graph) {
     if (graph.index === undefined) {
         const indexPath = relPath(graph.root, graph.indexAbs);
         // 인덱스가 없으면 다른 규칙은 돌리지 않는다.
-        return [finding('index-missing', 'error', indexPath, MESSAGES[graph.lang].indexMissing(indexPath))];
+        return [finding('index-missing', 'error', indexPath, MESSAGES[graph.lang].indexMissing(indexPath), 1)];
     }
     return [
         ...missingTitle(graph),
+        ...unterminatedComment(graph),
         ...brokenLink(graph),
         ...brokenAnchor(graph),
         ...unreachable(graph),
@@ -45,10 +47,10 @@ function checkGraph(graph) {
     ];
 }
 const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-// file, line(없는 것은 마지막), rule, message 순으로 정렬한다.
+// file, line, rule, message 순으로 정렬한다.
 function sortFindings(findings) {
     return [...findings].sort((a, b) => compareText(a.file, b.file) ||
-        (a.line ?? Number.MAX_SAFE_INTEGER) - (b.line ?? Number.MAX_SAFE_INTEGER) ||
+        a.line - b.line ||
         compareText(a.rule, b.rule) ||
         compareText(a.message, b.message));
 }

package/dist/src/check.js.map

@@ -1 +1 @@
-{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/check.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.js

@@ -116,6 +116,8 @@ function logAdd(root, values, args, lang) {
     const body = values.body === undefined ? undefined : normalizeLogBody(values.body);
     if (body !== undefined && hasHeadingLine(body))
         throw new UsageError(m.bodyHeading, lang);
+    if (rawTitle.includes('<!--') || (body ?? '').includes('<!--'))
+        throw new UsageError(m.commentForbidden, lang);
     const config = loadRepoConfig(root, values.config, lang);
     assertLogDocument(root, config);
     rejectForeignOptions(values, LOG_ADD_OPTIONS, config.lang);