Name and guard CDD's engineering-practices & self-improvement objectives

.claude/commands/cdd-pre-pr.md

@@ -53,7 +53,17 @@ Check and **update** documentation based on the changes:
 
 Read each relevant doc and compare against the actual code changes. Fix discrepancies directly when they are reconciliation (the doc is out of date relative to what landed). Ask before applying structural changes (adding new doc files, restructuring an existing doc).
 
-## 5. CI improvement check (conditional)
+## 5. Test coverage reconciliation
+
+For each behavioural change in the diff (a new function, a new branch, changed output, a fixed bug), check whether it is covered by a test. This is the recurring guardrail behind the "tested behaviour" row of `doc/knowledge_base/engineering-practices.md`.
+
+- **If the project has a test command** ("tested behaviour" marked *enforced*): confirm a test exercises the new behaviour. If a behavioural change landed with no accompanying test, flag it — the default expectation is that new behaviour ships with a test.
+- **If a change is deliberately untested** (a throwaway script, generated code, a spike): that is allowed, but it must be *intentional and recorded*, not silent. State the reason in the PR summary.
+- **If the project has no test command yet** ("tested behaviour" still *expected*): do not invent a framework. Note that the change shipped untested because there is no test harness, and confirm that standing one up is tracked as a roadmap task. If this change is exactly the kind of behaviour that motivates a first test, say so and let the user decide whether to pull that task forward.
+
+This step asks a question and records the answer; it does not mandate a specific framework, a coverage threshold, or that every change be tested. "Not tested, and here is why" is a valid, recorded outcome. Surface it — do not block on it.
+
+## 6. CI improvement check (conditional)
 
 If, and only if, the change introduces a category of work that the existing CI does not cover, propose specific improvements to the user. Examples that should trigger a proposal:
 
@@ -64,7 +74,7 @@ If, and only if, the change introduces a category of work that the existing CI d
 
 Do **not** propose generic CI improvements every run. The default is silence. If you do propose, the user has two options: apply now in this PR, or defer as a new roadmap task. Apply only on approval.
 
-## 6. Upstream drift check
+## 7. Upstream drift check
 
 ```bash
 git fetch origin main
@@ -86,9 +96,9 @@ The script renders the template through `bootstrap-cdd-project.sh --stage` with
 
 If the script exits 0, report "no drift" and continue. If it reports divergence, present each diff to the user; for each, the user decides whether to reconcile the repo copy, reconcile the template copy, or record a justified exception (a whitelist entry or a `cdd-only` fence). Apply fixes only on user approval. Do not auto-edit either tree from this step.
 
-When presenting the step 7 checklist, append a `- [ ] Command-set drift clean` line to it.
+When presenting the step 8 checklist, append a `- [ ] Command-set drift clean` line to it.
 <!-- cdd-only-end -->
-## 7. Summary
+## 8. Summary
 
 Present a checklist summary:
 
@@ -105,30 +115,31 @@ Present a checklist summary:
 - [ ] CLAUDE.md up to date
 - [ ] README up to date
 - [ ] Roadmap up to date
+- [ ] New behaviour tested (or untested-with-reason recorded)
 - [ ] CI gaps surfaced: none / proposed (list them)
 - [ ] No upstream drift (or: /cdd-merge-main recommended)
 - [ ] Reconciliation edits committed
 ```
 
 Mark each item as pass ✓ or needs attention ✗ with details.
 
-## 8. Commit reconciliation edits
+## 9. Commit reconciliation edits
 
-Commit the documentation reconciliation edits this session made in steps 3–6 (architecture/feature docs, CLAUDE.md, README, the coding standard, and the roadmap). This is a local commit only — **no push**. Pushing happens, if at all, in step 9.
+Commit the documentation reconciliation edits this session made in steps 3–7 (architecture/feature docs, CLAUDE.md, README, the coding standard, and the roadmap). This is a local commit only — **no push**. Pushing happens, if at all, in step 10.
 
 First check the entry snapshot from step 1:
 
 - **If the tree was already dirty on entry** (changes this session did not create), **stop and surface** them: list those paths, state that the auto-commit is skipped so unrelated work isn't swept in, and let the user resolve it. The checklist above still stands on its own.
 - **Otherwise**, commit only the files this session edited. Add them by path — do not `git add -A`:
 
 ```bash
-git add <files reconciled in steps 3–6>
+git add <files reconciled in steps 3–7>
 git commit -m '<message>'
 ```
 
 Follow the repo's commit conventions from CLAUDE.md. Print a one-line summary of the commit (subject + files included). If nothing was reconciled (no edits this session), say so and skip the commit.
 
