cohorte 2.7.0 → 2.9.0

package/core/commands/cohorte-retro.md

@@ -0,0 +1,85 @@
+---
+description: Mine the accumulated review findings across features for repeating patterns, and turn the ones the human ratifies into PIPELINE.md §Conventions rules the next build already follows.
+argument-hint: [last <n> | all]  (default: every feature with a report on disk)
+---
+
+You are running the **retrospective**. Every review this pipeline has run left structured
+residue on disk — verdicts, Remediation rounds, deferred backlog items. A finding that shows up
+once is a bug; the same finding shape across features is a **missing rule**, and the pipeline
+has a place for rules the implementers actually read: `PIPELINE.md` §Conventions, baked into
+each surface agent at render time. This command closes that loop: findings → patterns →
+ratified rules → re-rendered agents. The next build then never produces the finding again —
+which is cheaper than any number of review rounds catching it.
+
+> Read `PIPELINE.md` §`pipeline-profile` (`surfaces`, and skim the existing §Conventions
+> stanzas — a rule that already exists is a finding about *enforcement*, not a missing rule)
+> and `specs/_decisions.md` §Live. _Skip the re-read if already in context and unmodified._
+
+## 1. Collect — mechanical, redirected, no judgment yet
+
+Scope: `all` (default), or `last <n>` features by spec mtime. In as few Bash calls as possible,
+**always redirected to `specs/reports/retro-scan.txt` and grepped — never into your context**:
+
+- `specs/reports/*.verdict.json` — per feature: `blocking_items` (normalized identities),
+  `severity`, per-surface counts. The freshest machine record, one per feature.
+- Every non-`_` spec's `## Remediation` section — the **persistent** history (verdict.json is
+  overwritten per round; Remediation accumulates, and collapsed rounds still carry their
+  count line). Grep the item lines: `- [x?] <SEVERITY> · <file:line> · <kind> · <fix>`.
+- `specs/refactor-backlog.md` — the `deferred:<id>` tagged items: debt reviews kept finding
+  but no feature owned.
+
+A repo with fewer than two features' worth of residue ⇒ say the retro has nothing statistical
+to stand on yet, name what exists, and stop — one feature's findings are that feature's story,
+not a pattern.
+
+## 2. Patterns — what repeats, with the evidence attached
+
+A **pattern** is a finding shape that recurs where recurrence means something:
+
+- same `kind` × same surface across **≥ 2 features** (e.g. `security` findings on `backend`
+  twice running — the strongest signal there is);
+- the same file/module named by findings from **≥ 2 features** (a hotspot no single fix loop
+  owns);
+- the same *fix wording* family recurring (e.g. three "add the authz check" fixes = one
+  missing authorization convention);
+- a `deferred:` cluster in one domain — debt the reviews keep re-discovering because no rule
+  makes the implementers avoid adding to it.
+
+For each pattern, produce: the evidence lines **verbatim** (`<feature> · <severity> · <file> ·
+<problem/fix>`), the count, and ONE drafted convention rule — **rule-shaped**: a sentence an
+implementer can follow and a reviewer can test a diff against, placed under `### Shared` or the
+owning `### Surface: <key>`. Not advice ("be careful with auth") — a rule ("every route under
+`apps/api/src/routes/` calls `authorize()` before its handler; no exceptions without a spec
+§5 note"). Skip any pattern the existing §Conventions already covers — report those separately
+as **enforcement gaps** (the rule exists and reviews keep finding violations: that is input for
+the human, not a new rule).
+
+## 3. Ratify — the human picks; nothing lands without them
+
+Present a compact table: pattern → evidence count → drafted rule → target stanza. Then **stop
+and ask** which to adopt (all / some / none — none is a fine outcome and says the rulebook fits
+the codebase). Rules are standing law every future dispatch pays tokens to carry: the human
+decides what becomes law, exactly as they freeze specs.
+
+## 4. Apply — and keep the baked slices honest
+
+For each adopted rule, in this order:
+
+1. Append it to `PIPELINE.md` §Conventions under its stanza (create the `### Surface: <key>`
+   stanza if absent; keep it rule-shaped, one line each).
+2. **Re-render every affected surface agent** per SCHEMA.md §Rendering step 2 — the
+   `<SURFACE_CONVENTIONS>` slice is **baked at render time**, so a §Conventions edit without a
+   re-render produces the worst outcome available: reviewers (who read the prose live) enforce
+   a rule implementers (who carry the stale bake) have never seen, and every future review
+   round re-finds the pattern this retro just paid to close. If you cannot re-render on this
+   runtime, say so and route to `/cohorte-update-pipeline` (its reconcile step 2 re-renders) —
+   but then the rule is **pending**, and you say that too.
+3. Append ONE line per adopted rule to `specs/_decisions.md` §Live (SCHEMA.md §Decisions):
+   `- <date> · conventions · <rule, compressed> — because <kind>×<n> across <features> · retro`.
+   A retro rule is a standing decision; the journal is where the next `/cohorte-spec` learns it
+   without re-mining the reports.
+
+In chat print ONLY: patterns found / adopted / skipped (one line each), enforcement gaps, which
+agents were re-rendered (or the pending route), and the decisions lines appended. The evidence
+stays in `specs/reports/retro-scan.txt`. **Recommend a `/clear`** — everything that matters is
+now in `PIPELINE.md`, the rendered agents, and the journal.

package/core/commands/cohorte-review.md

@@ -12,7 +12,8 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > **Kanban** (SCHEMA.md §Kanban): run
 > `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS review`. `auto` resolves the board from the config itself and
 > exits 0 with a `kanban: <reason>` line when there is none — so **never decide "no board is
-> configured" without running it**.
+> configured" without running it**. _(PR mode — `--pr` below — skips this entirely: an incoming
+> PR is not a pipeline feature and has no card.)_
 >
 <!-- cohorte:if workflows -->
 > **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
