# What every shipped file is, and why

<!-- GENERATED by tools/file-map.mjs from standard/standard.manifest.json - do not edit by hand.
     Run `node tools/file-map.mjs` after changing the manifest; CI fails on a stale copy. -->

> **Generated, not written.** Every row below comes from
> [`standard.manifest.json`](../standard/standard.manifest.json) - the same data
> `self-verify` reads to decide whether your repo complies. A hand-written map would be a
> second description of the same thing, and second descriptions rot.

Read this when you are orienting: *what is this folder, why does it exist, which rule made it
so.* The **Rule** column links the numbered rule in the spec that each entry enforces, so any
row can be traced from "there is a file here" to "here is why the standard says so".

**Adapt** is how an entry lands in your repo when you align: `copy` arrives verbatim,
`merge` is reconciled with what you already have, and `fill-from-repo` is a shell you
author, because the standard never invents your content. **Needed** says whether a missing
entry counts as drift, and at which profile (`core` is every repo; `scale` is teams).

This map is the index, not the manual. What each path is **for**, what belongs in it, what
does not, and the decisions behind it are written up one page per path - open the path in
the sidebar. Those pages live with the standard and are read at latest, rather than being
copied into your repository as folder READMEs that then age in place.

## At the root - what an agent and a reader meet first

| Path | What it is, and why | Needed | Adapt | Rule |
|---|---|---|---|---|
| `AGENTS.md` | the single agent entry point | **required**, core | `fill-from-repo` | [R1](../standard/SPEC.md) |
| `.standards-version` | the state this repo last aligned to - a bookmark the delta is measured from, never a version to stay at (ADR-025); written by align-to-standards / update-to-latest | **required**, core | `fill-from-repo` | [R2](../standard/SPEC.md) |
| `standard.manifest.json` | this manifest, matching the recorded state - what self-verify checks against | **required**, core | `copy` | [R2](../standard/SPEC.md) |
| `SPEC.md` | the normative core this manifest projects - readable in place | optional, core | `copy` | [R2](../standard/SPEC.md) |
| `CLAUDE.md` <br><small>or `AGENTS.md`</small> | the file Claude Code loads first - points at AGENTS.md and carries the rule to check the skills before acting (R1); a non-Claude repo carries the same content in whatever its agent loads first | optional, core | `merge` | [R1](../standard/SPEC.md) |
| `specs` | living capability specs | **required**, core | `fill-from-repo` | [R8](../standard/SPEC.md) |
| `backlog.md` <br><small>or `docs/backlog.md`</small> | the work ledger; items leave only when their DoD is met | **required**, core | `fill-from-repo` | [R15](../standard/SPEC.md) |
| `backlog-archive.md` <br><small>or `docs/backlog-archive.md`</small> | where a closed row goes, with a `where` cell naming what its content became; ships empty, and a repo that has closed nothing deletes it until the first row moves (ADR-051) | optional, core | `fill-from-repo` | [R15](../standard/SPEC.md) |
| `CHANGELOG.md` <br><small>or `docs/CHANGELOG.md`</small> | the only home of history (ADR-018); a PR describes its change under `## Unreleased` and bumps the version itself, PATCH by default unless the requester directs otherwise - R18/R25's one path, at every profile | **required**, core | `fill-from-repo` | [R18](../standard/SPEC.md) |
| `.gitleaks.toml` | secret-scan config (the shipped scan SHOULD gate CI) | optional, core | `copy` | [R19](../standard/SPEC.md) |
| `.gitattributes` | forces LF on the shipped bash guards and Node scripts - a repo whose own setting is eol=crlf makes every hook exit 127 with empty stdout, which for a deny-guard is silence, not a refusal | **required**, core | `merge` | [R19](../standard/SPEC.md) |
| `README.md` | the repo's front door - authored from this repo's reality | optional, core | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `CONTRIBUTING.md` | contribution mechanics pointer - defers to AGENTS.md | optional, scale | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `SECURITY.md` | vulnerability-reporting contact and posture (placeholders filled at adoption) | optional, core | `fill-from-repo` | [R19](../standard/SPEC.md) |
| `.nvmrc` | exact runtime version for the dependency-free guards and CI setup | optional, core | `copy` | [R21](../standard/SPEC.md) |