-## 9. Open PR (optional)
+## 10. Open PR (optional)
 
 After the checklist, offer to open the PR. This is human-gated — never open a PR without explicit confirmation.
 
@@ -140,7 +151,7 @@ gh auth status && git remote get-url origin   # origin should be a github.com UR
 
 If either is missing, say so in one line and skip this step (the checklist above still stands).
 
-If §6 found upstream drift, restate the recommendation to run `/cdd-merge-main` before opening the PR, and let the user decide whether to proceed anyway.
+If §7 found upstream drift, restate the recommendation to run `/cdd-merge-main` before opening the PR, and let the user decide whether to proceed anyway.
 
 Ask: **"Open a PR now?"** Do not pre-show a title or body, and do not print manual `gh` instructions — just ask whether to proceed.
 

CLAUDE.md

@@ -8,6 +8,7 @@ CDD is a human-in-the-loop workflow for evolving software projects together with
 | ---------------------------------------------------- | ------------------------------------------------- |
 | Process document (philosophy, lifecycle, edit rules) | `doc/knowledge_base/claude-driven-development.md` |
 | Implementation roadmap                               | `doc/knowledge_base/roadmap.md`                   |
+| Engineering practices (enforced vs expected)         | `doc/knowledge_base/engineering-practices.md`     |
 | Documentation map                                    | `doc/index.md`                                    |
 | Architecture of this repo                            | `doc/architecture/index.md`                       |
 | Architecture decision records                        | `doc/architecture/adr/` (Nygard style)            |
@@ -64,7 +65,7 @@ When `/cdd-pre-pr` runs in this repo, the "build / format / lint / test" gates c
 
 | Directory                          | Purpose                                                   |
 | ---------------------------------- | --------------------------------------------------------- |
-| `doc/knowledge_base/`              | Process doc, roadmap, decision records                    |
+| `doc/knowledge_base/`              | Process doc, roadmap, engineering practices, decision records |
 | `doc/architecture/`                | How this repo is structured                               |
 | `doc/features/`                    | What this repo provides (process + template)              |
 | `template/`                        | Copy-paste material for new projects                      |

demo/seed/CLAUDE.md

@@ -9,6 +9,7 @@ Markdown Renderer is a small local web app: paste Markdown into a box, see it re
 | System architecture & design     | `doc/architecture/` (start with `index.md`)       |
 | Feature documentation            | `doc/features/` (start with `index.md`)           |
 | Implementation roadmap           | `doc/knowledge_base/roadmap.md`                   |
+| Engineering practices            | `doc/knowledge_base/engineering-practices.md`     |
 | Design decisions                 | `doc/knowledge_base/` (decision records)          |
 
 **Read `doc/architecture/` before planning any feature or structural change.**

demo/seed/doc/knowledge_base/engineering-practices.md

@@ -0,0 +1,40 @@
+# <PROJECT_NAME> Engineering Practices
+
+The engineering floor Markdown Renderer commits to. CDD distinguishes two kinds of practice:
+
+- **Enforced** — a CDD gate guarantees it on every change. If an enforced practice is failing, `/cdd-pre-pr` reports it and the change is not ready to merge.
+- **Expected** — committed to but not yet mechanized here; tracked as a roadmap task until it becomes enforced. "Expected" is a promise with a due date, not an opt-out.
+
+When an expected practice gains its mechanism, move it to **Enforced** in the same PR that lands the mechanism.
+
+## Documentation — Enforced
+
+Architecture, feature, and roadmap docs are reconciled against the diff by `/cdd-pre-pr` (documentation reconciliation). A change isn't done until the docs match it.
+
+## Tested behaviour — Enforced
+
+New behaviour ships with a test, or an explicit, recorded reason it does not. `/cdd-pre-pr` (test-coverage reconciliation) checks this on every change, and `/cdd-pre-pr` build & QA runs the suites.
+
+- Test command: `pytest`
+- Integration test command: `pytest tests/integration`
+
+## Continuous integration — Expected
+
+The checks below run locally through `/cdd-pre-pr`, but nothing runs them automatically on every PR yet. Adding a CI workflow (build + tests + lint on every PR) is tracked on the roadmap.
+
+- CI entry point: *none yet — expected*
+
+## Lint & format — Enforced
+
+`/cdd-pre-pr` build & QA runs both:
+
+- Lint command: `python -m pyflakes app`
+- Format check command: `black --check app tests`
+
+## Dependency & toolchain hygiene — Expected
+
+`requirements.txt` lists dependencies; pinning them to exact versions and documenting the Python toolchain version is *expected*.
+
+## How this list grows
+
+New practices are added here as the project matures. `/cdd-pre-pr`'s CI-improvement check and the roadmap's infrastructure tasks feed it — closing the CI task above flips "Continuous integration" from **Expected** to **Enforced**.