@@ -20,6 +21,57 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > This conversational path stays the default and the fallback; `/cohorte-doctor` shows which is available.
 <!-- cohorte:endif -->
 
+## PR mode — review an INCOMING pull request (`--pr <num>` or a PR URL)
+
+If `$ARGUMENTS` contains `--pr <num>` (or a GitHub PR URL — extract the number), this is not a
+pipeline feature: it is **someone else's work arriving**, reviewed with the same reviewers and the
+same report format, without pretending it went through the pipeline. What that changes, explicitly:
+**no spec** (nothing to check conformance against — reviewers run in audit mode: conventions +
+correctness + security + TDD coverage only), **no kanban move**, **no verdict.json**, **no DoD
+tick, no freshness stamp, no metrics line** — those certify pipeline features, and this is not one.
+Requires `vcs.host: github` + `gh`; otherwise say so and stop.
+
+1. **Fetch into a throwaway worktree — never touch the current checkout.** One Bash call:
+   `gh pr view <num> --json title,baseRefName,headRefName,author` (relay the one-line summary), then
+   `git fetch -f origin pull/<num>/head:cohorte-pr-<num> <baseRefName> && git worktree add ../<repo>-pr-<num> cohorte-pr-<num>`
+   — `-f` so a branch left behind by a crashed earlier run updates instead of failing, and the
+   **base ref is fetched too**: the diff below is against `origin/<baseRefName>`, and a stale
+   local base blames the PR for every commit it merely hasn't rebased onto yet.
+   The human's tree, branch and stamps stay untouched; every later step runs `-C` that worktree.
+2. **Mechanical checks inside the worktree — the commands directly, NEVER `preflight.sh`.** The
+   script's whole point is stamping `<state>/preflight.ok` in the MAIN checkout (it resolves
+   through `git-common-dir` on purpose), so running it here would overwrite the human's stamp
+   with the PR tree's digest — greening pipeline review dispatches of a tree nobody preflighted,
+   then blocking them once the worktree is gone. Instead: install dependencies first
+   (`commands.install` — a bare `worktree add` has no `node_modules`), then run the profile's
+   typecheck/lint-quiet/test-quiet yourself, each appended to the worktree's
+   `specs/reports/pr-<num>.preflight.txt`, stopping at the first failure. **Red does NOT get
+   reviewers** — same economics as §0 (a reviewer on code that doesn't compile rediscovers what
+   `tsc` printed for free) — but unlike §0 it is not an abort: the mechanical failures ARE the
+   review (severity CRITICAL, kind `quality`, the failing command + last lines) — jump to
+   step 4. An *environmental* failure (install itself failed, a missing service) is reported as
+   "not verifiable here", never as a finding against the PR.
+3. **Stage + dispatch — §1's staging procedure and §2's dispatch, minus everything spec-shaped**
+   (there is no `specs/<id>.md` to confirm and no small-diff fast path — an unknown author's
+   diff always gets a full reviewer), with three substitutions: the diff is
+   `git diff origin/<baseRefName>...HEAD` (**three-dot** — only the PR's own commits, not the
+   base's drift), staged diffs and file paths are **absolute paths into the worktree**
+   (reviewers are stateless — they must not read the main checkout), and the dispatch template's
+   spec/contract slots read
+   `spec: none (incoming PR — audit mode: PIPELINE.md conventions + quality/security/TDD only,
+   skip spec conformance)` · `contract: none`. Roll call + merge per §3 (retry once, `unreviewed`
+   forbids a clean verdict), same capped REVIEW REPORT.
+4. **Stage the report to the MAIN checkout's `specs/reports/pr-<num>.md`** (it must outlive the
+   worktree), print the verdict + severity table + CRITICAL/security digests in chat. Then —
+   **always ask the human first, posting is outward-facing** — offer:
+   `gh pr comment <num> --body-file specs/reports/pr-<num>.md` (prefix the body with one line:
+   `Automated review — cohorte pipeline (advisory)`). Never post without the explicit go-ahead;
+   "no" leaves the report on disk and that is a complete outcome.
+5. **Teardown, always** (also after a red preflight or a dead reviewer):
+   `git worktree remove --force ../<repo>-pr-<num> && git branch -D cohorte-pr-<num>`.
+
+Everything below this line is the normal pipeline-feature flow.
+
 ## 0. Deterministic pre-flight — no agents while red
 
 Run the profile's mechanical gates in ONE Bash call via the shipped script
