create-afe-project 0.0.0-stage → 2.0.0

package/template/docs/contributing.md.jinja

@@ -0,0 +1,206 @@
+# Contribution rules
+
+Branches, commits, pull requests, when a change is done, template updates, and review.
+`AGENTS.md` takes precedence; this file comes from the template, so report a disagreement there.
+Everything written into git history and pull requests is in English, without exception.
+
+## 1. Branches
+
+- `main` on the remote `origin` (`git remote set-head origin -a`) is the only long-lived branch
+  and the base of every pull request; nothing but the template's initial commit goes to it directly.
+- A working branch is named `<type>/<slug>`: `docs` for documentation, decisions, requirements,
+  and plans; `ci` for checks, hooks, workflows, and skills; `feat` for new behaviour; `fix` for a
+  defect; `chore` for tooling and housekeeping. The slug names the change in two to five
+  lowercase words joined by `-`, such as `ci/check-script-timeout`; no ticket numbers.
+- One branch carries one logical change and ends in one pull request: one mechanism with its
+  tests and the owner documents it changes (one check, one hook, one rule, one behaviour). A rule
+  change and the first code that follows it are two changes (`AGENTS.md`, section 5); readiness
+  warns above `DIFF_WARN_LINES` changed lines. An exception needs the owner's instruction, named
+  under "Notes for the owner".
+- Each parallel session works in its own git worktree (`git worktree add`) on its own branch. A
+  session that stops unfinished leaves a checkpoint: its commits pushed, and its progress and
+  blockers in the plan or the pull request description, where the next session starts.
+- A branch that a tool named otherwise (`claude/<name>`) is renamed before its first push; a
+  pushed one keeps its name, noted under "Notes for the owner". After the merge GitHub deletes it, a repository
+  setting that `scripts/protect-branch.sh` applies.
+
+## 2. Commits
+
+- The subject line is `<Scope>: <summary>`, at most 72 characters.
+  - `Scope` names what the commit changes, as it is written elsewhere: an owner document or its
+    area (`Requirements`, `Rules`, `Map`, `Plan`, `Contributing`), a decision (`ADR-0001`), a
+    workflow or skill (`create-pr`). Several scopes are separated by commas.
+  - `summary` states what the commit does or what is now true, in the present tense, lowercase,
+    without a trailing period: `apply review fixes`, `requirements section now exists`.
+- The body, after a blank line and wrapped at 72 characters, says why when the subject does not,
+  and names the documents affected, the statuses changed and who set them, and related pull
+  requests (`PR #2`). It never calls something implemented without a test.
+- One commit per logical change. Work-in-progress and fix-up commits are squashed before the
+  branch is pushed. A follow-up that answers review is its own commit.
+- A commit authored by an agent ends with the co-author trailer its tool prescribes; for Claude
+  Code, a `Co-Authored-By:` line naming the model.
+
+## 3. Pull requests and done
+
+- One pull request per branch, against `main`; a draft while the work is unfinished or a check
+  other than merge readiness fails. The title is the branch's commit subject, or one subject in
+  the same form for several commits.
+- The description is the report of `AGENTS.md`, section 6: the evidence that the change is done.
+  It has these sections in this order; "Owner decisions" and "Gate files" appear when they have
+  an item, "Notes for the owner" is optional, and an empty section reads "None".
+
+```markdown
+## Summary
+
+- What changed and why, one bullet per owner document or area, naming the files; each new
+  statement with its status (`proposed`, `accepted by the owner`, `implemented` with its test).
+
+## Acceptance and test plan
+
+- One bullet per identifier the change serves (`REQ-NNN`, `AC-NN`, or an identifier in the owner
+  document of a check): its cases, the test files in backticks and the tests that carry it, and
+  the evidence: failed on the base and why, passes now. "None: <reason>" for no behaviour change.
+
+## Checks
+
+- `scripts/check.sh` passes; or, for each failing part, the command and the lines of its output
+  that show the failure, so that the next session can resume from them.
+- Semantic self-review (`docs/documentation-rules.md`, section 7): what was checked, the result.
+- The review before the pull request (section 6): its reviewers and their models, or why none.
+
+## Assumptions and open questions
+
+- None, or one bullet each, labelled `blocking:`, `recorded:`, `assumption:`, or `limit:`.
+
+## Owner decisions
+
+- Each `Decided by the owner` marker the branch adds: the file, the statement, and the owner's
+  instruction, quoted with its date.
+
+## Gate files
+
+- Each file of class gate the branch touches, as `scripts/check-decisions.sh --ready` lists them.
+
+## Metrics
+
+| Sensor | Class | Found | Fixed | Limit | Declined |
+| --- | --- | --- | --- | --- | --- |
+| check.sh | blocker | 0 | 0 | 0 | 0 |
+
+| Measure | Value |
+| --- | --- |
+| First check.sh | pass |
+| Ralph iterations | 1 |
+| Santa rounds | 0 |
+| Owner interventions | 0 |
+| Files outside the scope | 0 |
+| Regression of | none |
+
+## Notes for the owner
+
+- Optional: protected files touched and the instruction that allowed it, alternatives not taken.
+```
+
+- An agent's pull request ends with the attribution line its tool prescribes; for Claude Code,
+  `🤖 Generated with [Claude Code](https://claude.com/claude-code)`.
+- The labels of "Assumptions and open questions":
+  - `blocking:` a question about the pull request itself (its content, a status, a decision it
+    needs), resolved before the merge. A review finding is one only in a Santa loop (section 6).
+  - `recorded:` a question about the subject matter, kept with an identifier in its owner
+    document, which the item names (`recorded: OQ-1 in docs/requirements/<document>.md`).
+  - `assumption:` an assumption the change rests on, also labelled where it is used.
+  - `limit:` a suggestion of a review that the branch does not fix, with its sensor and reason;
+    for a check, its owner document now names the forms it catches. The merge accepts it.
+- A change is done when each identifier it serves has a test that carries it, each new or changed
+  test failed on the base and passes now, `scripts/check.sh` passes and no measure the project
+  records falls below the base, no `blocker` is open, and the readiness check passes. The agent
+  derives the test plan from the identifiers (`testing-rules.md`, section 3); it is a report,
+  never approved per pull request and not maintained afterwards.{% if acceptance_check %} `scripts/check-acceptance.sh`
+  checks the first condition by identifier.{% endif %}{% if fail_without_change %} `scripts/fail-without-change.sh` checks per file that each
+  new or changed test passes with the change and fails on the base; `tests-pass-on-base` allows a pass.{% endif %}
+- Ralph loop: the author runs `scripts/check.sh`, fixes, and runs it again until it passes, at
+  most `RALPH_MAX_ITERATIONS` runs (`.claude/harness.conf`, default 5). At the cap the author
+  stops and reports the failing command and its output. Metrics count the runs.
+- An agent writes a `Decided by the owner` marker only on the owner's instruction and lists each
+  one it adds under "Owner decisions"; the owner's merge confirms them.
+- Metrics measure the sensors, so that a rule or check that never fires is removed;
+  `scripts/pr-metrics.sh` aggregates merged pull requests, with the time to merge. A sensor is a
+  check or a reviewer; an owner intervention is anything the owner answered, approved, or
+  corrected besides the merge; "Regression of" names the pull request whose behaviour this repairs.
+- Ready to merge: `scripts/check-decisions.sh --ready` and every other check pass, no `blocker`
+  is open, every finding is answered. Readiness fails on a missing "Acceptance and test plan" or
+  "Metrics" section, a missing or repeated measure; an added record still `proposed`; an
+  open `blocking:` item or one without a label; an Acceptance item that is neither "None" with a
+  reason nor names an existing path in backticks; an added marker in a Markdown file or a touched
+  gate file that its section does not name; a Metrics table outside its forms, whose answers do
+  not add up, or with a blocker as a limit.{% if acceptance_check %} It runs `scripts/check-acceptance.sh` too.{% endif %} Whether a test proves
+  its identifier is left to the review. The `decisions` workflow runs it on every change, on the records
+  only for a pull request that `github-actions[bot]` opened, and does not block; one waiting only on the owner stays open as "not ready to merge".
+- The owner merges with a merge commit; `scripts/protect-branch.sh` allows no other merge method.
+
+## 4. Before opening a pull request
+
+Sections 1 to 3 hold, the checks pass or their failures are stated, and every affected owner
+document is updated in the same branch. The `create-pr` skill runs this and opens it.
+
+## 5. Template updates
+
+The template-owned files (`documentation-rules.md`, section 9) change only through an update to a
+template version, which `.afe-answers.json` records; the `update-template` skill runs it:
+
+1. From an up-to-date `main`, on the branch `chore/template-update`: `npx create-afe-project@latest
+   update --defaults`, or `@<version>`. It replaces the template-owned files, keeps the project
+   block of `AGENTS.md`, never changes an existing seeded file, and regenerates generated files.
+2. Review its report: a replaced local edit of a template-owned file is lost unless it moves to
+   the template; project files are untouched. An update changes seeded files only by a migration
+   the changelog names.
+3. `scripts/check.sh`, then a pull request `Template: update to <version>` with the changelog
+   entries since the previous version under "Summary". A change the project needs in a
+   template-owned file is made in the template first.
+
+## 6. Review of pull requests
+
+- AI review is a sensor, not a gate: the checks decide by themselves, and a reviewer judges what
+  they cannot. Reviewers propose; the owner decides. The review follows the highest class of the
+  changed paths (`documentation-rules.md`, section 8), as `scripts/check-decisions.sh --classes`
+  prints it. Before the pull request the {% if dual_review %}`dual-review`{% else %}`create-pr`{% endif %} skill runs it:
+  - low (documents, generated files, a template update): no reviewer;
+  - normal and gate: one pass by one reviewer, {% if dual_review %}the Codex CLI when it is installed, otherwise {% endif %}a fresh
+    Claude subagent; only the fix of a blocker is checked again;
+{%- if dual_review %}
+  - high: the Santa loop: a Claude subagent and the Codex CLI (without Codex, a second fresh
+    Claude subagent with another lens) review independently; the author fixes the blockers and both
+    review again, until neither finds one or after `REVIEW_MAX_ROUNDS` rounds (`.claude/harness.conf`,
+    3 to 5): the open blockers go to the owner as `blocking:` items.
+{%- else %}
+  - high: one pass as for normal; the Santa loop is an optional module of the template.
+{%- endif %}
+{%- if docs_review or code_review %}
+- In the pull request, {% if docs_review %}`docs-review` reviews every pull request{% endif %}{% if docs_review and code_review %} and {% endif %}{% if code_review %}`code-review` every one that changes code, contracts, checks, or workflows{% endif %}, once, when it
+  opens or leaves draft, except one that `github-actions[bot]` opened; a push does not run {% if docs_review and code_review %}them{% else %}it{% endif %} again.
+{%- endif %}
+- A finding names a file, a line, a class, and the rule it rests on; zero findings is valid, and
+  style belongs to the linters. A `blocker`: merged as it is, the change breaks behaviour, a
+  contract, security, or a product invariant (`docs/invariants.md`), loses data, fails an item of
+  its Acceptance section, or contradicts a higher source (`AGENTS.md`, section 1). Which bypass of
+  a gate is a blocker follows `testing-rules.md`, section 4. Any other finding is a `suggestion`.
+- Each finding is answered once. A blocker is fixed, and the fix checked once more by a fresh
+  reviewer given the blocker and the fix, or declined with a reason. A suggestion never drives
+  a loop: it is fixed at once, recorded as `limit:` (section 3), or declined with a reason.
+- The project adds its own criteria in one owner document that the map names under "Review
+  criteria"; every reviewer applies both.
+
+| Criterion | Passes when |
+| --- | --- |
+| Authority | every behaviour serves a named requirement or criterion, or is an open question; nothing is invented (`AGENTS.md`, section 4) |
+| Co-change | contract, code, tests, and owner document change together; a breaking contract change is versioned; generated files are regenerated |
+| Correctness | the logic does what the requirement says, with the edge cases that apply |
+| Tests | the tests follow `docs/testing-rules.md`, and every identifier of "Acceptance and test plan" has a test that carries it and fails without the change |
+| Errors | no error is swallowed, no failure hides behind a default |
+| Security | external input is validated where it enters; secrets never reach code, logs, or output |
+| Dependencies | a new dependency exists in its registry under the name used, is maintained, has a license the project allows (an open question while no document says which), and does no job an existing dependency already does; its version is pinned exactly, through the lock file where the stack has one |
+| Statuses | nothing is called implemented without a test (`documentation-rules.md`, section 3) |
+
+- A defect found after the merge is fixed after a regression test; its pull request gives the
+  evidence pack (the reproduction, the root cause, the regression test failing then passing) and
+  names what keeps the next one out: a criterion, a check, a rule, or why none fits.