## `docs/` - the knowledge the repo keeps

| Path | What it is, and why | Needed | Adapt | Rule |
|---|---|---|---|---|
| `docs/decision-records` | the ADR/BDR decision log | **required**, core | `fill-from-repo` | [R5](../standard/SPEC.md) |
| `docs/ideas` | pre-decision ideas - status-driven, graduate into records/specs on approval (ADR-010) | optional, core | `fill-from-repo` | [R14](../standard/SPEC.md) |
| `docs/discovery` | discovery dossiers - provenance-stamped extracts per topic, never normative (ADR-024) | optional, core | `fill-from-repo` | [R5](../standard/SPEC.md) |
| `docs/facts.json` | the facts this repo restates: one home each, every restatement declared | optional, core | `fill-from-repo` | [R4](../standard/SPEC.md) |
| `docs/facts.example.json` | the shape of a declared fact, reference only - do not rename or copy its placeholder content into docs/facts.json; write docs/facts.json from scratch, in this shape, once this repo has its first fact worth declaring (R4) | optional, core | `copy` | [R4](../standard/SPEC.md) |
| `docs/PRINCIPLES.md` | the altitude apex R1 names - optional but expected | optional, core | `fill-from-repo` | [R1](../standard/SPEC.md) |
| `docs/personas.md` | the persona roster the R10 gate checks specs against - without it the gate has nothing to hold | **required**, core | `fill-from-repo` | [R10](../standard/SPEC.md) |
| `docs/adoption-intake.md` | what Step 0 measured and asked before any align work proceeded - the record that makes intake checkable, not just performed (ADR-042) | **required**, core | `fill-from-repo` | [R26](../standard/SPEC.md) |
| `docs/adoption-assessment.md` | what Gate 2's eight-pass assessment found - maturity per pass, top risks, findings grouped by the owner role that must act; the evidence Gate 5's count is derived from (ADR-048) | **required**, core | `fill-from-repo` | [R27](../standard/SPEC.md) |
| `docs/README.md` | the docs hub table | optional, core | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `docs/ARCHITECTURE.md` | how it is built - the altitude names it (filled from this repo) | optional, core | `fill-from-repo` | [R1](../standard/SPEC.md) |
| `docs/PRODUCT.md` | what it is and where it is going (filled from this repo) | optional, core | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `docs/conventions.md` | canonical conventions block - merged into AGENTS.md at adoption | optional, core | `merge` | [R1](../standard/SPEC.md) |
| `docs/analytics.md` | event-taxonomy tracking plan template | optional, scale | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `docs/journeys` | per-persona journey maps coupled to capabilities | optional, scale | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `docs/research` | anonymized research studies feeding personas, ideas and specs | optional, scale | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `docs/runbooks` | operational runbooks + postmortems - agent-followable at 3 a.m. | optional, core | `fill-from-repo` | [R3](../standard/SPEC.md) |
| `docs/sprints` | work sprints - what a team committed to and by when; an intent is in the pool or in exactly one sprint (ADR-028) | optional, scale | `fill-from-repo` | [R15](../standard/SPEC.md) |

## `specs/` - behaviour, by capability

| Path | What it is, and why | Needed | Adapt | Rule |
|---|---|---|---|---|
| `specs/capability-map.json` | capability -> code globs, so the coupling guard can bind spec to code | **required**, core | `fill-from-repo` | [R11](../standard/SPEC.md) |

## `scripts/` - the guards, and the spec engine's runtime