@@ -136,9 +188,11 @@ between the pipeline and any automated driver, which parses no prose:
 
 - **`blocking` = CRITICAL findings + `security` findings, deduplicated** (a finding that is both
   counts once). That is exactly the agent's existing verdict rule restated as a number, so
-  `blocking == 0` ⟺ `verdict == SHIP`. HIGH/MEDIUM/LOW quality findings are **not** blocking —
-  they follow the `deferred:<id>` backlog route below, and must never cost a driver an iteration.
-- **`blocking_items`** — one normalized string per blocking finding, `<surface>|<file>|<problem>`:
+  `blocking == 0` ⟺ `verdict == SHIP`. HIGH/MEDIUM/LOW quality findings are **not** blocking and
+  must never cost a driver an iteration — a *human* routes them in the verdict branch below
+  (a `/cohorte-fix` pass, or a deliberate park in the backlog); a driver ignores them.
+- **`blocking_items`** — one normalized string per **distinct** blocking finding (deduplicated —
+  two findings sharing surface, file and problem head are one identity), `<surface>|<file>|<problem>`:
   the file path **without the `:line`** (a fix that inserts lines shifts every line below it — a
   line-bearing identity would change every pass and the drift detection would never fire), and the
   **problem**, not the fix, cut to its first 8 words, lowercased, every run of non-alphanumerics
