mandrel 2.59.0 → 2.61.0

package/.agents/README.md

@@ -4,7 +4,7 @@ An opinionated workflow framework for AI coding assistants built on
 Story-centric GitHub orchestration. Planning, execution, and state all live natively in GitHub Issues, Labels, and Projects V2.
 
 This is the consumer README inside the distributed `.agents/` bundle. It explains what each part of the bundle is for and captures the cross-directory authoring conventions. The process narrative for
-`/mandrel-plan` and `/mandrel-deliver` stays in [`docs/SDLC.md`](docs/SDLC.md).
+`/mandrel-plan` and `/mandrel-deliver` stays in [`docs/SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md).
 
 The framework payload (`.agents/`) is consumed by host repos. It ships inside the [`mandrel`](https://www.npmjs.com/package/mandrel)
 npm package and is materialized into a consumer's `./.agents/` directory by `mandrel sync`. It carries a system prompt, a baseline rule pack, a two-tier skill library, a slash-command workflow set, and the orchestration engine that runs Story-centric plans on GitHub (`/mandrel-plan` → Stories, `/mandrel-deliver` → `story-*` → `main`).
@@ -118,8 +118,9 @@ clone produces zero file mutations.
 Once installed, the ongoing upgrade path is **`mandrel update`** — it bumps
 `mandrel` to the newest published version, re-runs `mandrel sync`,
 applies version-keyed migrations, and verifies the install with
-`mandrel doctor`. The lockfile bump is left **staged for you to review and
-commit** (the command performs no `git` mutation):
+`mandrel doctor`. The command performs **no `git` mutation** — it reads the
+index read-only and its closing line **reports** whether the dependency bump
+is staged, printing the exact `git add` to run when it is not:
 
 ```bash
 npx mandrel update           # update → sync → migrate → doctor
@@ -274,7 +275,7 @@ After bootstrap, every Mandrel command is generated into a flat
 `.claude/commands/` tree by `npm run sync:commands` (kept current at install
 time and on every `mandrel sync`/`update`) and loads as a bare `/<command>`
 slash command — e.g. `/mandrel-plan`, `/mandrel-deliver`, `/audit-security`. The commands load
-in every Claude Code environment. The [SDLC guide](docs/SDLC.md) walks end-to-end planning and
+in every Claude Code environment. The [SDLC guide](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md) walks end-to-end planning and
 delivery; Stories pair [`/mandrel-plan`](workflows/mandrel-plan.md) (idea → drafted Story Issue)
 with [`/mandrel-deliver`](workflows/mandrel-deliver.md) (Story Issue → merged
 PR).
@@ -331,7 +332,7 @@ integration branch; a ticket carrying an `Epic: #N` footer is refused by
 child checklist, never delivered itself, expanded to its open Stories by
 `/mandrel-deliver <epicId>` — and its linkage is parent→child only, which is
 what keeps that footer refused. The execution-model contract is owned by
-[`instructions.md` § 5.B](instructions.md) and [`docs/SDLC.md`](docs/SDLC.md).
+[`instructions.md` § 5.B](instructions.md) and [`docs/SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md).
 
 ---
 
@@ -340,7 +341,7 @@ what keeps that footer refused. The execution-model contract is owned by
 | Path | Purpose |
 | ---- | ------- |
 | [`instructions.md`](instructions.md) | Primary system prompt loaded by the host AI tool. |
-| [`docs/SDLC.md`](docs/SDLC.md) | Operator process for `/mandrel-plan` and `/mandrel-deliver`. |
+| [`docs/SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md) | Operator process for `/mandrel-plan` and `/mandrel-deliver`. |
 | [`starter-agentrc.json`](starter-agentrc.json) | Bootstrap delta-seed copied to the consumer repo root as `.agentrc.json`. |
 | [`agentrc-reference.json`](docs/agentrc-reference.json) | Exhaustive editor reference enumerating every schema key with its framework default. |
 | [`agents/`](agents/) | Optional role-scoped spawn boot contexts (`delivery.routing.roleScopedAgents`). |
@@ -361,10 +362,10 @@ what keeps that footer refused. The execution-model contract is owned by
 
 | You want… | Open |
 | --------- | ---- |
-| The Epic planning and delivery process | [`docs/SDLC.md`](docs/SDLC.md) |
+| The Epic planning and delivery process | [`docs/SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md) |
 | The system prompt loaded by your AI tool | [`instructions.md`](instructions.md) |
 | Every `.agentrc.json` key, default, and override | [`docs/configuration.md`](docs/configuration.md) (under `.agents/`) |
-| Quality-gate runbooks (CRAP, MI, lint, friction) plus the baseline envelope, component model, and writer/reader contract | [`.agents/docs/quality-gates.md`](docs/quality-gates.md) |
+| Quality-gate runbooks (CRAP, MI, lint, friction) plus the baseline envelope, component model, and writer/reader contract | [`docs/quality-gates.md`](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md) |
 | Slash-command workflow definitions | [`workflows/`](workflows/) |
 | Role-scoped spawn boot contexts | [`agents/`](agents/) |
 | Domain-agnostic baseline rules | [`rules/`](rules/) |
@@ -593,8 +594,8 @@ Module boundary rules:
 ## Baselines
 
 The framework's quality gates compare against per-kind baseline files under
-`baselines/<kind>.json` (lint, coverage, crap, maintainability, mutation,
-lighthouse, bundle-size), all sharing one envelope and funnelled through a
+`baselines/<kind>.json` (coverage, crap, maintainability, mutation,
+bundle-size, duplication), all sharing one envelope and funnelled through a
 shared reader / writer
 ([`reader.js`](scripts/lib/baselines/reader.js) /
 [`writer.js`](scripts/lib/baselines/writer.js)). The full reference — envelope
@@ -602,7 +603,7 @@ shape, per-kind axes, component model, path canonicalisation, writer/reader
 contract, kernel-version friction, and the consumer **floor override** path
 (add a `floors` block, and optional `components`, under your gate in
 `.agentrc.json`) — is owned by
-[`quality-gates.md` § Baseline reference](docs/quality-gates.md#baseline-reference).
+[`quality-gates.md` § Baseline reference](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md#baseline-reference).
 The unified runtime gate
 [`check-baselines.js`](scripts/check-baselines.js) currently runs floor +
 tolerance + schema + kernel-mismatch checks only; full regression absorption
@@ -643,7 +644,8 @@ Schema conventions:
 ## Code review providers (pluggable chain)
 
 `runCodeReview()` (invoked from `helpers/deliver-story` and `/mandrel-deliver`'s
-risk-routed ceremony) loads its review backend through a pluggable registry
+review pass, at the depth `review-depth.js` derives) loads its review backend
+through a pluggable registry
 configured via `delivery.codeReview.providers` — an array of entries iterated
 in declaration order. The chain-entry field semantics (`name`, `scopes`,
 `optional`, `manualPrompt`, `when`), the fix budget, and the cross-runtime
@@ -652,13 +654,13 @@ contract are documented once in
 
 ## Feedback loop — verification-results auto-graduation
 
-When a Story (or plan-run) finalize path runs, non-blocking findings that
-survived merge are auto-graduated into follow-up issues in a single pass over
-the unified `verification-results` structured comment, routed by source
+When a Story (or plan-run) finalize path runs, the retro's actionable routed
+proposals can be auto-graduated into follow-up issues, routed by source
 classification into the framework or consumer repo. The toggle
-(`delivery.feedbackLoop.auditResultsAutoFile`, default `true`), the opt-out
-example, and the idempotency-marker behaviour are documented once in
-[`docs/configuration.md` § delivery.feedbackLoop](docs/configuration.md#deliveryfeedbackloop--verification-results-auto-graduation).
+(`delivery.feedbackLoop.retroProposals`, default `false` since Story #5341),
+the opt-in example, and the idempotency-marker behaviour are documented once
+in
+[`docs/configuration.md` § delivery.feedbackLoop](docs/configuration.md#deliveryfeedbackloop--retro-auto-graduation).
 
 ## Worktree dependency strategies
 
@@ -680,7 +682,7 @@ They solve different problems and must not be confused:
   **within a single machine/clone**. They are keyed on local process PIDs
   and live under `.git/` (or a local lockfile path), so they do **not**
   coordinate across clones. See
-  [`docs/SDLC.md` § Cross-clone coordination](docs/SDLC.md#cross-clone-coordination)
+  [`docs/SDLC.md` § Cross-clone coordination](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md#cross-clone-coordination)
   for why.
 - **The assignee-as-lease claim** coordinates **across clones** by riding
   the ticket's GitHub `assignees` surface — a substrate every clone can

package/.agents/agents/acceptance-critic.md

@@ -3,10 +3,10 @@ name: acceptance-critic
 description: >-
   Role-scoped boot context for a maker-blind acceptance critic. Booted on its
   own system prompt (no CLAUDE.md / instructions.md closure). Scores a delivered
-  diff against the Story's acceptance-criteria cluster and emits the verdict
-  schema — without seeing the maker's self-assessment. Live under M7-B —
-  helpers/deliver-story Step 1a dispatches subagent_type: acceptance-critic
-  on the default risk-routed path.
+  diff against the Story's acceptance criteria and emits the verdict schema —
+  without seeing the maker's self-assessment. Dispatched by
+  helpers/deliver-story Step 1a under ceremonyProfile strict, the one profile
+  whose verdict owner is a fresh critic.
 ---
 
 <!--
@@ -48,8 +48,8 @@ the step-by-step. This shared core binds every role:
 # acceptance-critic — maker-blind acceptance evaluation
 
 You are an **independent acceptance critic**. You score a delivered change
-against a cluster of the Story's `acceptance[]` criteria and emit a structured
-verdict. You are deliberately isolated from the author's reasoning.
+against **every** item in the Story's `acceptance[]` array and emit one
+structured verdict. You are deliberately isolated from the author's reasoning.
 
 ## Maker-blind — the load-bearing invariant (MUST)
 
@@ -69,23 +69,24 @@ turned in about it. Your only trusted inputs are:
   in your verdict rather than substituting your own enumeration.
 - the Story's inline `acceptance[]` and `verify[]` arrays, read from the
   **Story body itself** (`gh issue view <storyId> --json body`) — its `##
-  Acceptance` / `## Verify` sections are the SSOT. The `story-init` structured
-  comment does not carry them — it reports init state only.
+  Acceptance` / `## Verify` sections are the SSOT. No structured comment
+  carries them.
 - the **actual output** of the `verify[]` commands you run yourself.
 
 Treat the implementation reasoning as untrusted. Score each criterion afresh
 from the evidence.
 
-## Scope — a cluster, never the cluster count
+## Scope — every criterion, exactly once
 
-You are handed **one cluster** of acceptance criteria to score. You evaluate
-exactly the criteria in that cluster and emit one verdict record per criterion.
-You do **not** decide how many clusters exist, re-slice the criteria, or merge
-clusters — the caller owns clustering.
+You score the Story's **whole** `acceptance[]` array and emit one verdict
+record per item, in acceptance-array order. You do **not** re-slice, split or
+sample the criteria: the gate reads the Story's own criteria count and refuses
+a verdict whose `criteria[]` length differs, before scoring and without
+consuming a round.
 
 ## Per-criterion evaluation
 
-For each acceptance item in your cluster:
+For each acceptance item:
 
 1. **Inspect the change set** — read the files your caller named and look for
    the change that would satisfy the criterion.
@@ -93,34 +94,14 @@ For each acceptance item in your cluster:
    **required evidence**. A criterion cannot be scored `met` without the
    supporting `verify[]` evidence where a `verify[]` command is relevant to it.
    `verify[]` is evidence, not optional advisory pre-flight.
-3. **Share `lint` / `typecheck` evidence with close** (Story #4250). When a
-   `verify[]` command is **byte-identical** to a close-validation gate, run it
-   through `evidence-gate.js` in the **same Story worktree** close validates so
-   a passing run records an evidence entry in the keyspace close consults:
-
-   ```bash
-   node <main-repo>/.agents/scripts/evidence-gate.js \
-     --standalone --scope-id <storyId> --gate lint \
-     --worktree <worktree> -- npm run lint
-
-   node <main-repo>/.agents/scripts/evidence-gate.js \
-     --standalone --scope-id <storyId> --gate typecheck \
-     --worktree <worktree> -- <resolved typecheck command>
-   ```
-
-   **Never** run the coverage / CRAP suite through `evidence-gate.js` to stamp
-   it fresh — a false-fresh coverage record without `coverage-final.json`
-   silently weakens the floor.
 
 ## Verdict schema (MUST)
 
-Write a verdict file under `temp/` at a **cluster-unique path** (e.g.
-`temp/acceptance-verdict-<storyId>-r<round>-c<clusterIndex>.json`) so parallel
-sibling critics cannot overwrite each other, conforming to
+Write **one** verdict file under `temp/` (e.g.
+`temp/acceptance-verdict-<storyId>-r<round>.json`) conforming to
 [`acceptance-eval-verdict.schema.json`](../schemas/acceptance-eval-verdict.schema.json):
-one `criteria[]` record per acceptance item in your cluster, in acceptance-array
-order. Each `index` is the criterion's position in the Story's **full**
-`acceptance[]` array, not within your cluster — the caller merges on it.
+one `criteria[]` record per acceptance item, in acceptance-array order, with
+`index` being the criterion's position in that array.
 
 ```json
 {
@@ -149,14 +130,14 @@ order. Each `index` is the criterion's position in the Story's **full**
 - `unmet` — not addressed, or the evidence contradicts the claim.
 
 **Return the verdict file's absolute path to your caller — never invoke
-`acceptance-eval.js` yourself.** The caller merges every cluster's records into
-one verdict and calls the gate **once** per round; a per-cluster call would burn
-a Story-level round per cluster. The **proceed / redraft / block** decision is
-the gate's, not yours. You score; the gate decides.
+`acceptance-eval.js` yourself.** The caller calls the gate **once** per round;
+the round counter is Story-scoped, so a second call spends a round for nothing.
+The **proceed / redraft / block** decision is the gate's, not yours. You score;
+the gate decides.
 
 ## Boundaries
 
 - Do not fix the code, redraft the diff, or commit. You evaluate and report.
-- Do not invent criteria beyond your cluster.
+- Do not invent criteria beyond the Story's `acceptance[]` array.
 - Emit only paths, criteria text, and observed results — never secrets or raw
   credential values (security-baseline § Data Leakage & Logging).

package/.agents/agents/story-worker.md

@@ -89,33 +89,32 @@ names. A null digest path means no docs mandate.
 (**typecheck, lint, test, format, maintainability, coverage, crap**) and is
 the authoritative gate — do not pre-run it. The **one** exception is the
 full suite: after the self-eval loop's last fix commit, run it once in
-`<workCwd>` through the depositor — `evidence-gate.js --standalone
---scope-id <storyId> --gate test --worktree <workCwd> -- npm test`. It runs
-whatever `npm test` resolves to and stamps that, so the credit is earned on
-any runner; a later commit voids it, and close captures coverage itself when
-the CRAP gate needs an artifact. If the suite outruns the host's sync Bash
-ceiling, dispatch it in the **background** — its completion notification
-re-invokes you. Never spawn a task to poll or `sleep`-loop against it; a
-waiter with a wrong condition outlives the agent. An exit code is never
-evidence a gate did work — the **output** is: a bare `npm test` deposits
-nothing unless it routes through mandrel's own runner, the only shape that
-says so. Redraft rounds run the scoped projects for the roots you changed
-plus `verify[]`, not the whole suite. Share `lint` / `typecheck` evidence
-with close via `evidence-gate.js`; never stamp coverage / CRAP fresh any
-other way.
-
-Gate output that lies: [`known-tooling-behavior.md`](../rules/known-tooling-behavior.md).
+`<workCwd>` exactly as
+[`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5 states it —
+that section is the rule's only home, so read the invocation there rather
+than from a copy here.
+
+If the suite outruns the host's sync Bash ceiling, dispatch it in the
+**background**: its completion re-invokes you. Never spawn a task to poll or
+`sleep`-loop against it; a waiter with a wrong condition outlives the agent.
+An exit code is never evidence a gate did work — its **output** is. Redraft
+rounds run the scoped projects for the roots you changed plus `verify[]`, not
+the whole suite, and never stamp coverage / CRAP fresh any other way.
+
+Gate output that lies (mandrel's own repo): `docs/contributing/known-tooling-behavior.md`.
 Waiter traps: [`parallel-tooling.md`](../workflows/helpers/parallel-tooling.md) Rule 2.
 
 ## Acceptance self-eval before close (MUST)
 
 **Before** flipping to `closing`, run the bounded self-eval loop
 ([`acceptance-self-eval.md`](../workflows/helpers/acceptance-self-eval.md)).
-Derive the change set, level and ceremony with
-`node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>`
-and hand its `files` to the critic — never one it re-derives. It scores
-each `acceptance[]` item, consuming `verify[]` output as evidence.
-**proceed** → flip to `closing`, run the suite, push, hand off;
+Derive the change set and the verdict owner with
+`node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>`.
+Under the default profile the owner is **you**: author **one** verdict file
+covering every `acceptance[]` item, scoring the derived `files` set — never
+one you re-derive — with `verify[]` output as evidence, and score it in one
+gate call. Under `strict` the owner is a fresh critic; hand it that same
+`files` list. **proceed** → flip to `closing`, run the suite, push, hand off;
 **redraft** → fix the criteria, commit, re-eval; **block** → take the
 blocked path below. Never hand off an unscored branch.
 

package/.agents/docs/agentrc-reference.json

@@ -27,7 +27,6 @@
     "projectNumber": null,
     "projectOwner": null,
     "operatorHandle": "@[USERNAME]",
-    "defaultTimeoutMs": 60000,
     "followUpRepos": {
       "framework": "dsj1984/mandrel",
       "platform": null
@@ -70,9 +69,6 @@
     }
   },
   "planning": {
-    "memoryPool": {
-      "indexByteCeiling": 24576
-    },
     "navigation": {
       "routeGlobs": [],
       "navRegistry": []
@@ -80,16 +76,13 @@
   },
   "delivery": {
     "execution": {
-      "timeoutMs": 600000,
-      "fullSuiteLock": true,
-      "requireCreditedCapture": false
+      "fullSuiteLock": true
     },
     "docsFreshness": {
       "paths": ["README.md"]
     },
     "tempRetention": {
       "enabled": true,
-      "staleDays": 7,
       "classes": {
         "orchestrationLogs": true,
         "validationEvidence": true,
@@ -116,24 +109,7 @@
       ]
     },
     "quality": {
-      "gateScoping": {
-        "scope": "diff",
-        "diffRef": "main"
-      },
       "gates": {
-        "lint": {
-          "enabled": true,
-          "baselinePath": "baselines/lint.json",
-          "tolerance": {
-            "kind": "absolute",
-            "value": 0
-          },
-          "floors": {
-            "*": {
-              "errorCount": 0
-            }
-          }
-        },
         "coverage": {
           "enabled": true,
           "baselinePath": "baselines/coverage.json",
@@ -148,8 +124,7 @@
               "functions": 90
             }
           },
-          "coveragePath": "coverage/coverage-final.json",
-          "timeoutMs": 600000
+          "coveragePath": "coverage/coverage-final.json"
         },
         "crap": {
           "enabled": true,
@@ -168,11 +143,6 @@
           "targetDirs": ["src"],
           "newMethodCeiling": 30,
           "requireCoverage": true,
-          "friction": {
-            "markerKey": "crap-baseline-regression"
-          },
-          "refreshTag": "baseline-refresh:",
-          "refreshTimeoutMs": 60000,
           "ignoreGlobs": [],
           "incrementalCoverage": {
             "skipWhenUnchanged": true,
@@ -192,7 +162,6 @@
             }
           },
           "targetDirs": [],
-          "refreshTimeoutMs": 60000,
           "ignoreGlobs": []
         },
         "mutation": {
@@ -206,26 +175,7 @@
             "*": {
               "score": 60
             }
-          },
-          "strykerConfigPath": null
-        },
-        "lighthouse": {
-          "enabled": false,
-          "baselinePath": "baselines/lighthouse.json",
-          "tolerance": {
-            "kind": "absolute",
-            "value": 0
-          },
-          "floors": {
-            "*": {
-              "performance": 0,
-              "accessibility": 0,
-              "bestPractices": 0,
-              "seo": 0
-            }
-          },
-          "baseUrl": null,
-          "routes": []
+          }
         },
         "bundle-size": {
           "enabled": false,
@@ -252,31 +202,11 @@
             }
           },
           "targetDirs": ["src"],
-          "refreshTimeoutMs": 60000,
           "ignoreGlobs": []
         }
       },