package/template/docs/decisions/adr-template.md

@@ -0,0 +1,38 @@
+---
+status: proposed
+date: YYYY-MM-DD
+decision-makers: {who decides}
+scope: {stack | architecture | data | security | operations | process}
+summary: "In the context of {situation}, facing {concern}, we decided {chosen option} and rejected {alternatives}, to achieve {quality}, accepting {downside}."
+supersedes: []
+---
+
+# {the decision as a short statement}
+
+## Context and Problem Statement
+
+{Two to five sentences, or a question: the problem, the forces, and the scope of the decision.
+Link the requirements and documents involved instead of copying them. Only for a decision that
+meets `docs/documentation-rules.md`, section 5; keep the whole record to about one page.}
+
+## Considered Options
+
+* {chosen option}
+* {real alternative}
+
+## Decision Outcome
+
+Chosen option: "{chosen option}", because {justification}. {Rules, parameters, and design details
+belong in their owner document; link it here instead of listing them.}
+
+Rejected: {each alternative, with the reason in one clause}.
+
+### Consequences
+
+* Good, because {positive consequence}
+* Bad, because {negative consequence}
+
+### Confirmation
+
+{The check that verifies the decision: a script, a test, a contract check, or a review step. Or
+"Not checked yet:" followed by what will check it and when.}

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; front matter as for architecture |
+| Conventions and recipes | `docs/conventions/<area>.md`, `docs/recipes/<task>.md` | conventions: reference, the rules of one area that the code does not make obvious, each naming the lint rule or check that enforces it, or `none` when only the review does; component boundaries and dependency rules stay in architecture; recipes: how-to, the steps of one repeated development task, each naming the command or file it relies on, while running the system stays in operations; a tool-specific rule file or skill links to them and never holds its own copy; front matter as for architecture |
+
+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, conventions, recipes | `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>`, or `none` while no code
+exists, the last review against code: architecture, operations, conventions, and recipes carry it.
+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.
+- The documents of section 4 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 | the SessionStart hook flags each plan past its `review-by` (section 5), with the branch, its base, and the uncommitted files | `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; in Claude Code, `CHECK_FAST` of `.claude/harness.conf` at a Stop when a file other than Markdown differs from the base, skipped when empty or the default `scripts/check-docs.sh` | as the project defines; what `CHECK_FAST` leaves out waits for `scripts/check.sh` |
+| 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 hooks in Claude Code: the documentation, decision, and template checks, `CHECK_FAST`, and the project's Stop hooks; a failing check blocks up to the Ralph cap (`contributing.md`, section 3) | none; the full `scripts/check.sh` runs before the pull request and in CI |
+| 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; every invalid contract example is rejected where 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, network, or external service, no dependence on
+  test order. A flaky test teaches that red can be ignored: it is fixed, never retried or rerun
+  until green; skipping it is a blocker of section 4 unless the owner, asked, decides otherwise.
+
+## 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`.