| Path | What it is, and why | Needed | Adapt | Rule |
|---|---|---|---|---|
| `scripts/self-verify.mjs` | the verify step - checks the repo against this manifest | **required**, core | `copy` | [R16](../standard/SPEC.md) |
| `scripts/spec-structure.mjs` | spec layout guard | **required**, core | `copy` | [R16](../standard/SPEC.md) |
| `scripts/facts-check.mjs` | a fact restated in prose still agrees with its source - declared homes and claims (R4) | optional, core | `copy` | [R4](../standard/SPEC.md) |
| `scripts/schema-pair.mjs` | the DDL under database/schema/ and its typed twin stay 1:1 - the declared edge resolves and every name is covered | optional, core | `copy` | [R24](../standard/SPEC.md) |
| `scripts/decision-records-check.mjs` | the ADR/BDR README index and the files on disk agree - no duplicate id, nothing indexed that is not there, nothing there that is not indexed | **required**, core | `copy` | [R5](../standard/SPEC.md) |
| `scripts/adoption-gates.mjs` | the Gate 2 and Gate 5 artifacts carry what the gate is for - eight passes rated, the scope block's total equal to the sum of its categories, an owner role on every alignment item | **required**, core | `copy` | [R27](../standard/SPEC.md) |
| `scripts/spec` | the spec engine runtime the skills invoke (gate, setup, templates, MIT licence) | **required**, core | `copy` | [R22](../standard/SPEC.md) |
| `scripts/lib` | what more than one guard needs - glob matching, so two guards cannot answer the same question differently | **required**, core | `copy` | [R16](../standard/SPEC.md) |
| `scripts/verifyAgentGuards.sh` | drives every guard with real commands - they only emit output on a denial, so a broken guard is otherwise silent | optional, core | `copy` | [R19](../standard/SPEC.md) |
| `scripts/spec-guard.mjs` | code<->spec coupling guard (+ --audit) - the tool ships at core, the blocking CI gate is scale (R11) | **required**, core | `copy` | [R11](../standard/SPEC.md) |
| `scripts/sprint-guard.mjs` | proves the one-place invariant the pool and the sprints depend on | optional, scale | `copy` | [R15](../standard/SPEC.md) |
| `scripts/backlog-archive-check.mjs` | a closed row reached the archive with a pointer to what its content became, instead of being deleted (ADR-051) | **required**, core | `copy` | [R15](../standard/SPEC.md) |
| `scripts/generate-dashboard` | renders the work state - pool, sprints, timeline, records, changelog - as one static page for the people who never open the repository; index.mjs is the generator, src/ the page and password-gate material it inlines. A projection, never a second place work is tracked | optional, core | `copy` | [R15](../standard/SPEC.md) |

## `.claude/` - the procedures, in Claude Code's reference form

