create-afe-project 0.0.0-stage → 1.0.0

package/template/docs/documentation-rules.md.jinja

@@ -0,0 +1,200 @@
+# Documentation rules
+
+Reference for creating, changing, and retiring documentation. `AGENTS.md` holds the short rules
+and takes precedence; this file comes from the template, so report a disagreement to the
+template (section 8). It has at most 200 lines (checked): an addition pays with a removal.
+
+## 1. Principles
+
+- Docs as code: documentation lives here, in Markdown, is reviewed like code, and is checked
+  automatically (section 7).
+- Progressive disclosure: entry files (`AGENTS.md`, `docs/README.md`) stay short and link out.
+- One owner per fact: `docs/README.md` maps kinds of facts to owner documents; others link, never
+  copy. Generated artefacts come from a script, are checked in CI, and are never hand-edited.
+- Content before structure: a section exists only with real content; future ones are listed in
+  the map, not created as placeholders. Diátaxis is a lens for content type, not a folder tree.
+
+## 2. Document kinds and formats
+
+| Kind | Location | Format |
+| --- | --- | --- |
+| Agent rules | `AGENTS.md` | at most 90 template lines plus a project block of at most 10 lines (checked); numbered sections; `CLAUDE.md` imports it with `@AGENTS.md` |
+| Documentation map | `docs/README.md` | tables of existing and planned sections |
+| Testing rules | `docs/testing-rules.md` | at most 80 lines (checked); numbered sections: what a test is for, how it proves behaviour, tests and the change, gates; the project's test levels, tools, and edge cases live in its own documents |
+| Contribution rules | `docs/contributing.md` | at most 200 lines (checked); numbered sections: branches, commits, pull requests and when a change is done, template updates, review |
+| Decision (ADR) | `docs/decisions/NNNN-title-with-dashes.md` | only for a decision that meets section 5; short MADR 4.0 from `adr-template.md`, about one page, details linked to their owner document; front matter `status`, `date`, `decision-makers`, `scope`, `summary`, optional `supersedes` |
+| Decision index | `docs/decisions/README.md` | generated by `scripts/gen-decisions-index.sh` from the front matter of the records; never hand-edited |
+| Plan | `docs/plans/<slug>.md` | front matter `status`, `owner`, `created`, `review-by`; sections Goal, Steps, Open questions |
+| Requirement | `docs/requirements/` | one `REQ-NNN` per statement; RFC 2119 keywords; fields `status`, `source`, `verification`; its acceptance criteria `AC-NN` as Given, When, Then, with the check that establishes each |
+| Invariants register | `docs/invariants.md` | one `INV-NN` per invariant that must hold everywhere (`testing-rules.md`, section 4); fields `statement`, `source` (the requirement or owner decision), `enforced-by` (the test or project check that fails when it breaks, or `none`, which is an open question) |
+| Architecture | `docs/architecture/` | the system map: components, domain ownership, public interfaces and the dependency rules a project check enforces; explanation and reference; front matter `status`, `date`, `verified-against` (commit, or `none` while no code exists) |
+| Contract | `contracts/` | machine-readable, for example OpenAPI or JSON Schema; the file is the contract; prose links to it |
+| Operations | `docs/operations/` | how-to; every procedure names the command or file it relies on |
+| Conventions and recipes | `docs/conventions/`, `docs/recipes/` | one area or task per file; a convention names the check that enforces it, or `none`; a recipe lists its steps and commands, and skills link to it |
+
+This is the fixed set of document kinds the template defines; another project document, such as
+a changelog, exists only when the owner approves it and the map lists it. Front matter is YAML
+between `---` lines at the top of the file.
+
+## 3. Status vocabulary
+
+| Document | Allowed `status` values and transitions | Transition set by |
+| --- | --- | --- |
+| ADR | `proposed` to `accepted` or `rejected`; `accepted` to `deprecated` or `superseded by ADR-NNNN` | owner; agents create `proposed` |
+| Requirement | `draft` to `approved` to `implemented` or `retired` | owner; `implemented` needs a linked test |
+| Plan | `active`, then the file is deleted when done or abandoned | the change that completes or abandons it |
+| Architecture, operations | `draft` to `current`; `current` with a stale `verified-against` is suspect | the reviewer who verified it against code |
+| Owner decision in an owner document | a statement carries its document's status until the owner decides it; then it ends with, or its section opens with, `Decided by the owner, YYYY-MM-DD.` | owner; an agent adds the marker only on the owner's explicit instruction and lists it in the pull request (`contributing.md`, section 3); the owner's merge confirms it |
+
+Wording rules for behaviour:
+
+- "X does Y" only for implemented behaviour, merged code with a test; link the test or module
+  when the claim matters. Requirements use RFC 2119 keywords and never claim to be implemented.
+  Proposals say "proposed", accepted decisions "accepted" or "decided", unknown things "not
+  decided" or "unknown", never guessed.
+- A statement about a check (a lint rule, a test check, a hook, a workflow) names the forms it
+  catches and what is left to the review; an absolute claim about a check needs a test for each
+  form it covers.
+
+## 4. Currency
+
+A document is current when its content agrees with its owner source (code, contract, decision).
+`date` records the last content change. `verified-against: <commit>` records the last review
+against code and is required for architecture and operations documents once code exists.
+Touching a file or bumping a date is not verification.
+
+## 5. Lifecycle
+
+- Create a document when its first real content exists. A new section or plan needs the owner's
+  approval, and the map moves the section from planned to existing in the same change. An agent
+  may create an ADR with `status: proposed`; the owner's acceptance is the approval.
+- A new ADR only for a decision that is costly to reverse once code or data depend on it and had
+  a real alternative: language, runtime, or framework; storage and persistent data formats;
+  public protocols and contract formats; the security, isolation, or authentication model; an
+  external service or infrastructure. Copy `adr-template.md`, take the highest number plus one,
+  set `status: proposed`, record one decision in about one page, link the owner documents, and
+  regenerate the index: `scripts/gen-decisions-index.sh > docs/decisions/README.md`.
+- Other owner decisions are edits of the owner document with the marker of section 3; a decision
+  about a template-owned file goes to the template. Process rules live in the rule documents and
+  their checks; implementation choices stay in the pull request and the commit messages.
+- A plan only for work that spans sessions or needs owner follow-up; the change that completes or
+  abandons it deletes the file. A plan past `review-by` is updated or deleted in the next change
+  to `docs/`, and agents flag it.
+- Update the owner document in the same change that makes it wrong; refactoring that leaves
+  behaviour, contracts, and operations unchanged needs none. Update links and the map.
+- An ADR on `main` changes only its `status` line along section 3. A `proposed` ADR that needs
+  other wording is `rejected` and replaced; an ADR is never deleted or renamed. `superseded by
+  ADR-NNNN` names an ADR the same change adds, which lists the records it replaces in
+  `supersedes`. Requirements are retired with a reason and a link to their replacement.
+- There is no archive directory: a retired document stays with its retired status. Temporary
+  material (research notes, logs, transcripts, agent reports) never enters `docs/`; a person
+  extracts durable facts into the owner document.
+
+## 6. Alignment of documentation, contracts, and code
+
+These rules apply once code exists; they are fixed now so the first code follows them.
+
+- Contracts are machine-readable files in `contracts/`. The file is the source of truth for the
+  interface. The implementation conforms to it, and prose documentation links to it. Contract
+  linting and breaking-change detection are added to CI with the first contract, as decided in
+  an ADR together with the contract format.
+- Implemented behaviour is proven by tests that follow `docs/testing-rules.md`. Documentation
+  that describes behaviour links to the test or module. A described behaviour without a test is
+  `proposed`, not `implemented`.
+- CI runs the documentation checks, the contract checks, and the tests on every pull request.
+- Architecture documents carry `verified-against`; a review against code updates it.
+- With the first code: the project adds its code checks to `scripts/checks.d/` (section 9), and
+  `docs/README.md` moves "implemented behaviour" to existing.
+
+## 7. Automated checks and semantic review
+
+| Concern | Automated (`scripts/check.sh`, CI) | Semantic review, per change |
+| --- | --- | --- |
+| Markdown syntax and structure | markdownlint-cli2 | none |
+| Broken internal links and anchors | `scripts/check-links.mjs`, offline, with anchors | none |
+| Secrets in a change | {% if secret_scan %}gitleaks in the `secret-scan` workflow; {% endif %}the protect hook asks when an edit contains a known token format | none |
+| External links | not checked automatically | author verifies when adding; spot check on review |
+| Status correctness | none | status matches the evidence (section 3) |
+| Invented facts | none | every new fact has a source or is marked unknown |
+| Duplication | none | new content links instead of copying |
+| Currency | none | `verified-against` and the map are updated |
+| Documentation updated together with code | {% if docs_review %}`docs-review` workflow on pull requests, one pass, a sensor{% else %}none{% endif %} | reviewer confirms the owner document changed |
+| ADRs on `main` change only their status line (section 5); new ADRs carry `scope` and `summary`; the decision index matches the records | `scripts/check-decisions.sh`: Stop hook and `decisions` workflow | none |
+| A new ADR meets the criteria of section 5 | none | {% if docs_review %}`docs-review` reports it; {% endif %}the owner decides |
+| Template-owned files unchanged; one project block in `AGENTS.md`; the line budgets of the rule documents; `.claude/settings.json` generated, and every hook command it names exists (sections 2 and 9) | `scripts/check-template.sh`: Stop hook and `docs` workflow | none |
+| Each invariant names its check (section 2) | none | the review checks `docs/invariants.md` against the checks it names |
+| Project checks (section 9) | `scripts/check-project.sh` runs `scripts/checks.d/*.sh`: `scripts/check.sh` and `docs` workflow; a Stop hook only if the project adds one | as the project defines |
+| Code and tests meet the review rubric and the testing rules (`contributing.md`, section 6; `testing-rules.md`) | the project's test checks in `scripts/checks.d/`{% if fail_without_change %}; `scripts/fail-without-change.sh`{% endif %}{% if code_review %}; `code-review` workflow, a sensor{% endif %} | reviewer applies the rubric, by the class of the paths |
+| Merge readiness (`contributing.md`, section 3) | `scripts/check-decisions.sh --ready`, in the forms that section names{% if acceptance_check %}, with `scripts/check-acceptance.sh`{% endif %}; `decisions` workflow; signals, does not block | whether the tests prove their identifiers; no `blocker` open; the owner's merge confirms the listed markers |
+| Measurement of the sensors (`contributing.md`, section 3) | `scripts/pr-metrics.sh` aggregates the Metrics of merged pull requests | the owner removes a rule or check that never fires |
+| Finishing with failing checks | Stop hook in Claude Code | none |
+| Class approval and irreversible actions (section 8) | protect hook: owner prompt in Claude Code, denied headless; deny rules of `.claude/settings.json` | explicit, separate, owner-approved |
+
+Semantic review checklist for any documentation change:
+
+1. Each new statement has a status, and the status matches the evidence; a statement about a
+   check names the forms it catches and what is left to the review, and an absolute claim about
+   a check has a test for each form it covers (section 3).
+2. No requirement, default, or decision was invented; gaps are listed as open questions.
+3. No content duplicates another document; links point to the owner.
+4. The map (`docs/README.md`) and all links are updated; `scripts/check.sh` passes.
+5. ADRs that exist on `main` (apart from their status line), template-owned files, the
+   documentation map, and the structure are unchanged unless the change is explicitly about them.
+6. A new ADR meets the criteria of section 5 and links details instead of listing them; every
+   new `Decided by the owner` marker is listed in the pull request with the owner's instruction,
+   quoted with its date (`contributing.md`, section 3).
+
+## 8. Path classes, access, and changing these rules
+
+Governance follows risk and reversibility: every path a change touches takes the highest class
+that applies, from the template's built-in rules and the project's `.claude/path-classes`
+(section 9); `scripts/check-decisions.sh --classes` prints them and the review they need.
+
+| Class | Paths (defaults; the project adds its own) | Before the edit | Review before the pull request (`contributing.md`, section 6) |
+| --- | --- | --- | --- |
+| low | Markdown outside the rules, the decision index, a template update | nothing | none |
+| normal | code, tests, scripts: every path no other class takes | nothing | one reviewer |
+| gate | workflows, project checks and Stop hooks, `.claude/harness.conf`, dependency manifests and lock files, linter, test, coverage, and mutation configuration | nothing; listed under "Gate files", reviewed by the owner after the merge | one reviewer |
+| high | security, secrets, access and authentication, data migrations, money and billing, public contracts (`contracts/`) | nothing | {% if dual_review %}Santa loop{% else %}one reviewer; the Santa loop comes with the review module{% endif %} |
+| approval | `AGENTS.md`, the template-owned files, the generated manifest, answers file, and `.claude/settings.json`, the map, `.claude/path-classes`, `.claude/settings.project.json`, `.mcp.json`, credentials, ADRs on `main` or not `proposed` | the protect hook asks the owner; a headless run is denied | by the class of the content |
+
+The protect hook (`.claude/hooks/protect-docs.sh`) asks on an Edit, Write, or MultiEdit call and
+on a shell command of a form its comments name (a redirect, `cp`, `mv`, `tee`, `rm`, `sed -i`,
+and the like), and on the irreversible commands it names: `git push` that forces, deletes,
+mirrors, prunes, or pushes tags (a release); `gh pr merge`; `gh release create` and `delete`;
+`gh repo delete`. A side effect of a tool, a path or command named only inside a script or
+behind a variable, an alias, or a directory a script changes is not caught and is left to the
+review of the diff.
+
+Access control comes before prompts: an agent gets no credentials or tools for irreversible or
+production actions outside its task. `.claude/settings.json` denies force pushes and deletions
+of remote branches in the forms its rules spell out, and reading `.env`, `.env.*`, `*.pem`, and
+`*.key`; in `.claude/settings.project.json` the project adds deny rules, for example for the
+destructive tools of an MCP server (`mcp__<server>__<tool>`), and takes a template entry out
+with `"remove"`. For scripted, owner-driven changes the owner starts Claude Code
+with `DOCS_GUARD=off`, which also lifts the Stop hooks for decisions and template integrity.
+Other agents are bound by `AGENTS.md` and the review only.
+
+Template-owned files (section 9), including this file and `AGENTS.md` outside its project block,
+change only in the template and arrive through an update (`contributing.md`, section 5). A
+change to the map or the structure is a dedicated change approved by the owner.
+
+## 9. Ownership of files
+
+Every file belongs to exactly one class:
+
+| Class | Files | Changed by |
+| --- | --- | --- |
+| Template-owned | the files listed with their hashes in `.template/owned.sha256` (rules, ADR template, checks, hooks, skills, workflows, linter configuration), and `AGENTS.md` outside its project block | a release of the template, applied with `npx create-afe-project@latest update` (`contributing.md`, section 5); never edited in this repository |
+| Seeded | `README.md`, `CLAUDE.md`, `.gitignore`, `docs/README.md`, `.claude/path-classes`, `.claude/harness.conf`, `.claude/settings.project.json`, and the project block of `AGENTS.md`: created once by the template | the project |
+| Generated | `docs/decisions/README.md`, `.template/owned.sha256`, `.afe-answers.json`, `.claude/settings.json` (by `scripts/gen-settings.sh` from `.claude/settings.template.json` and `.claude/settings.project.json`) | their generator only |
+| Project | everything else, including the documentation sections of section 2 and the extension points below | the project |
+
+The project extends the template only at its extension points: checks in `scripts/checks.d/*.sh`,
+run in name order by `scripts/check.sh` and the `docs` workflow, which provision any tool they
+need beyond Git, bash, and Node.js; Stop hooks in `.claude/hooks/project/stop/*.sh`, which
+receive the Stop hook input and block the agent by exiting with 2; its own workflows in
+`.github/workflows/`; its path classes in `.claude/path-classes`; its harness settings in
+`.claude/harness.conf` (the Ralph cap, the identifier pattern, test globs, test commands); and
+its Claude Code settings in `.claude/settings.project.json`. Checks and Stop hooks keep their
+executable bit. Personal settings go into `.claude/settings.local.json`, never committed.