doc/architecture/adr/0001-name-and-guard-founding-objectives.md

@@ -0,0 +1,35 @@
+# 0001: Name and guard CDD's under-guarded founding objectives
+
+**Status:** Accepted
+
+## Context
+
+CDD has three founding objectives as stated by the project owner:
+
+1. **Automate as much as possible, but keep human approval at the important gates.**
+2. **Instil engineering best practices into any adopting project without invading how it works** — so juniors and non-engineers inherit architecture excellence, structured documentation, thorough unit/integration tests, and strong CI.
+3. **Self-improvement** — whenever CDD or a CDD project finds a workflow improvement (a better `CLAUDE.md`, a command/CI/test/doc improvement), it incorporates it.
+
+Two of these were under-guarded. Objective 2's testing/CI/lint half was only *suggested* — no shipped CI workflow, no test scaffolding, no lint config, and no canonical best-practices artifact in either layer — while its documentation half was already enforced. Objective 3 had no standing channel in steady state: upstreaming existed only via `/cdd-retrofit` upgrade mode and CDD-on-CDD dogfooding, with the friction log deliberately retired.
+
+**Structural root cause:** §1 named exactly four commitments. Objective 2's testing/CI half was unnamed (only its documentation half was elevated), and objective 3 was entirely unnamed. The philosophy can only guard what it names.
+
+## Decision
+
+Elevate the two under-guarded objectives to named commitments, and give each a concrete guardrail:
+
+- **§1 reframed, 4 → 5 commitments.** "The project documents itself" broadened to "the project holds itself to engineering standards as it grows" — documentation as the leading *enforced* exemplar; tests/CI/lint instilled by **mechanism and floor, not prescription**. Added a fifth commitment: "the workflow improves itself."
+- **An engineering-practices contract (§2.12)** — a canonical, enforced-vs-expected artifact, shipped in the template as `doc/knowledge_base/engineering-practices.md` and instantiated in both the CDD repo and the demo seed.
+- **A test-coverage reconciliation step in `/cdd-pre-pr`** (both command copies) — the recurring objective-2 guardrail, parallel to doc reconciliation: it surfaces and records coverage drift but adds no new checkpoint.
+
+Objective 3 is named this session but its mechanism is deferred (see below); the decision is to name the commitment now and design the channel separately rather than reintroduce a standing friction log.
+
+## Consequences
+
+- Objective 2 now has a named commitment, a canonical enumerated artifact, and a recurring guardrail — closing the largest gap. Tests/CI/lint are held to a floor by mechanism rather than prescribed per project type, preserving the "without invading how it works" constraint.
+- The engineering-practices contract is a third thing to keep consistent across the two layers (process doc + template) and the demo seed; drift there is now a defect like any other cross-layer drift.
+- The `/cdd-pre-pr` reconciliation step adds work to every pre-PR run, but deliberately *records* rather than *blocks* — it does not become a seventh checkpoint.
+- **Deferred (roadmap Phase 11):**
+  - *Objective-3 standing channel* — a recurring mechanism routing a discovered improvement into the roadmap/conventions (not a reintroduced log). Recorded as a §6 known gap.
+  - *Objective-1 mechanizations* — codifying when `/cdd-merge-main` should be recommended or auto-triggered, and any mechanical gate-honored check.
+  - *Objective-2 reinforcement at bootstrap* — a required bootstrap-phase task and/or checklist, once the recurring `/cdd-pre-pr` mechanism is proven.

doc/architecture/index.md

@@ -8,3 +8,4 @@ How this repo is structured. This index is a pointer list — the content lives
 - [Bootstrap & retrofit](bootstrap-and-retrofit.md) — the single substitution pipeline: bootstrap script, stage mode, overlay mode, `/cdd-bootstrap`, `/cdd-retrofit`, the baseline marker
 - [The demo layer](demo.md) — the third artifact: filled-in seed + create/teardown automation
 - `adr/` — architecture decision records (`adr/0000-template.md` for the format)
+  - [`0001-name-and-guard-founding-objectives.md`](adr/0001-name-and-guard-founding-objectives.md) — naming and guarding CDD's two under-guarded founding objectives (engineering practices, self-improvement)

doc/architecture/overview.md

@@ -27,7 +27,7 @@ Changes flow process-first, template-second. A PR that touches the process doc b
 │   ├── index.md                              # documentation map
 │   ├── architecture/                         # how this repo is structured
 │   ├── features/                             # what this repo provides