| Path | What it is, and why | Needed | Adapt | Rule |
|---|---|---|---|---|
| `.claude/skills` <br><small>or `.agents/skills`</small> | the lifecycle skills - the standard as executable procedures (Claude reference form; a non-Claude repo ports them to its agent's own mechanism) | **required**, core | `copy` | [R22](../standard/SPEC.md) |
| `.claude/settings.json` | agent settings baseline - permission lists, and which guards run | optional, core | `merge` | [R19](../standard/SPEC.md) |
| `.claude/hooks` | the pre-execution guards themselves - remote-DB writes, force-push, CI secrets - behind one dispatcher that denies when any of them is missing or broken | optional, core | `copy` | [R19](../standard/SPEC.md) |

## `.github/` - templates, never enabled in this repo

| Path | What it is, and why | Needed | Adapt | Rule |
|---|---|---|---|---|
| `.github/workflows/gitleaks.yml` | the secret-scan workflow template | optional, core | `merge` | [R19](../standard/SPEC.md) |
| `.github/workflows/standards-update-watch.yml` | weekly notification that a newer standard exists - opens one issue per release, never edits the recorded state (ADR-025) | optional, core | `merge` | [R2](../standard/SPEC.md) |
| `.github/workflows/spec-guard.yml` | the CI workflow that wires self-verify + both guards - how R16's gate actually runs | **required**, core | `merge` | [R16](../standard/SPEC.md) |
| `.github/pull_request_template.md` | PR template - what/why, decision-record impact across both streams, test plan, checklist | optional, scale | `merge` | [R5](../standard/SPEC.md) |
| `.github/workflows/dashboard.yml` | builds the dashboard on every push to main; publishes it only when the repository is public or the build is locked with a password, because Pages on a private repository is served publicly | optional, core | `merge` | [R15](../standard/SPEC.md) |

## Adopted by reference, never copied

These are not in your repo. They are read at their home in the standard, always latest
(ADR-023, ADR-025) - so the method improves without a re-scaffold, and `self-verify` notes
them rather than checking files.

| Document | What it covers |
|---|---|
| [`docs/method/taxonomy.md`](#) | where each kind of knowledge lands (ends 'ADR or rule?') |
| [`docs/method/checklist.md`](#) | the forks every repo consciously decides, with paved-road defaults |
| [`docs/method/adoption.md`](#) | the gated path from unaligned to aligned + the modernize pass |
| [`docs/method/repo-assessment.md`](#) | the read-only assessment the transition agent runs, and the periodic health check |
| [`docs/method/ways-of-working.md`](#) | how work flows around the spec (PO -> dev -> AI) |
| [`docs/method/changelog-process.md`](#) | the two-outputs changelog model teams follow |
| [`docs/method/working-with-specs.md`](#) | real situations -> the prompt -> what the standard does (specs day to day) |
| [`docs/method/discovery.md`](#) | discovery dossiers: from a meeting to a spec with provenance (ADR-024) |
| [`docs/method/working-with-ai/README.md`](#) | evidence-checked practices for driving the agent: context, verification, review load, blast radius |
| [`docs/method/self-verify.md`](#) | what drift 0 does and does not certify - the tiers, the flags, the arithmetic |
| [`docs/method/prerequisites.md`](#) | what must be installed before an agent starts an adoption |
| [`docs/method/security-baseline.md`](#) | the axes a repo decides once - a menu, answered in your own security ADR |
| [`docs/tree/specs.md`](#) | how to write a capability spec - the tiers, the contracts, what makes buildable checkable (R8, R9) |
| [`docs/tree/docs-decision-records.md`](#) | the ADR/BDR streams, the record test and the altitude hierarchy (R5) |
| [`docs/method/agent-work.md`](#) | what the agent starts on its own, what it refuses, and what it never decides for you |
| [`docs/method/dev-work.md`](#) | the dev's job when building: intent in, a buildable spec plus its records out |
| [`docs/method/lead-work.md`](#) | rolling the standard out across more than one repo, consistently |
| [`docs/method/product-work.md`](#) | the product owner's job: what should be true, and for whom |
| [`docs/method/tracking-work.md`](#) | the three files that answer what is still owed, what is happening now, and when it lands |
| [`docs/method/tracker-sync.md`](#) | the OPTIONAL tracker-sync extension - a per-capability sidecar core never reads; skip it entirely if you sync to no tracker (ADR-032) |
| [`docs/method/working-language.md`](#) | language is a configuration, not a constraint - the reasoning and the guidance for a non-English team |

## Required headings

A file can exist and still be a shell. These headings are checked by name.

| File | Heading | Why it must be there |
|---|---|---|
| `AGENTS.md` | `Altitude` | the precedence order wins-on-conflict must be stated |
| `CHANGELOG.md` | `Unreleased` | R18/R25 - a PR describes its change here; nothing else holds history, and drift 0 must not be reachable with no changelog at all |
| `AGENTS.md` | `The loop runs itself (unprompted)` | the unprompted-behaviour contract survives deletion or a thin rewrite - it is what makes the loop self-triggering rather than merely documented |
| `AGENTS.md` | `Volunteer, don't wait to be asked` | an ambiguous mention of a bug, a decision, or scope creep gets named and asked about, not silently actioned or silently dropped |
| `AGENTS.md` | `Say where you are` | long work reports itself every 60-120 seconds - what is happening and what it is waiting on - and never invents progress or a result that has not come back |