package/template/docs/testing-rules.md

@@ -0,0 +1,80 @@
+# Testing rules
+
+Rules that every test in this repository follows, whatever its language or tools. `AGENTS.md`
+holds the short rules and takes precedence if the two ever disagree. This file comes from the
+project template: report such a disagreement to the template instead of editing it. The project
+adds the levels of its verification ladder (static checks, unit, integration, user journeys),
+tools, commands, thresholds, and the edge cases of its domain in documents the map names, and
+its test checks in `scripts/checks.d/` (`documentation-rules.md`, section 9).
+
+## 1. What a test is for
+
+- A test protects a behaviour that a requirement, an acceptance criterion, a contract, or a fixed
+  defect names. It carries that identifier (`REQ-NNN`, `AC-NN`) in its name or a tag when one
+  applies, so that an `implemented` status and the "Acceptance and test plan" of a pull request can
+  point at it (`documentation-rules.md`, section 3; `contributing.md`, section 3). The project's
+  checks in `scripts/checks.d/` map each identifier to the tests that carry it.
+- Test count and coverage are not goals. Coverage shows which lines ran, not what a test checked:
+  it is a floor the project sets, never evidence of quality. Where the project runs mutation
+  testing, the mutation score is the measure.
+- What the type checker, schema validation, or the contract check already proves (a shape, a
+  required field, a closed set of values) gets no test of its own.
+- One behaviour has one test, or one parametrised test over its table of inputs. A test that
+  catches nothing the other tests miss is removed, and removing it is a valid change.
+
+## 2. How a test proves behaviour
+
+- A test asserts an observable outcome: the returned value or result, the resulting state, or the
+  emitted events, records, and output. An assertion that a mock was called, that a value is
+  defined or truthy, or that nothing threw is not enough on its own.
+- Fakes stand in for the boundaries of the unit under test (external services, storage, the
+  clock, randomness), never for code inside it.
+- Expected values are literals or fixtures. A test never computes its expectation with the logic
+  it tests, and a snapshot is never the only assertion of a rule.
+- Failure paths are tested as deliberately as success: every distinct outcome or error a unit can
+  return has a test that produces it, and every invalid example of a contract is rejected where
+  the input is validated.
+- The edge cases that apply are covered: boundaries, empty and missing values, unknown against
+  zero, duplicates and retries, concurrent use, time zones and period boundaries, and the largest
+  input the requirement allows. The project lists the edge cases of its domain.
+- Tests are deterministic: no sleeps, no real clock, no real network or external service, and no
+  dependence on the order in which tests run.
+
+## 3. Tests and the change they cover
+
+- Tests come first: they are written before the implementation and run once to see them fail for
+  the expected reason. A test that passes before the implementation exists tests nothing.
+- The acceptance tests of a requirement's criteria are written or reviewed by someone other than
+  the author of the implementation, before it exists; the author changes them only with the
+  owner's agreement.
+- The agent derives the test plan from the identifiers the change serves: their cases, failure
+  paths, and edge cases (section 2). It is a report under "Acceptance and test plan"
+  (`contributing.md`, section 3), never approved per pull request and not maintained afterwards.
+  Each new or changed test fails on the base and passes with the change.
+- A defect is fixed only after a regression test that reproduces it fails.
+- A refactoring keeps the tests as they are. A change of behaviour first changes the requirement
+  or the acceptance criterion, then the test that carries the same identifier; the pull request
+  names both.
+
+## 4. Gates
+
+- No test is skipped, focused, or deleted, no assertion is weakened, no code is excluded from
+  coverage, and no threshold is lowered to make a check pass. Such a need is an open question for
+  the owner.
+- The quality measures the project records (coverage, mutation score) never fall below those of
+  the base branch.
+- The configuration of the test runner, coverage, mutation testing, and linters is class gate in
+  `.claude/path-classes` (`documentation-rules.md`, section 8): it changes without a prompt, the
+  pull request lists it under "Gate files", which the readiness check enforces, and the owner
+  reviews it after the merge.
+- An invariant that must hold everywhere (for example, a secret never appears in output) is an
+  executable check, a test or a project check, and the register `docs/invariants.md` names it
+  with that check (`documentation-rules.md`, section 2); its invariants are criteria of the
+  review of class high (`contributing.md`, section 6).
+- Threat model of development gates: a gate (a lint rule, a test check, a coverage or mutation
+  setting, an agent hook) catches honest mistakes and shortcuts; it is not a security boundary.
+  It decides which bypass is a `blocker` (`contributing.md`, section 6): a diff that itself
+  loosens or evades a gate (a test skipped, an assertion weakened, a threshold lowered, a test
+  behind an aliased import), and any bypass of a product invariant (security, secrets, policy
+  enforcement, limits), whatever it takes. A gap that only deliberate evasion exploits, such as
+  a computed property or tampering with a gate's own state, is a `suggestion`.