Generated files, schemas, and lifecycle

Paths below use the default docs directory. Most relocate with docs_dir; the project configuration remains at the fixed docs/capstone/capstone.json path. Capstone's final documents are meant to stand on their own: decisions and their rationale belong in these outputs, not only in a local interview transcript.

Reference chapters#

02-models.md places each entity under ### <Entity> in Fields and types. Every entity section needs a table with Field, Type, and Required; Default and Notes are optional. Names are lookup keys, not decorative titles. Enum values belong in Notes, for example accepted: draft, published.

The index does not carry a second copy of chapter freshness. Absent topics receive explanatory rows. Large subsystems may split a topic while preserving its number, such as 01-architecture-api.md and 01-architecture-worker.md.

Observed file frontmatter#

This is an illustrative shape, not a captured file:

---
generated_at_commit: 0123456789ab
generated_date: 2026-09-09
capstone_version: 6.4.1
content_hash: abcdef012345
paths_covered:
  - ":(top)src/auth/**"
  - ":(top)src/routes/**"
---

generated_at_commit and content_hash are 12-character Git values. The date is when the file was generated; capstone_version identifies the writer's template generation. paths_covered is the set of source paths used for refresh, anchored at the repository root. If the manifest cannot be read, the writer omits the version rather than inventing one. Outside Git, commit/hash requirements are waived. Prescriptive design uses mode: prescriptive; interview outputs without coverage globs have different freshness rules.

The machine schema requires generated_date on generated Markdown other than the index. Git-specific keys are waived for prescriptive and non-Git outputs; scenario/UI records waive coverage keys when they have no paths_covered. The checker handles an absent or older version in its freshness pass, not as a duplicate schema finding.

Product and design outputs#

Every logic scenario has these exact sections: Trigger & preconditions; Steps; Branches; Unhappy paths; State transitions; Invariants; Outcomes & side effects; Dimensions not in play. The final section distinguishes ruled-out dimensions from unanswered ones.

standards.md contains 17 domain headings and Not in play; the design chapter lists them. uiux/02-system.md has an Assets table with Asset | File | Source | Status, and the code build stops for awaited assets.

Working files and durable history#

The factual reference follows docs_in_git; interviews, feature files, previews, rasters, and review reports remain local regardless of that choice. Ledger, project configuration, and questionnaires are committed exceptions. A fresh clone can consume completed reference outputs and their ledger without the interviews. It cannot recover unfinished local Q&A, feature plans, or checked task state that were never copied there.

Each writing stage records its ledger entry before its done marker. New entries are fragments; a later writing run on the default branch folds them. Past 200 folded entries, all but the newest 100 move into year files. Keys remain searchable in fragments and rotation files. A shipped feature's folder is deleted only after its wrap; its implement/<id> key then tells later runs it is done.

Find the event that completed a stage#

Ledger keys are internal durable identifiers, not commands. Search changelog.md, year files, and pending fragments together. <id> is a feature identifier; <stamp> is the run's source/date stamp; Q<n> is the highest incorporated interview entry. Question numbers may appear in these keys, but final chapters should not send readers back to the interview.

start and feature normally route rather than create an event of their own; their writing stages record the work. Readback is start's named exception. help, core's help route, and map check write no event. A no-op map or report-only doctor/retro also has no repair/write entry.

Generated sections may be rewritten. Manual prose edits are not generally preserved. The explicit protected exceptions are ledger history and previously confirmed to/from values on still-existing interface rows. Keep durable design decisions in their owning final files and let the relevant command record changes.

Sources: machine schema, topic definitions, index and ignore rules, ledger and lifecycle.