mandrel 2.7.0 → 2.9.0

package/.agents/workflows/helpers/qa-run-scenario.md

@@ -151,31 +151,17 @@ finding, it **MUST** pass
 Redaction is not optional — findings are posted to GitHub at the orchestrator's
 approval time, so unredacted secrets must never reach the `findings` output.
 
-## Deferred: batched sub-agent dispatch mode (spec-only)
-
-> **Not yet enabled.** This section specifies a future execution mode; the
-> current `/qa-run` sweep calls this helper **inline**, one scenario at a time,
-> in the orchestrator's own turn. The batched mode below is documented so the
-> contract is stable when it is turned on — do not implement it as live
-> behavior from this spec alone.
-
-In the deferred mode, the orchestrator MAY dispatch scenarios to fresh-context
-sub-agents to keep its own context window focused, under these hard rules:
-
-- **Sequential, never parallel.** Sub-agents run **one at a time**, never
-  concurrently. A live browser surface is a single shared resource; parallel
-  drivers would race on navigation and cross-contaminate evidence.
-- **One sub-agent per persona group.** Scenarios are grouped by persona and a
-  single sub-agent drives all of one persona's scenarios, so the persona is
-  signed in once per group rather than per scenario.
-- **Re-verify auth on entry.** Each sub-agent MUST re-verify the
-  authenticated-session precondition (a `take_snapshot` confirming the persona
-  badge) when it starts, because it does not share the orchestrator's live
-  session state.
-- **Same input/output contract.** Each sub-agent consumes the input contract
-  above and returns the per-scenario result shape above for every scenario it
-  drove — the orchestrator aggregates identically whether the helper ran inline
-  or via a batched sub-agent.
+## Sequential-only driving (a live browser is a shared resource)
+
+Scenarios are driven **one at a time, never concurrently**. A live browser
+surface is a single shared resource; parallel drivers would race on navigation
+and cross-contaminate evidence, so parallel driving is ruled out. Today the
+`/qa-run` sweep calls this helper **inline**, one scenario per turn. A future,
+**not-yet-enabled** batched sub-agent dispatch mode — which would still run
+sub-agents sequentially, one per persona group, re-verifying auth on entry and
+honoring the same input/output contract — is specified in
+[`qa-run-scenario-reference.md`](qa-run-scenario-reference.md). Do not implement
+that mode as live behavior from the spec alone.
 
 ## Constraints
 

package/.agents/workflows/helpers/worktree-lifecycle.md

@@ -242,73 +242,12 @@ Symlink strategy:
   specific failure up to 3 times with 250/500/1000 ms backoff. Unrelated fetch
   failures surface immediately — no retry.
 
