cohorte 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.4.0 — 2026-08-13
+
+- **The pipeline froze *what* to build, never *how much*.** A spec pins the contract and the
+  acceptance criteria, so the feature was right — but nothing ever asked an implementer whether the
+  helper it was about to write already existed three files over, whether the stdlib shipped it, or
+  whether the abstraction it was wrapping had exactly one caller. The diff came out correct and
+  fatter than it needed to be, and every extra line was then paid twice: once at build, once again at
+  `/cohorte-review`, whose cost is linear in the diff it reads.
+
+  Implementers now walk a **minimality ladder** before inventing anything: does it need to exist at
+  all → already in this repo → stdlib/framework → native platform feature → an already-installed
+  dependency → a few inline lines → only then the minimum the contract requires. It governs the
+  **how**, never the **what** — a contract field, an acceptance criterion, a test, a validation or an
+  authz check is out of its reach, by construction. It is bounded to **one lookup per candidate**, so
+  it costs a symbol search and not an exploration, and a shortcut kept on purpose surfaces in the
+  handoff's `## TODO / not done` with its ceiling and its upgrade trigger, instead of rotting in a
+  comment.
+
+  The `review` agent gains the matching axis — over-engineering, tagged `delete:` / `stdlib:` /
+  `native:` / `yagni:` / `shrink:`, always naming the cheaper replacement. It is deliberately the
+  weakest thing in the report: **5 findings max, MEDIUM ceiling, never a CRITICAL, never a REVISE,
+  never a BLOCK**. A diff whose only findings are `complexity` ships, and they park in the backlog
+  like any other nit. Tests, fixtures and anything the contract mandates are out of bounds — coverage
+  is not bloat. In audit mode the axis widens to the whole target (10 per domain, biggest cut first,
+  closing with `net: -N lines, -M deps possible.`), and `/cohorte-audit` files them under a new
+  `complexity` backlog tag: the cheapest wins in the file, since deleting code needs no new test.
+
+  Doctrine adapted from [ponytail](https://github.com/dietrichgebert/ponytail) (MIT) — the decision
+  ladder and the finding tags are theirs; the subordination to the frozen contract and the
+  can't-block severity ceiling are what make them safe inside a gated pipeline.
+
+  Run `/cohorte-update-pipeline` to re-render your surface agents — the ladder lives in the
+  implementer template, so it only reaches your agents through a reconcile.
+
 ## 2.3.0 — 2026-08-12
 
 - **A bug fix had to pretend to be a feature.** The only way into the pipeline was

package/core/agents/implementer.template.md

@@ -59,6 +59,33 @@ them over Grep/Glob + whole-file Reads**: locate code by symbol, read only the d
 and trace references before changing any shared shape. Fall back to Grep/Read only when the retrieval
 tools are unavailable or come up empty.
 
+## How you choose what to write — the minimality ladder
+
+The spec froze the **what**; this ladder governs only the **how**. It never licenses you to skip a
+contract field, an acceptance criterion, a test, a validation, an authz check or an accessibility
+attribute — those are the *what*, and they are not yours to trim.
+
+Before writing any helper, utility, wrapper, abstraction or new dependency, walk down and stop at the
+first hit:
+
+1. **Does it need to exist at all?** An abstraction with one implementation, a config nobody sets, a
+   layer with one caller — don't write it. The second caller is when it earns its keep.
+2. **Is it already in this repo?** One retrieval/Grep lookup by symbol name, not a survey — you are
+   checking, not exploring. Reuse beats re-implementing, and it keeps the convention.
+3. **Is it in the standard library / framework?** Name it and use it.
+4. **Is it a native platform feature?** (CSS, the HTTP layer, the DB, the runtime.) Prefer it over code.
+5. **Is it in a dependency already installed?** Use that one. Adding a dependency for what tiers 3–5
+   already ship is a finding at review.
+6. **Can it be a few lines inline?** Then it doesn't need a file, a class, or a name.
+7. Only then: the **minimum implementation that satisfies the contract** — no speculative options, no
+   "we'll probably need" parameters, no premature generalisation.
+
+Bound the cost: this is at most **one lookup per candidate**, and it applies to code you are inventing —
+never to code the contract dictates. If a step would cost more searching than writing, write it.
+
+Something you deliberately kept simple with a known ceiling goes in your handoff `## TODO / not done`
+with its limit and what would trigger the upgrade — not in a comment, and not silently.
+
 ## How you work — strict TDD (red → green → refactor)
 
 <!-- <SURFACE_TDD_STEP1> is a LEAD-IN paragraph, not a numbered item: it is filled only for a

package/core/agents/review.md

@@ -63,6 +63,20 @@ be precise and self-contained.
    additive `sm:/md:/lg:`, no fixed widths that break on mobile. (You can't render; judge from the code.)
 7. **TDD coverage.** Each surface's tests cover its slice of the contract (statuses, validation, auth,
    behavior). Flag untested contract surface.
+8. **Over-engineering (lowest priority, never blocking).** Code the diff *added* that didn't need to
+   exist. Tag each one and always name the replacement — a finding with no cheaper alternative is an
+   opinion, not a finding:
+   - `delete:` dead code, unused flexibility, a speculative feature nothing calls. Replacement: nothing.
+   - `stdlib:` hand-rolled thing the standard library or framework ships. Name the function.
+   - `native:` a dependency or code doing what the platform already does. Name the feature.
+   - `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+   - `shrink:` same behaviour, materially fewer lines. Name the shorter form.
+
+   **Hard limits on this axis.** It is capped at **5 findings**, biggest cut first, and its severity
+   ceiling is **MEDIUM** — it can never produce CRITICAL, never REVISE, never BLOCK. Test code,
+   fixtures and anything the contract or an acceptance criterion mandates are **out of bounds**:
+   coverage is not bloat, and "simpler" is never a reason to drop a spec'd behaviour. Deduplication
+   that would cross a surface boundary is out of bounds too — that's an architecture call, not a review one.
 
 ## Language checks (apply only those matching the surfaces under review)
 
@@ -89,10 +103,19 @@ entry point / module with **no test**), and the lint/format/type debt staged at
 dispatch names (`specs/reports/audit-gates.txt`). Emit a **prioritized refactor backlog grouped by
 domain** (same finding-line shape) instead of a SHIP/REVISE/BLOCK verdict.
 
+In audit mode the over-engineering axis (§8) widens: there is no diff, so the whole target is in
+scope and the 5-finding cap lifts to **10 per domain**, ranked biggest cut first. Hunt the usual
+shapes — deps the stdlib or platform already ships, single-implementation interfaces, factories with
+one product, wrappers that only delegate, dead flags and config, hand-rolled stdlib. Close the
+audit-mode report with one line: `net: -<N> lines, -<M> deps possible.` (`0`/`0` is a valid answer —
+say it rather than inventing cuts).
+
 ## Severity & verdict
 
 - **CRITICAL** — spec violation or correctness bug that must be fixed ⇒ verdict **REVISE**.
 - **HIGH / MEDIUM / LOW** — quality/convention issues; note them.
+- **Over-engineering (§8) caps at MEDIUM** and never drives the verdict — a diff whose only findings
+  are `complexity` ships. It is a cleanup signal, not a gate.
 - Any **security vulnerability** ⇒ verdict **BLOCK**.
 - No CRITICAL and no security issue ⇒ verdict **SHIP**.
 
@@ -117,7 +140,7 @@ they are **never lost and never cost a fix loop**.
 ## Your return — the REVIEW REPORT, exactly this shape
 
 Every finding must be **self-sufficient for a stateless agent**: `file:line` · severity ·
-`spec-violation | quality | security` · one concrete suggested fix — it gets appended verbatim to the
+`spec-violation | quality | security | complexity` · one concrete suggested fix — it gets appended verbatim to the
 spec's `## Remediation`. Your final message **is** the report. **The shape is capped:** at most
 **20 findings**, ONE line each, **zero code excerpts** (the diff and the source are on disk — a
 `file:line` is enough for a stateless fixer). More than 20? Keep every CRITICAL/HIGH/security
@@ -140,12 +163,13 @@ Verdict: <SHIP | REVISE | BLOCK>
 
 ## Findings
 
-- **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security> · <problem> → **Fix:** <concrete change>
-(order by severity; "None." if none; max 20 lines, one per finding, no code excerpts)
+- **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security|complexity> · <problem> → **Fix:** <concrete change>
+(order by severity; "None." if none; max 20 lines, one per finding, no code excerpts.
+ `complexity` lines carry their §8 tag in the problem — `yagni: <what>` — and cap at 5)
 
 ## Deferred
 
-- **[<SEVERITY>]** `<file>:<line>` · <quality|security> · <problem> → **Fix:** <concrete change> · out of scope: <why this feature does not own it>
+- **[<SEVERITY>]** `<file>:<line>` · <quality|security|complexity> · <problem> → **Fix:** <concrete change> · out of scope: <why this feature does not own it>
 (real but out of this feature's scope — see §Deferred; worst first; "None." if none; max 10 lines)
 
 ## Notes

package/core/commands/cohorte-audit.md

@@ -32,8 +32,9 @@ bulk never sits in your history, then grep it for the `file:line` of every failu
 
 Dispatch `review` (read-only; static prompt first, variable slot last — prompt-cache prefix):
 "Audit a target against `PIPELINE.md` (no spec — **audit mode**). Check conventions (§Conventions
-per surface), TDD coverage (untested entry points / modules per surface), and — if the profile
-enables them — mobile-first + design-system usage. Mechanical findings from the gates: read
+per surface), TDD coverage (untested entry points / modules per surface), over-engineering (§8,
+widened per your audit-mode rules — ranked biggest cut first, closing `net:` line), and — if the
+profile enables them — mobile-first + design-system usage. Mechanical findings from the gates: read
 `specs/reports/audit-gates.txt`. Emit a prioritized refactor backlog (capped finding-line format
 from your instructions), grouped by domain (one group per surface + shared). — Target: `$ARGUMENTS`
 (default: whole repo)."
