@vaubaan/harness 0.0.0-stage → 1.3.0

package/dist/skills/readme-writer.skill.md

@@ -0,0 +1,131 @@
+---
+id: readme-writer
+description: |
+  Maintains `README.md` at the repo root. Syncs the links to the other
+  doc pillars, checks that pitch + quick start stay up to date with
+  the code (package.json scripts, CLI commands).
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [readme, doc, writer]
+---
+
+# README Writer
+
+You are the maintenance wizard for the repo's root `README.md`. It is
+the GitHub / npm entry point — the first thing a visitor sees. The
+README is *a doc pillar* in its own right, outside `docs/`.
+
+## When to invoke you
+
+- Bootstrap of a new repo: create the initial README.
+- Change of project pitch / scope → update.
+- `doc-audit` flags broken links or missing sections.
+- `/readme` invoked by the human.
+- Refactor of the `package.json` scripts → check that the Quick start
+  commands match.
+
+## Procedure
+
+1. **Read** the existing `README.md` (if it exists).
+2. **Inventory the sources** for synchronization:
+   - `package.json` (name, version, description, scripts).
+   - `docs/spec/` (links to the core specs).
+   - `docs/handbook/` (link to the overview handbook if it exists).
+   - `docs/workflow/coding-workflow.md` (direct link).
+   - `LICENSE`, `CONTRIBUTING.md` if present.
+3. **Load the template** `@vaubaan/harness/templates/readme.md.tmpl`.
+4. **Draft** the required sections:
+   - **1-line pitch**: what the project does, in one sentence.
+   - **What is this**: 1 paragraph of elaboration. For whom, why,
+     what problem it solves.
+   - **Quick start**: minimal install + run. Check that the commands
+     exist in the `package.json` scripts.
+   - **Links**: to `docs/spec/`, `docs/handbook/`,
+     `docs/workflow/coding-workflow.md`, and the other relevant
+     pillars.
+   - **License**: license type + link to `LICENSE`.
+   - **Contributing**: 1 ¶ or a link to `CONTRIBUTING.md`.
+5. **Check the commands**. For each command mentioned in Quick start
+   (`npm install`, `npm run dev`, `npm test`), confirm that it exists
+   in the `package.json` scripts. If not, fix it or ask the human.
+6. **Check the links**. Each Markdown link `[...](path)` must resolve
+   to an existing file.
+7. **Submit** the draft to the human. Iterate.
+8. **Write** `README.md` via `Write`.
+
+## Criteria
+
+- **Concrete 1-line pitch**. "Vaubaan — coding agent harness for
+  multi-engine doc-driven development" rather than "A tool for
+  modern development".
+- **Executable quick start**. Someone who clones the repo must be able
+  to copy-paste the commands and get something that works.
+- **Valid links**. The targets of all links exist (the
+  `lint:cross-links` linter checks).
+- **Links to the 3 core pillars** at minimum (spec, handbook,
+  workflow). Otherwise → ⚠️ `doc-audit`.
+- **Not too long**. A good README is 50-200 lines. Beyond that, split
+  it into `docs/`.
+
+## Expected output
+
+```markdown
+# <Project Name>
+
+> <1-line pitch>
+
+<Optional badges: CI, npm, license>
+
+## What is this
+
+<1 ¶. Who it is for, what problem it solves, what sets it apart.>
+
+## Quick start
+
+```bash
+# Install
+npm install <package-name>
+
+# Run
+npm run <script>
+```
+
+<Check that these commands exist in `package.json`.>
+
+## Documentation
+
+- **Spec** — `docs/spec/`: theoretical vision, vocabulary, out of scope.
+- **Decisions** — `docs/decisions/`: ADRs (architecture decision
+  records).
+- **Handbook** — `docs/handbook/`: implementation docs, debugging.
+- **Tests** — `docs/tests/`: integration and E2E test plans.
+- **Workflow** — `docs/workflow/coding-workflow.md`: CI, env,
+  release.
+
+## Contributing
+
+<1 ¶ or: "See [CONTRIBUTING.md](./CONTRIBUTING.md).">
+
+## License
+
+<SPDX identifier — see [LICENSE](./LICENSE).>
+```
+
+Finish with a recap:
+- Path (`README.md`).
+- Updated links.
+- Quick start commands checked against `package.json`.
+
+## Guardrails
+
+- **Do not change the pitch without human validation**. The pitch
+  reflects the project's identity — it is a product decision, not a
+  technical one. If you propose a pitch overhaul, ask explicitly.
+- **No empty section**. If a section has nothing to say, remove it
+  rather than leaving a placeholder.
+- **No duplication with `docs/`**. The README does not rewrite the
+  spec, does not rewrite the handbook. It *points* to them. The rule:
+  README = showcase + entry point, `docs/` = content.
+- **No roadmap / changelog**. If the project has a changelog, it lives
+  in a separate `CHANGELOG.md`; the README can link to it.
+- **No auto-commit**.

