Enhance .cursor documentation and workflows

Updated the README.md to reflect new skill commands and improved descriptions for various workflows, including the addition of new skills like /test-spec, /code-review, and /release. Enhanced clarity on session boundaries and flow resolutions in the auto-chaining process.

Removed the implementer agent file as it is no longer needed. Updated coderule and meta-rule documents to enforce stricter testing and implementation standards, ensuring real results are produced rather than simulated ones.

Revised the autodev flow documentation to include a new release step and clarified the retrospective process. Adjusted the testing rules to specify coverage thresholds for critical paths.

Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/skills/plan/steps/01_artifact-management.md

@@ -26,6 +26,10 @@ DOCUMENT_DIR/
 │   └── deployment_procedures.md
 ├── risk_mitigations.md
 ├── risk_mitigations_02.md          (iterative, ## as sequence)
+├── adr/
+│   ├── 001_[decision_slug].md
+│   ├── 002_[decision_slug].md
+│   └── ...
 ├── components/
 │   ├── 01_[name]/
 │   │   ├── description.md
@@ -66,6 +70,8 @@ DOCUMENT_DIR/
 | Step 3 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
 | Step 3 | Diagrams generated | `diagrams/` |
 | Step 4 | Risk assessment complete | `risk_mitigations.md` |
+| Step 4.5 | Each ADR captured | `adr/NNN_[decision_slug].md` |
+| Step 4.5 | ADR index updated | `adr/README.md` |
 | Step 5 | Tests written per component | `components/[##]_[name]/tests.md` |
 | Step 6 | Epics created in work item tracker | Tracker via MCP |
 | Final | All steps complete | `FINAL_report.md` |
@@ -85,3 +91,15 @@ If DOCUMENT_DIR already contains artifacts:
 2. Identify the last completed step based on which artifacts exist
 3. Resume from the next incomplete step
 4. Inform the user which steps are being skipped
+
+#### Step 4.5 (ADR Capture) resumption rule
+
+ADR files have a `Status` field that disambiguates "step in progress" from "step done":
+
+- `Status: Proposed` → Step 4.5 is **in progress**. The user has not yet hit the BLOCKING gate (or hit it and chose B/C/D, which kept files at `Proposed`). Resume Step 4.5 at Phase 4.5f and re-present the BLOCKING Choose to the user. Do NOT skip to Step 5.
+- `Status: Accepted` AND `adr/README.md` index exists AND every Accepted ADR is referenced in the index → Step 4.5 is **done**. Skip to Step 5.
+- `Status: Accepted` but `adr/README.md` is missing or out of date → Step 4.5 is **partially complete**. Resume at Phase 4.5d (Maintain the ADR Index) before moving on.
+- Mixed `Proposed` + `Accepted` files in the same directory → Step 4.5 is **in progress** with prior partial confirmations. Resume at Phase 4.5f and re-present only the still-`Proposed` ADRs.
+- Empty `adr/` directory or no `adr/` directory → Step 4.5 has not started yet. Begin at Phase 4.5a.
+
+The `Date` field on every Accepted ADR is the date the user confirmed it; do not regenerate it during resumption.

.cursor/skills/plan/steps/04-5_adr-capture.md

@@ -0,0 +1,187 @@
+# Step 4.5: Architecture Decision Records (ADRs)
+
+**Role**: Architect / technical writer
+**Goal**: Capture every major architecture, tech-stack, data-model, and integration decision made during Steps 2–4 as a durable, dated, immutable record under `_docs/02_document/adr/`.
+**Constraints**: ADRs only — do not re-open architecture; do not make new decisions in this step. Document what has been decided, not what is still open.
+
+ADRs are the single thing in `_docs/` that explains the **why** of each major decision after the conversation history is gone. They are consumed by:
+
+- `decompose` Step 1.5 (`steps/01-5_module-layout.md`) — every Accepted ADR is cross-checked against the module-layout proposal; conflicts trigger an explicit Choose between supersede / exception / re-open.
+- `new-task` Step 4.5 (`SKILL.md` § "Step 4.5: Contract & Layout Check") — every new task is classified against Accepted ADRs as Conflict / Drift / Aligned; conflicts STOP the task with a Choose A/B/C; drift adds an `### ADR Impact` section; alignment adds an `### ADR Compliance` section.
+- `refactor` Phase 2b.1 (`phases/02-analysis.md`) — every Accepted ADR is diffed against the proposed roadmap; Violations trigger a BLOCKING supersede gate that produces a `supersede_adr_NNN.md` task before any refactor task is created.
+- `code-review` Phase 7 (`SKILL.md` § "Phase 7: Architecture Compliance") — every changed-files batch is checked against Accepted ADRs; ADR-Violation findings are Critical, ADR-Drift findings are High.
+
+Discipline that still relies on the human: when a downstream skill detects a Drift case, the resulting task spec MUST land its `## ADR Impact` / `## ADR Compliance` section; the implementer must address it; the next code-review batch then has the context it needs. Drift left undocumented is the silent-failure path — every consumer hook above is designed to make it visible.
+
+## Inputs
+
+- `_docs/02_document/architecture.md` (incl. confirmed `## Architecture Vision`)
+- `_docs/02_document/glossary.md`
+- `_docs/02_document/data_model.md`
+- `_docs/02_document/system-flows.md`
+- `_docs/02_document/risk_mitigations.md` (and any `risk_mitigations_NN.md` iterations from Step 4)
+- `_docs/02_document/components/[##]_[name]/description.md`
+- `_docs/02_document/deployment/` (CI/CD, environments, observability)
+- `_docs/00_problem/restrictions.md` and `_docs/00_problem/acceptance_criteria.md` (each ADR must reference relevant constraints / AC by ID)
+- Optional: `_docs/01_solution/solution.md` and `_docs/01_solution/tech_stack.md` (research output)
+- Optional: `_docs/LESSONS.md` — surface any lesson categories of `architecture` / `dependencies` that bias the recommendation
+
+## What is an ADR (and what is not)
+
+Capture an ADR when **all** of the following hold:
+
+1. The decision picks between two or more genuinely valid approaches with meaningful trade-offs.
+2. The decision has **downstream consequences** that other decisions, code, or tasks inherit from.
+3. The decision is **non-obvious** to a future reader who only sees the final code — they would ask "why was it built this way?" rather than discovering the answer by reading the source.
+
+Do NOT create an ADR for:
+
+- Naming, formatting, or purely cosmetic choices.
+- A choice that is fully implied by a single explicit restriction (`restrictions.md` is itself the record — link to it from the architecture doc instead).
+- A choice the team has not actually made yet — open questions live in `risk_mitigations.md` or `_docs/_process_leftovers/`, not in ADRs.
+- A technology selection where research already produced an exact-fit selection with one viable option (the research doc is the record — link to the relevant `solution_draft*.md` section).
+
+## Process
+
+### Phase 4.5a: Decision Inventory
+
+Walk the inputs and list candidate decisions. For each candidate, record a one-liner:
+
+```
+- [decision] — [trade-off summary] — [downstream consumers] — [evidence file:section]
+```
+
+Inspect at minimum:
+
+| Inspection target | Typical decisions surfaced |
+|-------------------|----------------------------|
+| `architecture.md` § layering | Layering style (clean vs hex vs n-tier), which layer owns transactions, how cross-cutting concerns enter |
+| `architecture.md` § Architecture Vision | The North Star principle (e.g., "edge-first, sync-second"); ADR captures the implication for one specific subsystem |
+| `data_model.md` | Datastore choice (Postgres vs Mongo), partitioning, soft vs hard deletes, schema evolution strategy |
+| `system-flows.md` | Sync vs async boundaries, idempotency strategy, retry policy ownership, error envelope shape |
+| `components/*/description.md` § interfaces | Public-API style (REST vs RPC vs event), versioning strategy, auth/authorization placement |
+| `deployment/containerization.md` | Single container vs sidecar vs init container, base image lineage |
+| `deployment/ci_cd_pipeline.md` | Trunk-based vs feature-branch, gate ordering, deploy strategy (blue-green / canary / all-at-once) |
+| `deployment/observability.md` | Logging stack, metric backend, sampling rate decisions, retention |
+| `risk_mitigations.md` | Risk-acceptance trade-offs (e.g., "we accept N% data loss in exchange for sub-100ms p99") |
+| Tech-stack from `_docs/01_solution/tech_stack.md` | Anything where research recorded ≥2 candidates and a winner |
+
+Drop any candidate that fails the three "what is an ADR" criteria above. Keep the rest.
+
+### Phase 4.5b: Numbering and Slugs
+
+ADRs are numbered globally per project, monotonically, never re-used.
+
+1. List existing files under `_docs/02_document/adr/` matching `^[0-9]{3}_.+\.md$`.
+2. The next ADR number is `max(existing) + 1`, zero-padded to 3 digits.
+3. The slug is kebab-case, ≤6 words, derived from the decision summary. Example: `001_use-postgres-for-transactional-data.md`, `004_event-driven-cross-component-comms.md`.
+
+### Phase 4.5c: Render One ADR Per Decision
+
+For each kept candidate, render the ADR using `templates/adr.md`. Required sections (do NOT omit any):
+
+| Section | Content |
+|---------|---------|
+| **Number** | `NNN` |
+| **Title** | One-line decision statement (matches slug) |
+| **Status** | `Proposed` (only during Step 4.5 iteration) → `Accepted` (after user confirmation at the BLOCKING gate) |
+| **Date** | YYYY-MM-DD (the date the user confirmed) |
+| **Deciders** | The user (project owner) — the AI is not a decider |
+| **Context** | The problem this decision addresses, including links to AC IDs, restriction IDs, risks, and (where relevant) the research draft section |
+| **Decision** | The chosen approach in one sentence, then the supporting detail |
+| **Alternatives Considered** | Each alternative with a one-line "rejected because…" |
+| **Consequences** | Positive (what becomes easier / cheaper / faster) and negative (what becomes harder / locked in / costly to undo). Be honest — every decision has a downside. |
+| **Supersedes / Superseded by** | Empty initially; updated when a future ADR overturns this one |
+| **Evidence** | File-and-section pointers into `_docs/` showing where the decision is reflected (architecture.md § layering, components/02_*/description.md § interface, etc.) |
+
+After rendering, write each file to `_docs/02_document/adr/NNN_<slug>.md`. Keep `Status: Proposed` until the BLOCKING gate.
+
+### Phase 4.5d: Maintain the ADR Index
+
+Write or update `_docs/02_document/adr/README.md` with this exact shape:
+
+```markdown
+# Architecture Decision Records
+
+This index lists every ADR for this project, in number order. ADRs are immutable once `Accepted` —
+new decisions that overturn a prior ADR are recorded as new ADRs whose `Supersedes` field points
+back, and the original ADR's `Superseded by` field is updated.
+
+| # | Title | Status | Date | Supersedes |
+|---|-------|--------|------|------------|
+| 001 | Use Postgres for transactional data | Accepted | 2026-05-21 | — |
+| 002 | Event-driven cross-component comms | Accepted | 2026-05-21 | — |
+| ... | ... | ... | ... | ... |
+```
+
+Sort by `#` ascending. Include all ADRs ever written, even superseded ones — the audit trail is the point.
+
+### Phase 4.5e: Cross-Link from architecture.md
+
+In `architecture.md`, every section that reflects an ADR decision gets a one-line trailing reference:
+
+```markdown
+> See ADR 001 (Use Postgres for transactional data), ADR 003 (Event-driven cross-component comms).
+```
+
+Place the reference at the end of the section, after the prose. This lets a future reader of `architecture.md` jump straight to the rationale.
+
+### Phase 4.5f: BLOCKING Gate — User Confirmation
+
+Present the ADR set to the user using the Choose format from `.cursor/skills/autodev/protocols.md` (or plain text if AskQuestion is unavailable):
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: ADR set captured (N records)
+══════════════════════════════════════
+ 001 — [title]
+ 002 — [title]
+ ...
+══════════════════════════════════════
+ A) Accept all ADRs as written
+ B) Edit specific ADRs (numbers and edits)
+ C) Add a missed decision (description)
+ D) Remove an ADR (number and reason)
+══════════════════════════════════════
+ Recommendation: A — review the rendered set and confirm; corrections are quick on Round 2
+══════════════════════════════════════
+```
+
+Loop:
+
+- **A** → flip every ADR's `Status` from `Proposed` to `Accepted`, set `Date` to today's date, save, exit step.
+- **B** → apply edits, re-present the modified ADRs, loop.
+- **C** → run Phase 4.5a–4.5e for the missed decision only, append to the set, re-present, loop.
+- **D** → confirm with the user that the candidate fails the three "what is an ADR" criteria, remove the file, update the index, loop.
+
+Do NOT mark `Accepted` without an explicit user A.
+
+## Self-verification
+
+- [ ] Every kept candidate from Phase 4.5a has a corresponding file under `adr/`
+- [ ] Every ADR has all required sections (none empty except `Supersedes` / `Superseded by`)
+- [ ] `Decision` sections are one-sentence-then-detail, not "we'll figure it out"
+- [ ] `Alternatives Considered` lists at least one rejected alternative per ADR
+- [ ] `Consequences` lists both positive AND negative consequences (an ADR with no negatives is suspect)
+- [ ] `Evidence` points at real `_docs/` sections that exist on disk
+- [ ] `adr/README.md` index lists every file in the directory and matches their `Status` / `Date`
+- [ ] `architecture.md` has a trailing `See ADR …` reference at every section that an ADR reflects
+- [ ] The user confirmed the set via Choose A; every ADR is `Accepted` with today's date
+
+## Common mistakes
+
+- **Re-opening architecture**: Step 4.5 records, it does not decide. If a candidate decision turns out to be unsettled, that's a Step 2 / Step 4 gap — return there, do not paper over it with a wishy-washy ADR.
+- **Decision-of-the-week**: do not write an ADR for every minor pattern choice. The bar is "non-obvious to a future reader". 5–15 ADRs is typical for a planning round; 40+ is over-capture.
+- **Negative consequences left empty**: every real decision has costs. If you cannot name one, the decision was not actually weighed.
+- **Vague evidence**: `architecture.md` is not enough — point at the specific section. `architecture.md § Layering` ≠ `architecture.md`.
+- **Numbering reuse**: never recycle a number from a deleted ADR. The audit trail is more important than tidy numbering.
+- **Superseding without recording**: when a later cycle overturns an ADR, the new ADR must point at the old one via `Supersedes`, AND the old ADR's `Superseded by` field must be updated. Index reflects both. (This is enforced when `decompose` or `refactor` later updates ADRs.)
+
+## Escalation
+
+| Situation | Action |
+|-----------|--------|
+| Candidate decision is unsettled (the team has not actually decided) | Return to the originating step (2 / 3 / 4); do NOT write a placeholder ADR |
+| Two candidates in Phase 4.5a turn out to be the same decision phrased differently | Merge into one ADR, list both phrasings in `Context` |
+| User picks D (remove an ADR) and the AI judges the decision is genuinely worth recording | Surface the disagreement, ASK why the user wants it removed, defer to user |
+| Existing `adr/` directory has files but `adr/README.md` is missing or stale | Rebuild the index from the directory before adding new ADRs |

.cursor/skills/plan/steps/05_test-specifications.md

@@ -2,7 +2,7 @@
 
 **Role**: Professional Quality Assurance Engineer
 
-**Goal**: Write test specs for each component achieving minimum 75% acceptance criteria coverage
+**Goal**: Write test specs for each component achieving the canonical minimum acceptance-criteria coverage (currently 75% — see `.cursor/rules/cursor-meta.mdc` Quality Thresholds; do not restate a different number here)
 
 **Constraints**: Test specs only — no test code. Each test must trace to an acceptance criterion.