The shapes of the Markdown documents the stages commit to the document repo. The repo holds no JSON (ADR-0042).
One reader and one writer implement this page: packages/agents/builtin/plugins/reverse_engineering/scripts/docmd.py writes, hooks/reader/document.ts reads. A reader never throws on a malformed file; it drops what does not fit.
| Block | Shape | Used for |
|---|---|---|
| Front matter | --- lines at the top: key: value, strings quoted as JSON, numbers and booleans plain, a list as a block (key: then - "item"). Only scalars and short lists. |
Facts about the document: totals, provenance, counts |
| Table | GFM; one record per row; | escapes a pipe; one line per cell |
Records of one kind: catalog items, edges, verdicts, findings |
| Card | A heading ## id: title (or ###), prose, field bullets - **key:** value (a list is nested bullets), subsections one level down |
A record with prose or nested fields: a catalog item, a rule, a finding detail |
| List | Bullets, paths and ids in backticks | Unbounded lists: the files of an item, the unassigned files |
Anything unbounded is a list or a table inside a section, never front matter. Ids and paths are written in backticks.
One more shape is read only by the design-set tools: a directive comment under a heading of a design template (<!-- required, table: …, check: …, -->), which holds that section's contract and is invisible when rendered. See Design templates.
Path (10-applications/<app>/…; a path that starts with a numbered root is from the repo root) |
Written by | Content |
|---|---|---|
01-legacy/inventory.md |
inventory.py |
Front matter with the figures of record (sloc, ksloc, complexityIndex, sources: the <repository id>@<commit> of each legacy repository measured, …); tables Languages, Directories, Size distribution, Most complex files |
01-legacy/topology.md |
render_topology.py |
Front matter (system, counts, truncated); tables Domains, Edges between domains, Leaves (with Entry point and Dead end columns), Edges; Observations, Flows, a Mermaid Diagram |
01-legacy/_catalog/index.md |
render_catalog.py |
Front matter (app, source commit, counts); tables Modules and Items; lists Ambiguities and Unassigned files |
01-legacy/_catalog/<module>.md |
render_catalog.py |
One card per item: fields referenceCode, kind, status, loc, complexity, digest, aliases; subsections Leaves, Depends on, Used by, Data stores, Parts, Files |
01-legacy/plan.md |
check_plan.py |
Front matter (version, catalogSources, counts); the strategy; a card ## Batch <n>: <title> per batch (rationale, fields risk, loc, high complexity, cohesion, subsections Items, Depends on outside); tables Left out, Dropped |
01-legacy/<module>/<unit>/understanding.md |
finish_items.py |
Front matter: status: understood, digest, sources, runId, specification, counts, and profile: <kind>@<version> (with profileMissing when the specification lacks a section of it, specification profiles). Its presence on the default branch means the unit is understood |
…/spec.md |
the specification job | The 11 sections of the AS-IS specification; the last, Gaps and questions, is a table ID | Kind | Question | Where | Impact, with the optional Settled by | Probe (ids GAP-<scope>-0001; kinds missing-source, unresolved, ambiguous, unverified; impact blocking, risk, note; settled by source-owner, expert, data, check, the kind's default when empty; ADR-0057, ADR-0087) |
…/identifiers/{rules,findings,gaps}-ids.md |
split scripts / finish | Allocation history: front matter type, scope, version, allocated; table ID | Fingerprints | Anchor | Status; identifier contract |
…/rules.md |
split_rules.py |
The rules index: front matter (catalogVersion, rules, p0); a table ID | Name | Category | Priority | Confidence | Version | Status | Source | Rule file; a table Retired rules; the explicit no-rules line when empty |
…/rules/<rule id>.md |
split_rules.py |
One rule: front matter (id, name, category, priority, confidence, status, version, digest, source, …); sections Summary, Specification (Given/When/Then), Decision table, Flow, Parameters, Inputs and outputs, Evidence, Edge cases, Suspected defects, Open questions, Acceptance scenarios, Version history (only those with evidence), see ADR-0046 |
…/data-objects.md |
split_rules.py |
One ## name section per object with Source: and a field table |
…/rules-review.md |
people, in a pull request | Table Rule | Verdict | Approver | Date (and an optional Note); verdicts confirmed, refuted, clarify |
…/findings.md |
split_findings.py |
Scorecard table; table Findings by severity; a ### SEC-… card per finding for the fix and the masked evidence; Tools not run, Files reviewed |
…/topology.md |
scope_items.py |
The topology document of one item: its leaves, Depends on, Used by, Data stores |
…/trace.md |
finish_items.py |
Front matter (openQuestions, the unresolved rows of the specification's gaps table at generation; result views and rebuilds derive the current count from the specification); sections Entry points, Rules applied, Findings, Dependencies (table), Data objects, External systems, Files, Requirements, Pull requests, Tests |
01-standards/templates/<set>/set.md, <template>.md |
people | A design set: front matter (id, title, version, needs, stage) and a files table; templates with directive comments (design templates) |
01-standards/templates/<set>/<kind>/profile.md, <template>.md, _examples/ |
people | The profile of a set for a unit kind: front matter (kind, version, removes), a files table, templates that replace the set's and finished examples (ADR-0053) |
02-modern/<module>/<unit>/README.md |
finish_items.py, then the Kintsugi API and people |
The unit's card: front matter (identity, kind, state, source, target, links, waived) and a short body (unit files) |
02-modern/<module>/<unit>/<set>/<file> |
scaffold_design.py, then the design stage's designer |
A design document: front matter template: "<set>@<version>" (or "<set>/<kind>@<version>") and unit, then the sections and tables the template names |
_generated/traceability.md |
rebuild_aggregates.py |
Front matter with the totals the headlines read; one row per understood unit |
_generated/GAPS.md |
rebuild_aggregates.py |
The units' Gaps and questions rows joined (Item | ID | Kind | Impact | Question | Where | Settled by | Probe | Status | Answer | Evidence), blocking first; front matter counts by impact and kind, and the open gaps per settler (ADR-0057, ADR-0087) |
_generated/DATA_ACCESS.md |
rebuild_aggregates.py |
The read/write matrix of data stores and items from the catalog's links (Data store | Written by | Read by, then Item | Kind | Reads | Writes); front matter counts (ADR-0060) |
_generated/BUSINESS_RULES.md, DATA_OBJECTS.md, SECURITY_FINDINGS.md, README.md |
rebuild_aggregates.py |
The index of the units' rules (one row per rule with its version and a link to the rule's file), the units' objects and findings joined; the index of the specifications |
The data a run passes between its steps is JSON under scratch/<app>/ in the job workspace and is never committed: inventory.json, topology.json, catalog.json, catalog-draft/, understand/ (scope.json, shards.json, scan.json, rules_result.json, graph.json, plan-draft.json, briefs/, trace/). The plans mark it intermediate.
The job-output hook refuses a file over 1 MiB, and the API serves a file up to 2 MiB; the documents above stay under both by summarising (the inventory and the topology cap their tables, the catalog index lists at most 200 unassigned files). A module whose catalog document outgrows the API limit is not shown.
The original specification's Gaps and questions table can add Settled by, Probe (ADR-0087) and Status, Answer, Evidence columns to its five
required columns. Status is open or resolved; an absent/blank status is open. Only a resolved row with meaningful
non-placeholder answer and evidence clears a blocker. Preserve its ID, question, kind, location and impact. Reopen it
in the same row when the answer is withdrawn or its supporting unit evidence changes. The generated gaps view retains
all rows and includes open and resolved totals; current open-question counts exclude valid resolved rows. No answer
file or database register is used (ADR-0082).
A deliberately generated draft design has draft: true in each document's front matter. Both conformance checkers
report that marker as a draft problem. A merged draft cannot fulfil a prerequisite or authorize build/review; after
the inputs are resolved, a final regeneration writes the current template without that marker. Unsupported/ambiguous
values of draft are treated conservatively as draft; only an absent marker or boolean false is final.