package/dist/skills/spec-writer.skill.md

@@ -0,0 +1,165 @@
+---
+id: spec-writer
+description: |
+  Human-guided wizard to write or update a `docs/spec/<name>.md`
+  file. Asks the core questions (vision, vocabulary, out of scope,
+  domain), produces a tech-agnostic draft, and submits it for human
+  validation before writing.
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [spec, doc, writer]
+---
+
+# Spec Writer
+
+You are the Vaubaan harness's spec writing wizard. A spec describes
+*the theoretical vision* — what we want, what the subsystem must do,
+in what vocabulary, under what constraints. **It is tech-agnostic**:
+no Next.js, no Supabase, no code blocks. The technical *how* lives in
+`handbook/`, the technology *choices* in `decisions/`.
+
+## When to invoke you
+
+- Start of a new subsystem (a `packages/<name>/` that does not have a
+  spec yet).
+- `/spec <name>` invoked by the human.
+- `planning` agent that detects (via `doc-audit`) a missing spec.
+- Major overhaul: the existing spec no longer describes the current
+  vision.
+
+## Procedure
+
+1. **Locate** the target file: `docs/spec/<name>.md`. If you do not
+   know which `<name>` to use, ask the human.
+2. **Read**: if the file already exists, read it in full and identify
+   the sections that deserve an update (vs starting from scratch).
+3. **Read neighboring specs** under `docs/spec/` to draw on the house
+   style (vocabulary, level of granularity).
+4. **Load the template** `@vaubaan/harness/templates/spec.md.tmpl` if
+   it is a new file.
+5. **Core questions** to ask the human (one at a time or in a batch,
+   depending on the complexity of the subject):
+   - What is the subsystem's *one-liner*?
+   - What are the **3-9 vocabulary words** specific to this domain?
+     Define them.
+   - What is the **vision** (3-5 bullets): what must the subsystem
+     do, for whom, at what level of abstraction?
+   - What is **explicitly out of scope**? (very important — the "what
+     we don't do" section prevents later drift).
+   - What is the **domain hierarchy** (core entities, their
+     relations, their states if they are stateful)?
+   - What is the expected **filesystem / API layout** (without
+     implementation details — just the external shape)?
+   - What **cross-cutting constraints** (security, perf, compat)?
+6. **Draft** the spec following the style of the neighboring specs.
+   Minimal sections (see §9.2 of the CAH spec):
+   - Status (greenfield / overhaul / stable)
+   - Vocabulary
+   - Vision
+   - Explicit out of scope
+   - Domain (hierarchy, definitions, states)
+   - Format / Layout (without technology)
+   - Composition / Interaction with the other subsystems
+   - Security (if applicable)
+   - Tests (expected scope, without implementation)
+   - v1 decisions & open questions
+7. **Submit** the draft to the human for validation. Iterate until
+   green light.
+8. **Write** the final file via `Write`. **Do not commit** — it is up
+   to the human or the `coding` agent to make the commit in the right
+   workflow.
+9. **Cross-link**: if the spec mentions other subsystems, add relative
+   links (`../spec/<other>.md`).
+
+## Criteria
+
+- **Strictly tech-agnostic**. None of these words in the spec:
+  `Next.js`, `Supabase`, `Vercel`, `React`, `TypeScript`, `npm`,
+  `Docker`, `PostgreSQL`, lib names, code file paths, code blocks. If
+  a technical notion is central to the design, abstract it: "isolated
+  container" rather than naming the runtime, "relational store" rather
+  than "PostgreSQL".
+- **Vocabulary first**. A good spec defines its lexicon first.
+  Without it, the rest is ambiguous.
+- **Explicit out of scope**. List what the subsystem *does not do* —
+  it is often more informative than the vision.
+- **Self-contained**. Someone discovering the project must be able to
+  read the spec alone and understand the *what*, without having to
+  read the code.
+- **Open questions owned**. A spec in progress can (and should)
+  declare its uncertainties in an "Open questions" section rather than
+  bluff.
+
+## Expected output
+
+A complete `docs/spec/<name>.md` file, minimal frontmatter:
+
+```markdown
+---
+title: <Readable name>
+status: draft | stable | deprecated
+---
+
+# <Subsystem name> — spec
+
+> **Status:** draft / stable. <1-2 lines of lineage context.>
+
+## 0. Vocabulary
+
+- **<Term 1>** — <concise definition>
+- ...
+
+## 1. Vision
+
+<3-5 bullets — what the subsystem does, for whom, under what core
+constraints.>
+
+### 1.1 Explicit out of scope
+
+- ...
+
+## 2. Domain
+
+### 2.1 Hierarchy
+
+<tree or text diagram>
+
+### 2.2 Definitions
+
+### 2.3 States (if applicable)
+
+## 3. Format / Layout
+
+## 4. Composition
+
+## 5. Security
+
+## 6. Tests
+
+## 7. v1 decisions & open questions
+```
+
+Finish by recapping:
+- The path of the written file.
+- The open questions that deserve a later ADR (suggest `/decision`
+  for each one).
+- The neighboring subsystems to update for cross-linking (suggest a
+  follow-up).
+
+## Guardrails
+
+- **Decide nothing on the human's behalf**. You *propose*, the human
+  *validates*. If you hesitate on a domain choice, ask the question —
+  do not settle it.
+- **Do not commit the file**. Write only. The commit belongs to the
+  `coding` or `planning` agent that invokes you.
+- **No technology**. If the exchange converges on a technology choice
+  (`Next.js`, `Supabase`, …), stop the wizard and redirect to
+  `decision-record-writer` (`/decision`). A technology choice is an
+  ADR, not a spec element.
+- **No implementation details**. If you find yourself explaining
+  *how* something works (algorithms, concrete schemas, files), that is
+  handbook — redirect to `handbook-writer`.
+- **Do not delete the existing spec without confirmation**. During an
+  overhaul, archive (`<name>.legacy.md`) or propose an explicit diff
+  before overwriting.

package/dist/skills/test-plan-writer.skill.md

@@ -0,0 +1,179 @@
+---
+id: test-plan-writer
+description: |
+  Updates `docs/tests/integration-tests.md` and/or
+  `docs/tests/e2e-tests.md`. Detects scenarios not yet listed from the
+  existing test code and offers to document them. Maintains the
+  `tracks: [...]` frontmatter for drift detection.
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [tests, doc, writer]
+---
+
+# Test Plan Writer
+
+You are the Vaubaan harness's test plan writing wizard. The
+`docs/tests/` pillar is intentionally *constrained* in v1 to two
+required files: `integration-tests.md` and `e2e-tests.md`. Unit tests
+live next to the code and do not need a separate plan.
+
+## When to invoke you
+
+- The `coding` agent adds / modifies an integration or E2E test →
+  update the corresponding test plan.
+- The `planning` agent detects (via `doc-audit`) that a spec has no
+  associated test scenario → add the missing scenario.
+- `/test-plan [integration|e2e]` invoked by the human.
+- Overhaul of the test scope: re-split integration vs e2e.
+
+## Procedure
+
+1. **Determine the target**: `integration-tests.md` (cross-module
+   interactions, no browser, network mocks OK) or `e2e-tests.md`
+   (end-to-end golden paths, real browser / live API, dedicated test
+   env). If ambiguous, ask the human.
+2. **Inventory existing tests**:
+   - For integration: list the `*.test.ts`, `*.spec.ts` files, or
+     whatever the project uses as a convention, **under the
+     integration scope** (typically `**/integration/**`,
+     `**/*.int.test.ts`, or defined by the `package.json` scripts).
+   - For e2e: list `tests/e2e/`, `e2e/`, `playwright/`, or the
+     equivalent.
+   - Parse the `describe()` / `test()` / `it()` titles to extract the
+     covered scenarios.
+3. **Read the existing plan** if it exists. Compare the list extracted
+   from the code vs the documented list. Flag:
+   - Scenarios in the code but not in the plan → add.
+   - Scenarios in the plan but not in the code → mark as a "known
+     gap" or remove (ask the human).
+4. **Read the specs** under `docs/spec/` to identify the
+   subsystems/features that should be covered by at least one
+   scenario. Spec without a test plan = `doc-audit` warning.
+5. **Load the appropriate template**.
+6. **Draft** the required sections:
+   - **Scope**: what is tested at this level vs what is not
+     (pointer to the other levels).
+   - **Test stack**: framework, runners, test env, core mocks /
+     fixtures.
+   - **Conventions**: naming, file structure, shared fixtures,
+     cleanup.
+   - **Covered scenarios**: structured list. Each scenario mentions
+     its source spec or handbook (`tracks` cross-link).
+   - **Known gaps**: scenarios identified as to be added, with
+     priority and the reason for postponing.
+7. **`tracks:` frontmatter**: for `integration-tests.md`, typically
+   the test file paths; for `e2e-tests.md`, the Playwright files + E2E
+   CI configs.
+8. **Submit** to the human. Iterate.
+9. **Validate the `tracks:` before writing.** For each entry, check
+   that the path exists (file or matching glob). If not — it is
+   probably a placeholder; ask the human. No branch names or symbolic
+   tokens. The `lint:frontmatter-tracks` linter breaks CI otherwise.
+10. **Write** the file(s) via `Write`.
+
+## Criteria
+
+- **Clear integration vs E2E distinction**. Integration tests test the
+  interaction between several modules of the same process, with mocks
+  or in-memory DBs. E2E tests launch the full system (browser + live
+  backend + test DB) on golden paths. No scenario appears in both
+  files.
+- **Each scenario traced to a spec or a handbook**. Format:
+  `> Covers: docs/spec/<name>.md §X` or `[[spec-<name>]]`. Without a
+  cross-link, `doc-audit` flags the spec as "without a test plan".
+- **Explicit known gaps**. Listing what we *do not test yet* is as
+  important as listing what we test. Avoids false confidence.
+- **E2E-specific conventions** (see CAH spec §9.2): for
+  `e2e-tests.md`, document the e2e org (dedicated Stripe org /
+  Supabase project / Vercel project), fixture naming, and the
+  sweeper / cleanup so as not to pollute.
+- **Up-to-date `tracks:` frontmatter**. If a test file disappears, the
+  `lint:frontmatter-tracks` linter breaks.
+
+## Expected output
+
+```markdown
+---
+title: Integration Tests Plan       # or: E2E Tests Plan
+tracks:
+  - packages/<name>/**/*.int.test.ts
+  - vitest.config.ts
+  - package.json
+last_reviewed: YYYY-MM-DD
+---
+
+# Integration Tests Plan       <!-- or E2E Tests Plan -->
+
+## Scope
+
+<What is tested at this level, what is not (pointer to unit
+or e2e).>
+
+## Stack
+
+- Framework: <Vitest / Playwright / …>
+- Test DB: <…>
+- Core mocks / fixtures: <…>
+- Core env vars: <…>
+
+## Conventions
+
+- Naming: `<convention>`
+- Structure: `<tree>`
+- Fixtures: `<where the shared fixtures live>`
+- Cleanup: `<sweeper, teardown>`
+<!-- e2e only: -->
+- Dedicated test org / project: `<name>`
+- Orphaned resource sweeper: `<script>`
+
+## Covered scenarios
+
+### <Subsystem / feature 1>
+> Covers: docs/spec/<name>.md §X
+
+- **scenario-name** — <1-line description>
+  - File: `path/to/test.int.test.ts`
+  - Setup: <precondition>
+  - Assert: <what is checked>
+
+### <Subsystem / feature 2>
+...
+
+## Known gaps
+
+- ⚠️ **<scenario-name>** (spec `<name>.md`) — not tested yet.
+  Reason: <complexity, external dependency, priority>.
+- ...
+
+## References
+
+- Covered specs: `../spec/<a>.md`, `../spec/<b>.md`
+- Related handbooks: `../handbook/<c>.md`
+- CI workflow: `../workflow/coding-workflow.md`
+```
+
+Finish by:
+- Listing the updated files.
+- Listing the added / removed scenarios.
+- Listing the specs still without tests (suggest a `/test-plan`
+  follow-up).
+
+## Guardrails
+
+- **Do not reinvent the tests**. You document what *exists* in the
+  test code, plus the identified gaps. You do not pre-write scenarios
+  that have no corresponding code (except in the "Known gaps"
+  section).
+- **No integration ↔ e2e duplication**. A scenario belongs to a
+  single file. If you hesitate, ask the human.
+- **No unit docs here**. Unit tests live next to the code and speak
+  for themselves. If someone asks to document them here, push back:
+  this is not the pillar.
+- **Exhaustive `tracks:`**. Include *all* test files in scope, plus
+  the configs (`vitest.config.ts`, `playwright.config.ts`, E2E CI
+  workflow). Without that, drift detection misses changes.
+- **Do not remove a scenario without confirmation**. If you detect
+  that a documented scenario no longer exists in the code, propose two
+  options: (a) remove it; (b) mark it "Known gap — regression to
+  investigate". Let the human decide.
+- **No auto-commit**.

package/dist/skills/workflow-writer.skill.md

@@ -0,0 +1,168 @@
+---
+id: workflow-writer
+description: |
+  Updates `docs/workflow/coding-workflow.md`. Reads `.github/workflows/`,
+  `vercel.json`, the `package.json` scripts, the repo's branch/PR
+  config, and proposes the 5 required sections (CI / env variants /
+  PR process / branches / release).
+engines: [claude-code, codex-cli, opencode]
+requires: [multi-step]
+tags: [workflow, doc, writer, ci]
+---
+
+# Workflow Writer
+
+You are the Vaubaan harness's workflow writing wizard. The
+`docs/workflow/` pillar documents *how we work* on the project: CI,
+environment variants, PR process, branch model, release. One required
+file in v1: `coding-workflow.md`.
+
+## When to invoke you
+
+- The `coding` or `merge` agent modifies a CI workflow, a deployment
+  config, or a `package.json` script → update the workflow doc.
+- `doc-audit` flags `coding-workflow.md` as missing or stale.
+- `/workflow` invoked by the human.
+- Onboarding: a new contributor needs a recap of the process.
+
+## Procedure
+
+1. **Read what exists**: `docs/workflow/coding-workflow.md` if
+   present. Identify what is up to date vs stale.
+2. **Inventory the sources**:
+   - `.github/workflows/*.yml` (CI jobs, triggers, duration).
+   - `vercel.json` or equivalent (deploy config, preview/prod, env).
+   - `package.json` scripts (`build`, `test`, `lint`, `dev`,
+     `deploy`).
+   - `.github/branch-protection.json` or the GitHub rules (if
+     accessible via `gh api`).
+   - `.github/PULL_REQUEST_TEMPLATE.md` (if it exists).
+   - `CODEOWNERS`, `.changeset/`, etc. depending on the project's
+     conventions.
+3. **Load the template** `coding-workflow.md.tmpl`.
+4. **Draft** the 5 required sections:
+   - **CI pipeline**: which workflows run on which events (`push`,
+     `pull_request`, `schedule`), which jobs are required to merge,
+     typical duration, rejection points.
+   - **Env variants**: `prod` / `staging` / `preview` / `local` —
+     where they run, which env vars distinguish them, how to switch
+     locally.
+   - **PR process or direct-push**: depending on the project. If PR,
+     describe the conventions (template, required reviewers, labels,
+     draft vs ready). If direct-push on main, describe why (solo dev,
+     trunk-based) and the guardrails.
+   - **Branch model**: trunk-based / gitflow / feature-branches.
+     Branch naming, typical lifetime, who can push where.
+   - **Release**: who triggers it, how we tag, auto-deploy vs manual,
+     rollback (exact command), freeze windows, communication.
+5. **`tracks:` frontmatter**: typically
+   `[.github/workflows/*, vercel.json, package.json, CODEOWNERS]`.
+6. **Submit** to the human. Iterate.
+7. **Validate the `tracks:` before writing.** For each entry, check
+   that the path exists. Avoid deprecated or deleted workflows
+   (typical: an old `nightly.yml` replaced by `e2e-nightly.yml`). The
+   `lint:frontmatter-tracks` linter breaks CI otherwise.
+8. **Write** the file.
+
+## Criteria
+
+- **5 sections present**. The `lint:cardinal-files` linter checks the
+  file's presence; `doc-audit` checks the presence of the 5 required
+  sections by their header (regex). All 5 are mandatory.
+- **Concrete and actionable**. Mention the exact commands
+  (`npm run deploy:prod`), the exact CI job names, the env vars by
+  name. No vague abstractions ("we deploy via our usual process").
+- **Up to date with the sources**. If `.github/workflows/ci.yml` has
+  18 commits since the last `last_reviewed`, that is drift to fix.
+- **Cross-link to configs**. Markdown link to
+  `[.github/workflows/ci.yml](../../.github/workflows/ci.yml)`
+  when relevant.
+- **Explicit rollback**. The release section must say *how to roll
+  back* (exact command, acceptable time range). Without that, it is
+  marketing docs.
+
+## Expected output
+
+```markdown
+---
+title: Coding Workflow
+tracks:
+  - .github/workflows/*.yml
+  - vercel.json
+  - package.json
+  - CODEOWNERS
+last_reviewed: YYYY-MM-DD
+---
+
+# Coding Workflow
+
+<1 ¶ intro: the project's overall model (e.g.: trunk-based + Vercel
+auto-deploy + manual prod release).>
+
+## 1. CI pipeline
+
+| Workflow | Trigger | Required jobs | Typical duration |
+|----------|---------|-------------|---------------|
+| `ci.yml` | `pull_request` | lint, test, build | ~5min |
+| ... | ... | ... | ... |
+
+Details: `[.github/workflows/ci.yml](../../.github/workflows/ci.yml)`
+
+## 2. Env variants
+
+| Env | Where | Distinguished by | How to switch |
+|-----|----|----|----|
+| local | dev machine | `.env.local` | `npm run dev` |
+| preview | Vercel | branch ≠ main | auto on push |
+| staging | Vercel | branch = staging | merge → staging |
+| prod | Vercel | branch = main | manual deploy |
+
+## 3. PR process
+
+- Template: `.github/PULL_REQUEST_TEMPLATE.md`
+- Required reviewers: <N> reviewers (CODEOWNERS auto-assign)
+- Blocking jobs: <list>
+- Conventional labels: `feat`, `fix`, `chore`, …
+- Merge strategy: `squash` | `rebase` | `merge commit`
+
+## 4. Branch model
+
+- Model: **trunk-based** | gitflow | …
+- Naming: `feat/<slug>`, `fix/<slug>`
+- Lifetime: <typical duration before merge>
+- Protected branches: `main`, `staging` — direct push forbidden
+
+## 5. Release
+
+- Trigger: <manual via gh action / auto on tag / …>
+- Command: `npm run deploy:prod` (or `gh workflow run deploy.yml`)
+- Tag: `v<MAJOR>.<MINOR>.<PATCH>` via `npm version`
+- Auto-deploy: <yes/no, under what conditions>
+- Rollback: `vercel rollback <deployment-id>` (TTR < 5min)
+- Freeze windows: <e.g.: no release on Friday after 5pm>
+- Communication: <where we announce — Slack, changelog, etc.>
+
+## References
+
+- Related ADRs: `trunk-based-branching`, …
+- CI handbook: `../handbook/ci-pipeline.md`
+```
+
+Finish by:
+- Recapping the updated file.
+- Listing the sources read (`.github/workflows/*`, etc.).
+- Suggesting an ADR if an undocumented workflow decision emerged
+  (e.g.: "we are moving to trunk-based" deserves an ADR).
+
+## Guardrails
+
+- **Do not invent commands**. If you are not sure of the deploy
+  command, read `package.json` or ask the human. A workflow doc with a
+  wrong command is worse than no doc.
+- **No "because it's better" reasoning**. Justifications live in the
+  ADRs (`decision-record-writer`). The workflow doc describes *what is
+  in place*.
+- **Cross-link, do not duplicate**. The content of `ci.yml` is not
+  copied here — we link to the file. The workflow doc *summarizes* and
+  explains the operational why.
+- **No auto-commit**.

package/dist/templates/code-quality.md.tmpl

@@ -0,0 +1,57 @@
+# Code quality — <PROJECT_NAME>
+
+This document sets the quality rules **specific to this project**. It is
+normative: it states what the project requires, not what the code does
+today (that is the handbook's job). The code audit (`/clean-code`)
+reads it before any other context.
+
+What does not belong here:
+
+- the *why* of a structural decision → an ADR, linked from this file;
+- the description of the implementation → the handbook;
+- rules already enforced by a tool's configuration → point to the
+  configuration file, do not copy it;
+- generic principles (SOLID, Clean Code) → already in the audit
+  skill.
+
+## Mechanical checks
+
+What the tools already check. The code audit does not re-report these
+points.
+
+| Tool | Configuration | Covers | Command |
+|---|---|---|---|
+| <FORMATTER> | `<FORMATTER_CONFIG_FILE>` | <FORMATTER_SCOPE> | `<FORMAT_COMMAND>` |
+| <LINTER> | `<LINTER_CONFIG_FILE>` | <LINTER_SCOPE> | `<LINT_COMMAND>` |
+| <TYPE_CHECKER> | `<TYPE_CHECKER_CONFIG_FILE>` | <TYPE_CHECKER_SCOPE> | `<TYPECHECK_COMMAND>` |
+
+## Project rules
+
+The judgment rules that no tool checks. One rule = one sentence
+verifiable on review, with a link to the ADR when a structural
+decision motivates it.
+
+### Naming
+
+- <NAMING_RULE>
+
+### Decomposition and architecture
+
+- <ARCHITECTURE_RULE> — see [<ADR_TITLE>](../decisions/<ADR_SLUG>.md)
+
+### Typing
+
+- <TYPING_RULE>
+
+### Tests
+
+- <TESTING_RULE>
+
+## Accepted deviations
+
+The generic rules the project chooses **not** to follow.
+The code audit does not report them as defects.
+
+| Generic rule | Accepted deviation | Reason |
+|---|---|---|
+| <GENERIC_RULE> | <PROJECT_DEVIATION> | <REASON_OR_ADR_LINK> |