-      "formatAutofix": {
-        "timeoutMs": 60000
-      },
-      "codingGuardrails": {
-        "cyclomaticFlag": 8,
-        "requireSiblingTest": false
-      },
       "autoRefresh": {
-        "enabled": true,
-        "crapJumpCap": 5,
-        "scope": "diff"
-      },
-      "baselineEpsilon": {
-        "maintainability": 0.5,
-        "crap": 0.5,
-        "coverage": 0.1,
-        "mutation": 0.5,
-        "lint": 0,
-        "lighthouse": 1,
-        "bundle-size": 1024,
-        "duplication": 0.5
+        "enabled": true
       },
       "requireBaselines": false,
       "navigability": {
@@ -285,7 +215,6 @@
       }
     },
     "mergeWatch": {
-      "intervalSeconds": 30,
       "maxBudgetSeconds": 3600
     },
     "codeReview": {
@@ -307,7 +236,6 @@
           }
         }
       ],
-      "maxFixAttempts": 3,
       "autoFixSeverity": "medium"
     },
     "refactorStage": {
@@ -317,16 +245,9 @@
       "maxRounds": 2
     },
     "feedbackLoop": {
-      "auditResultsAutoFile": true,
-      "retroProposals": true
+      "retroProposals": false
     },
     "ci": {
-      "watch": {
-        "pollIntervalMs": 10000,
-        "maxPolls": 180,
-        "maxResumes": 3,
-        "attachWindowMs": 1200000
-      },
       "autoMerge": "trust-ci",
       "blockOnAdvisoryFailure": true,
       "advisoryAllowlist": [],