@@ -181,25 +235,33 @@ In chat print ONLY: the verdict, the severity-count table, a one-line digest of
 finding, and `Full report: specs/reports/$ARGUMENTS.md` — never echo the findings body into chat (it
 would sit in this session's history, re-sent every turn). Then:
 
-- **SHIP** → only reachable with `unreviewed` empty (the roll call above forbids it otherwise). A SHIP
-  verdict *is* the pipeline's statement that the feature meets its Definition of
-  Done, so **tick the DoD**: in `specs/$ARGUMENTS.md` §`Acceptance criteria / DoD`, flip each `- [ ]`
-  → `- [x]` for the criteria the pipeline has actually verified — spec conformance + `ui_language`
-  copy (this review), tests · lint · typecheck (a green `/cohorte-build`), mobile-first as far as the code
-  shows it (this review). **Leave `- [ ]` (and say which) any item no stage actually verified** —
-  nothing in the pipeline *runs* the feature, so any criterion that needs the app up (runtime flows,
-  a visual check against the design) stays open unless the human says they exercised it by hand and
-  it held. Ticking is the lead's job
-  (the reviewer is read-only). **Then stamp the freshness gate** so `/cohorte-ship` can refuse to ship code
-  edited after this verdict: compute `BASE=$(git merge-base <default_branch> HEAD)` and write into the
-  spec front-matter `reviewed_base: $BASE` plus
-  `reviewed_digest: $(git diff $BASE -- . ':(exclude)specs/' | sha256sum | cut -c1-16)` — the fingerprint
-  of exactly the source you just reviewed (specs excluded, so DoD ticks + the ship status flip don't
-  trip it). Then tell the human they can `/cohorte-ship` — **recommend a `/clear` first**, the handoff is
-  fully on disk. **SHIP with leftover LOW findings** (or LOW+MEDIUM at the human's call) does NOT
-  force a fix cycle for nits: park them through §3.5's exact route (the backlog, under their surface's
-  domain heading, tagged `deferred:$ARGUMENTS` — never as open `## Remediation` items, which would
-  re-trigger the fix loop), keep the SHIP verdict and the freshness stamp, and let the human ship.
+- **SHIP** → only reachable with `unreviewed` empty (the roll call above forbids it otherwise).
+  **Split on what survived — the DoD tick and the freshness stamp are earned by a clean bill, not
+  by the verdict alone** (the workflow variant enforces the same rule; certifying surviving
+  HIGH/MEDIUM findings for `/cohorte-ship` would ship known defects):
+  - **Nothing above LOW survived** — the clean bill. **Tick the DoD**: in `specs/$ARGUMENTS.md`
+    §`Acceptance criteria / DoD`, flip each `- [ ]` → `- [x]` for the criteria the pipeline has
+    actually verified — spec conformance + `ui_language` copy (this review), tests · lint ·
+    typecheck (a green `/cohorte-build`), mobile-first as far as the code shows it (this review).
+    **Leave `- [ ]` (and say which) any item no stage actually verified** — nothing in the pipeline
+    *runs* the feature, so any criterion that needs the app up (runtime flows, a visual check
+    against the design) stays open unless the human says they exercised it by hand and it held.
+    Ticking is the lead's job (the reviewer is read-only). **Then stamp the freshness gate** so
+    `/cohorte-ship` can refuse to ship code edited after this verdict: compute
+    `BASE=$(git merge-base <default_branch> HEAD)` and write into the spec front-matter
+    `reviewed_base: $BASE` plus `reviewed_digest: $(git diff $BASE -- . ':(exclude)specs/' | sha256sum | cut -c1-16)`
+    (`shasum -a 256` then the first 16 hex chars where there is no `sha256sum` — macOS) — the
+    fingerprint of exactly the source you just reviewed (specs excluded, so DoD ticks + the ship
+    status flip don't trip it). Park the leftover LOWs through §3.5's exact route (the backlog,
+    under their surface's domain heading, tagged `deferred:$ARGUMENTS` — never as open
+    `## Remediation` items, which would re-trigger the fix loop). Then tell the human they can
+    `/cohorte-ship` — **recommend a `/clear` first**, the handoff is fully on disk.
+  - **HIGH or MEDIUM findings survived** — the verdict stays SHIP (they are not blocking), but
+    **no DoD tick and no freshness stamp**. Route them: `/cohorte-fix $ARGUMENTS` for what should
+    be fixed now; MEDIUMs the human *explicitly* chooses to live with go through §3.5's park
+    instead — and once everything left is LOW, apply the clean-bill branch above (tick, stamp,
+    ship). The stamp is the pipeline certifying what ships; it is never written over known
+    HIGH/MEDIUM defects.
 - **REVISE / BLOCK**, or any CRITICAL/HIGH/security finding → tell the human to run
   **`/cohorte-fix $ARGUMENTS`** — it appends the report to the spec's `## Remediation` and re-dispatches ONLY
   the surfaces with findings. The full path (`/cohorte-spec` Mode B then `/cohorte-build`) remains for findings that

package/core/commands/cohorte-ship.md

@@ -23,7 +23,8 @@ You are the **lead**. Ship feature **$ARGUMENTS**. This is the outward-facing ga
   verdict was REVISE/BLOCK, stop and say so.
 - **Freshness gate** — the reviewed code must be exactly what ships. If the spec front-matter carries
   `reviewed_base` + `reviewed_digest`, recompute
-  `git diff <reviewed_base> -- . ':(exclude)specs/' | sha256sum | cut -c1-16` and compare to
+  `git diff <reviewed_base> -- . ':(exclude)specs/' | sha256sum | cut -c1-16` (`shasum -a 256`
+  then the first 16 hex chars where there is no `sha256sum` — macOS) and compare to
   `reviewed_digest`. **Match** ⇒ source unchanged since the SHIP verdict, proceed. **Mismatch** ⇒ source
   (or the contract) was edited after review — the verdict is **stale**: stop and tell the human to re-run
   `/cohorte-review $ARGUMENTS` before shipping. Missing fields (spec predates the gate) ⇒ skip, don't block.

package/core/commands/cohorte-spec.md

@@ -91,7 +91,7 @@ Detect the mode from the pasted content:
    `specs/reports/<id>.md`, where `/cohorte-review` stages its last report. Identify `feature_id` from its
    header; open `specs/<id>.md`.
 2. Append each finding to the spec's **`## Remediation`**, one per line:
-   `- [ ] <severity> · <file:line> · <spec-violation|quality|security> · <concrete fix>`
+   `- [ ] <severity> · <file:line> · <spec-violation|quality|security|complexity> · <concrete fix>`
    (Keep prior items; add the new round under a dated/numbered subheading.)
 3. If a finding implies the **contract** must change, update §5 and flag it so the lead re-authors the
    contract file.

package/core/hooks/gate.py

@@ -454,13 +454,19 @@ def check_bash(payload: dict, cfg: dict) -> int:
             branch_cache[directory] = branch is None or branch == default
         return branch_cache[directory]
 
-    for raw in SPLIT.split(command):
-        seg = norm(raw)
-        if not seg:
-            continue
+    segments = [s for s in (norm(raw) for raw in SPLIT.split(command)) if s]
+
+    # Deny wins over ask across the WHOLE chain, not just in segment order. Scanning
+    # segment-by-segment returned on the first match, so `git commit -m x && node ace
+    # migration:fresh` surfaced only the benign `git commit` ask — and the human's one
+    # confirmation ran the hard-denied command behind it. Scan every segment for deny
+    # patterns first; only a fully deny-free chain gets an ask.
+    for seg in segments:
         for pat in deny:
             if norm(pat) in seg:
                 return decide("deny", f"`{pat}` is forbidden by the project's PIPELINE.md gate.")
+
+    for seg in segments:
         for pat in ask:
             if norm(pat) in seg:
                 return decide(ask_decision,

package/core/workflows/audit.js

@@ -157,8 +157,15 @@ const gates = await agent(
   'the file and return each failure as file/line/kind/one-line summary, capped at 40 (set overflow for the rest).',
   { model: 'haiku', label: 'gates', schema: GATES, effort: 'low' },
 )
+// A dead gates agent is NOT "zero mechanical failures" — silence would read as the
+// cleanest possible inventory from a phase that never ran (SCHEMA.md §Dead agents).
+// The domain auditors still run (they read the staged gates file, which then simply
+// isn't there), but the run must say the mechanical sweep is uncovered.
+const gatesCovered = gates != null
 const mech = (gates && gates.failures) || []
-log(`Mechanical failures: ${mech.length}${gates && gates.overflow ? ` (+${gates.overflow} overflow)` : ''}`)
+log(gatesCovered
+  ? `Mechanical failures: ${mech.length}${gates.overflow ? ` (+${gates.overflow} overflow)` : ''}`
+  : 'the gates agent died — mechanical checks NOT covered this run')
 
 // ── Phase 2 — one auditor per domain, concurrent ─────────────────────────────
 // Domains = every surface + `shared` (contract package + anything outside the
@@ -195,6 +202,10 @@ if (deadDomains.length) {
   body.push('', `> ⚠ NOT audited (the auditor died): ${deadDomains.join(', ')} — absence of items below`,
     '> for those domains means "not looked at", not "clean". Re-run the audit for them.')
 }
+if (!gatesCovered) {
+  body.push('', '> ⚠ Mechanical gates NOT run (the gates agent died) — lint/typecheck/test failures',
+    '> are uncounted below. Re-run the audit for the mechanical sweep.')
+}
 let total = 0
 for (const d of perDomain) {
   const items = [...d.items].sort((a, b) => SEV[a.severity] - SEV[b.severity])
@@ -214,7 +225,8 @@ const backlogOk = written != null && /done/i.test(String(written))
 return {
   backlog: backlogOk ? 'specs/refactor-backlog.md' : '(NOT written — the backlog writer died)',
   notAudited: deadDomains,   // absence of findings here means "not looked at"
-  mechanicalFailures: mech.length,
+  mechanicalFailures: gatesCovered ? mech.length : null,  // null = gates agent died, NOT zero
+  gatesCovered,
   domains: Object.fromEntries(perDomain.map(d => [d.key, d.items.length + (d.overflow || 0)])),
   total,
   top: perDomain.flatMap(d => d.items.map(it => ({ ...it, domain: d.key })))