-│   └── knowledge_base/                       # process doc, roadmap, decisions
+│   └── knowledge_base/                       # process doc, roadmap, engineering practices, decisions
 ├── scripts/                                  # template smoke assertions + command-set drift check (with whitelists)
 ├── template/                                 # copy-paste material for new projects
 └── tools/

doc/features/demo.md

@@ -7,7 +7,7 @@ A `demo/` subsystem that instantiates a concrete project ("Markdown Renderer") f
 
 Contents:
 
-- `demo/seed/`: filled-in `CLAUDE.md`, a 6-phase roadmap, and architecture/features docs for the Markdown Renderer (CDD scaffolding only — the app itself is built by running CDD cycles on a created instance).
+- `demo/seed/`: filled-in `CLAUDE.md`, a 6-phase roadmap, the engineering-practices contract, and architecture/features docs for the Markdown Renderer (CDD scaffolding only — the app itself is built by running CDD cycles on a created instance).
 - `demo/setup.sh`: create an instance — wraps `bootstrap-cdd-project.sh --overlay demo/seed`, then always creates and pushes a GitHub repo. Auto-numbers disposable demo instances (`mdr_demo_NN`) checking both local dirs and existing repos; `mdr` is the kept dogfood instance.
 - `demo/teardown.sh`: reclaim an instance — remove the local directory and delete its GitHub repo (needs the `gh` `delete_repo` scope).
 

doc/features/template.md

@@ -7,7 +7,8 @@ A copy-paste directory (`template/`) plus a non-interactive bootstrap script (`t
 - `.claude/settings.json`: auto-allows worktree sessions to read their handoff file (`~/.claude-handoffs/<PROJECT_DIR>/**`), substituted at bootstrap.
 - `doc/index.md` plus `doc/{architecture,features,knowledge_base}/`: the documentation map and doc directory skeletons; the architecture and features skeletons follow the index-plus-per-topic-docs convention.
 - `doc/knowledge_base/project-overview.md`: the project-charter skeleton (what it is, goals, what it does and does not do, constraints, architecture intentions) — a living document, kept current. Filled by `/cdd-bootstrap` from discovery, or by hand otherwise.
-- `doc/knowledge_base/roadmap.md`: roadmap skeleton with a pre-filled Phase 1 of CDD bootstrap tasks (codebase survey, initial architecture and feature docs, CLAUDE.md and overview stubs, roadmap fill) plus a suggested-infrastructure task list (CI, linting, tests, …) to distribute across the project's real phases. The pre-filled phase serves files-only starts (`/cdd-retrofit` install + the manual script); `/cdd-bootstrap` writes those docs through discovery and ships a real roadmap without it.
+- `doc/knowledge_base/roadmap.md`: roadmap skeleton with a pre-filled Phase 1 of CDD bootstrap tasks (codebase survey, initial architecture and feature docs, CLAUDE.md and overview stubs, engineering-practices fill, roadmap fill) plus a suggested-infrastructure task list (CI, linting, tests, …) to distribute across the project's real phases. The pre-filled phase serves files-only starts (`/cdd-retrofit` install + the manual script); `/cdd-bootstrap` writes those docs through discovery and ships a real roadmap without it.
+- `doc/knowledge_base/engineering-practices.md`: the engineering-practices contract skeleton — each practice marked *enforced* (a CDD gate guarantees it) or *expected* (committed, tracked on the roadmap until mechanized), with placeholders for the project's own test/CI/lint commands. Filled in during the bootstrap phase.
 - `tools/PROJECT-worktree.sh`: worktree helper, renamed and substituted to `<PROJECT_SLUG>-worktree.sh` by the bootstrap script.
 - `BOOTSTRAP.md`: meta-documentation for the bootstrap recipe. Not copied into the bootstrapped tree.
 

doc/index.md

@@ -6,6 +6,7 @@ Documentation map for the CDD repository. Each directory keeps an `index.md` poi
 
 - [`architecture/`](architecture/index.md) — how this repo is structured
 - [`features/`](features/index.md) — what this repo provides
-- `knowledge_base/` — process doc, roadmap
+- `knowledge_base/` — process doc, roadmap, engineering practices
   - [`claude-driven-development.md`](knowledge_base/claude-driven-development.md) — the process document: philosophy, artifacts, lifecycle, edit rules (the shipped product)
   - [`roadmap.md`](knowledge_base/roadmap.md) — implementation roadmap for this repo
+  - [`engineering-practices.md`](knowledge_base/engineering-practices.md) — this repo's engineering floor: which practices are enforced vs expected