@@ -42,7 +43,11 @@ from your instructions), grouped by domain (one group per surface + shared). —
 
 Merge mechanical + convention findings into one prioritized backlog and **write
 `specs/refactor-backlog.md`**, grouped by domain, each item:
-`- [ ] <SEVERITY> · <file:line> · <rule|tdd|lint|format|type|security> · <concrete fix>`
+`- [ ] <SEVERITY> · <file:line> · <rule|tdd|lint|format|type|security|complexity> · <concrete fix>`
+
+`complexity` items are the over-engineering cuts, ranked biggest first inside their domain — they are
+the cheapest wins in the backlog (deleting code needs no new tests) but they never outrank a
+security, correctness or `tdd` item.
 
 **Carry over the deferred items** before overwriting: `grep -n 'deferred:' specs/refactor-backlog.md`
 and re-emit every **open** (`- [ ]`) match verbatim under its domain, tag included. Those lines were

package/core/commands/cohorte-review.md

@@ -165,7 +165,7 @@ exactly the leak this step closes. Append each merged `## Deferred` item to
 `/cohorte-refactor <domain>` picks them up with no extra plumbing):
 
 ```
-- [ ] <SEVERITY> · <file:line> · <quality|security|rule> · <concrete fix> · deferred:$ARGUMENTS
+- [ ] <SEVERITY> · <file:line> · <quality|security|rule|complexity> · <concrete fix> · deferred:$ARGUMENTS
 ```
 
 - **Never into the spec's `## Remediation`** — that list is what `/cohorte-fix` re-dispatches, so a

package/core/workflows/review.js

@@ -125,7 +125,7 @@ const FINDING = {
   properties: {
     severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
     file: { type: 'string' }, line: { type: 'integer' },
-    kind: { enum: ['spec-violation', 'quality', 'security'] },
+    kind: { enum: ['spec-violation', 'quality', 'security', 'complexity'] },
     problem: { type: 'string', description: 'one line, no code excerpts' },
     fix: { type: 'string', description: 'one concrete change, one line' },
   },
@@ -141,7 +141,7 @@ const DEFERRED = {
   properties: {
     severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
     file: { type: 'string' }, line: { type: 'integer' },
-    kind: { enum: ['quality', 'security', 'rule'] },
+    kind: { enum: ['quality', 'security', 'rule', 'complexity'] },
     problem: { type: 'string', description: 'one line, no code excerpts' },
     fix: { type: 'string', description: 'one concrete change, one line' },
     outOfScope: { type: 'string', description: 'one line: why this feature does not own it' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code, Codex CLI, Cursor, Gemini CLI and OpenCode — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"