-## Harness-worktree ⇄ consumer-lint-ignore interaction (Story #152)
-
-Mandrel's own worktree isolation (above) always roots story worktrees at
-`delivery.worktreeIsolation.root` (default `.worktrees/` at the repo root).
-That path is separate from **the host IDE/CLI harness's own worktree
-mechanism** — for example Claude Code, when it manages an agent session as a
-git worktree, nests it at `.claude/worktrees/<name>/`. A mandrel delivery
-agent can be invoked from *either* location depending on how the operator's
-harness composes with `/deliver`: mandrel's own `.worktrees/story-<id>/` when
-`worktreeIsolation.enabled` drives the checkout, or a harness-level
-`.claude/worktrees/<name>/` when the harness itself provides the isolated
-working directory mandrel runs inside.
-
-This matters because a consumer's `pre-push` (or `pre-commit`) lint step is
-commonly configured with an ignore glob that excludes noisy agent-tooling
-directories, e.g. a Biome `files.includes` entry like `"!**/.claude"`. When
-the *agent's CWD itself* resolves under `.claude/worktrees/<name>/`, a
-lint invocation scoped to `.` (`biome check .`, or equivalent) resolves
-every candidate path as living under the ignored `.claude` prefix — the glob
-matches zero files, and tools that treat zero-match as failure (Biome's
-default `check` behavior without `--no-errors-on-unmatched`) exit non-zero
-with something like `No files were processed in the specified paths`. This
-is a **false negative**: the changed files were never actually linted
-against, and the hook is not reporting a real defect. It is functionally
-distinct from a `pre-push` rejection caused by a genuine lint violation, and
-must not be treated the same way.
-
-**Do not resolve this by bypassing the push hook.**
-[`rules/git-conventions.md`](../../rules/git-conventions.md) § "Push
-Validation & Reliability" prohibits skipping hooks without explicit operator
-authorization, and that prohibition is not weakened by this interaction —
-the zero-match failure is a **consumer-tooling gap**, not a framework
-authorization the agent gets to grant itself.
-
-**Sanctioned resolution path:**
-
-1. **Recognize the signature.** A `pre-push`/`pre-commit` failure whose
-   message is a zero-match error (`No files were processed`, `0 files
-   matched`, or equivalent for the consumer's linter) — not a reported
-   violation in a specific file — combined with an agent CWD under
-   `.claude/worktrees/` (or any other harness-managed path a consumer's lint
-   config ignores) is this known interaction, not a real lint failure.
-2. **Fix it in the consumer, not the agent invocation.** The remedy lives in
-   the consumer's own lint command, mirroring what its `lint-staged` config
-   (if present) likely already does for the same reason: make the zero-match
-   case a no-op instead of a failure. For Biome:
-   `biome check --no-errors-on-unmatched .`. Other linters have an
-   equivalent flag (e.g. ESLint's `--no-error-on-unmatched-pattern`). This is
-   a one-line consumer-side change, typically to `.husky/pre-push` or the
-   `package.json` script it invokes.
-3. **Escalate through the normal HITL path**, per
-   [`.agents/instructions.md` § 1.J](../../instructions.md), if the agent
-   cannot edit the consumer's hook/lint config directly (e.g. it sits outside
-   the Story's scope). Transition to `agent::blocked`, name the zero-match
-   signature and the one-line remedy in the blocker summary, and let the
-   operator apply the consumer-side fix or explicitly authorize a one-time
-   hook-skip per [`rules/git-conventions.md`](../../rules/git-conventions.md)
-   § "Push Validation & Reliability". Explicit operator authorization is the
-   *only* circumstance under which a hook may be skipped — never as an
-   agent's unilateral default when this signature is recognized.
-4. **Do not relocate mandrel's own worktrees to work around a harness-level
-   path.** `delivery.worktreeIsolation.root` controls where *mandrel*
-   materializes `story-<id>` worktrees (default `.worktrees/`, already
-   outside `.claude/`) and is unrelated to where the host harness places its
-   own session worktree. Changing `worktreeIsolation.root` does not fix this
-   interaction when the false negative originates from the harness's path,
-   not mandrel's.
+## Harness-worktree ⇄ consumer-lint-ignore interaction
+
+When an agent's CWD resolves under a harness-managed worktree path the consumer's
+lint config ignores (e.g. `.claude/worktrees/`), a `.`-scoped lint can zero-match
+and fail falsely. Its signature and the sanctioned consumer-side fix (never a
+hook bypass) live in [`rules/git-conventions-reference.md` § Push Validation](../../rules/git-conventions-reference.md).
 
 ## Fallback: single-tree mode
 

package/.agents/workflows/mandrel-update.md

@@ -113,19 +113,13 @@ single source of truth, kept in lockstep with this table by
 | **migrate**       | `npx mandrel migrate --from <cur> --to <target>`        |
 | **doctor**        | `npx mandrel doctor` (then apply the per-check remedies) |
 
-The exact stderr the CLI prints per failed phase:
-
-- **sync** — the .agents/ materialization may be incomplete. Run `mandrel
-  sync` manually to restore.
-- **sync-commands** — the .claude/commands/ tree may be out of sync. Run `npm
-  run sync:commands` manually to restore.
-- **migrate** — some migrations for v\<cur\> → v\<target\> may not have
-  applied. Run `mandrel migrate --from <cur> --to <target>` manually to retry.
-- **doctor** — upgraded to v\<target\> but doctor reported failures. → Run
-  `mandrel doctor` for remedies.
-
-(`<cur>` / `<target>` are the installed and resolved-newest version strings
-the failing run reported.)
+The CLI prints the matching remedy command to stderr per failed phase; the
+workflow quotes those commands verbatim so an operator sees the same thing the
+CLI told them, and the drift gate above keys on them: Run `mandrel sync`
+manually to restore. · Run `npm run sync:commands` manually to restore. · Run
+`mandrel migrate --from <cur> --to <target>` manually to retry. · Run
+`mandrel doctor` for remedies. (`<cur>` / `<target>` are the installed and
+resolved-newest version strings the failing run reported.)
 
 Recovery sequence: run the matching remedy, then **re-run
 `npx mandrel update`** — it is idempotent (the install already landed, so a

package/.agents/workflows/plan.md

@@ -79,11 +79,36 @@ That is what makes superseding work without anyone re-typing ids
 
 The envelope carries docs context, codebase snapshot, BDD probe, risk
 heuristics, the story-author system prompt, `sourceTickets[]` (`--tickets`
-mode), and `duplicates[]` (open **Stories** whose title/body overlap the
-seed — never Epics).
+mode), `duplicates[]` (open **Stories** whose title/body overlap the
+seed — never Epics), and the `complexityRoute` ceremony-lite signal (below).
 Under `--yes`, do not ask free-form operator questions — unresolved
 unknowns land in Key Assumptions.
 
+#### Ceremony-lite complexity gate (`complexityRoute`)
+
+The envelope's `complexityRoute` field is a **deterministic, conservative**
+plan-time gate (Story #4683) that routes a genuinely trivial single-artifact
+seed onto a collapsed path so it stops paying the full two-session
+plan/deliver ceremony that measurably buys no quality at that size:
+
+- **`route: "lite"`** — a trivial scope (seed ≤ `maxSeedWords` words **and** ≤
+  `maxArtifacts` enumerated items). Collapse the ceremony: author **one minimal
+  Story** and skip the fresh-critic / Tech-Spec ceremony a one-artifact scope
+  does not earn. The lite route is **not** licence to drop a non-negotiable —
+  its `preserves` field enumerates exactly what still holds: the Story ticket,
+  the PR-to-`main` landing, every repo quality gate, and the security baseline.
+  Those gates still run in `single-story-close.js` regardless of route.
+- **`route: "full"`** — everything else. The gate fails toward `full` on any
+  doubt (empty seed, over the word ceiling, a multi-capability enumeration, or
+  the gate disabled via `planning.complexityGate.enabled=false`), so a real
+  capability slice never loses ceremony. Author normally under the split policy.
+
+The threshold and its override knob (`planning.complexityGate.{enabled,
+maxSeedWords, maxArtifacts}`) are documented in
+[`.agents/docs/configuration.md`](../docs/configuration.md) under `### planning`;
+the defaults live on `DEFAULT_COMPLEXITY_GATE` in
+[`lib/orchestration/complexity-gate.js`](../scripts/lib/orchestration/complexity-gate.js).
+
 **Gate #1** — STOP to confirm the sharpened plan intent and any
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
@@ -180,17 +205,21 @@ assumption, thin the Slicing checkpoint) and re-run this step. Empty
   provably have nothing for a critic to find, and each skip is recorded on the
   plan-metrics ledger so under-firing stays auditable.
 - **Either `dispatch: true`** — dispatch **one fresh-context sub-agent per
-  firing critic** (a generic sub-agent), then fold its findings into the
-  Gate #2 view or a re-author round before persist. Each critic is
+  firing critic**, then fold its findings into the Gate #2 view or a re-author
+  round before persist. When `delivery.routing.roleScopedAgents` is enabled
+  (the **default**), dispatch each firing critic with `subagent_type:
+  plan-critic` — it boots on the role-scoped
+  [`plan-critic`](../agents/plan-critic.md) context (its own system prompt, no
+  `CLAUDE.md` @-closure) that carries the maker-blind invariant, the
+  `consolidation` and `pre-mortem` charters, and the output shape standalone.
+  When the kill-switch is off (`roleScopedAgents: false`) or the host cannot
+  spawn at this depth, fall back to a generic sub-agent and hand it the same
+  charter (the `consolidation` / `pre-mortem` definitions in
+  [`plan-critic.md`](../agents/plan-critic.md)). Either way the critic is
   **maker-blind**: hand it the draft artifacts (`stories.json`, and
-  `techspec.md` when present) plus its charter below — never the authoring
-  transcript or the reasons the planner believed its own draft is sound. A
-  critic that reads the maker's case grades the case, not the draft.
-  - `consolidation` — the draft's shape: Stories that should be one cohesive
-    slice, a slice split per-module rather than per-capability, and
-    `depends_on` edges that disagree with the Delivery Slicing table.
-  - `pre-mortem` — assume the plan shipped and failed: name the most likely
-    failure modes and what the draft would have to say to prevent them.
+  `techspec.md` when present) — never the authoring transcript or the reasons
+  the planner believed its own draft is sound. A critic that reads the maker's
+  case grades the case, not the draft.
 
 Fold what survives back into `stories.json` and re-run this step. Findings are
 advisory input to the operator's Gate #2 decision, not an automatic re-author
@@ -201,11 +230,9 @@ mandate.
 **Gate #2** — when the operator passed `--force-review`, STOP for approval of
 the assembled plan before persist. Under `--yes`, auto-proceed.
 
-`--force-review` is the **only** thing that raises this gate. Story #4542
-retired the risk-derived alternative: the planner authored its own risk verdict,
-persist computed a `requiresStop` from it *after* `createStoryIssues` had already
-run, and nothing read the result — the STOP was prose executed by the same
-session that wrote the verdict. A gate a plan can lower for itself is not a gate.
+`--force-review` is the **only** thing that raises this gate — there is no
+risk-derived routing (Story #4542): a gate a plan can lower for itself is not a
+gate.
 
 #### Dry-run pre-pass (always)