mandrel 1.70.0 → 1.72.0

package/.agents/README.md

@@ -333,7 +333,7 @@ See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execu
 | Check registry authoring rules | [§ Self-healing checks](#self-healing-checks) |
 | JSON Schema conventions | [§ Schemas](#schemas) |
 | Bootstrap script (project + GitHub setup) | [`scripts/bootstrap.js`](scripts/bootstrap.js) |
-| Adopt the QA workflows (`/qa-explore`, `/qa-assist`, `/qa-run-harness`) in your project | [§ Adopting the QA harness](#adopting-the-qa-harness) |
+| Adopt the QA workflows (`/qa-explore`, `/qa-assist`, `/qa-run`) in your project | [§ Adopting the QA harness](#adopting-the-qa-harness) |
 | Coordinate two operators on the same repo (lease model) | [§ Multi-developer coordination](#multi-developer-coordination) |
 
 ---
@@ -890,12 +890,12 @@ known scenario set:
   `/qa-assist` when you hit something mid-flight and want it captured well
   without breaking stride; reach for `/qa-explore` when you want the agent to
   go hunt a named surface.
-- **`/qa-run-harness <selector>`** — the **automated complement**: it drives a
+- **`/qa-run <selector>`** — the **automated complement**: it drives a
   consumer's Gherkin `.feature` scenarios through a real browser (the
   `chrome-devtools` MCP surface), captures per-surface console/network into
   structured `F#` findings, and drafts follow-up tickets for operator
   sign-off. The end-to-end procedure is the SSOT in
-  [`workflows/qa-run-harness.md`](workflows/qa-run-harness.md); the
+  [`workflows/qa-run.md`](workflows/qa-run.md); the
   instrumentation conventions live in the
   [`skills/stack/qa/qa-harness`](skills/stack/qa/qa-harness/SKILL.md) skill; the
   architectural overview (run pipeline, contract fields, finding shape) is in
@@ -904,7 +904,7 @@ known scenario set:
 Reach for `/qa-explore` when you want the **agent** to hunt a freshly delivered
 Story/Feature or run a structured bug-hunt captured into a triageable ledger;
 reach for `/qa-assist` when **you** hit something mid-flight and want it
-enriched into a single triage-ready ledger item; reach for `/qa-run-harness` to
+enriched into a single triage-ready ledger item; reach for `/qa-run` to
 step a **known** scenario set through the browser for a regression pass.
 
 Binding the QA contract is **opt-in**. All three workflows resolve the
@@ -989,8 +989,8 @@ environment, never inlined) and `{ signInSkill }` points at a per-persona
 sign-in skill.
 
 Once these three `qa.*` keys are in place, `/qa-explore <surface>`,
-`/qa-assist`, and `/qa-run-harness <selector>` all resolve the contract and
-operate against the bound surface. For `/qa-run-harness`, the `chrome-devtools`
+`/qa-assist`, and `/qa-run <selector>` all resolve the contract and
+operate against the bound surface. For `/qa-run`, the `chrome-devtools`
 MCP surface is a host-provided runtime dependency; when it is unavailable the
 harness degrades with a clear error rather than falling back to a headless
 runner. `/qa-explore` and `/qa-assist` read the same `qa.*` keys to scope their

package/.agents/docs/SDLC.md

@@ -1103,7 +1103,7 @@ for the acceptance tier is governed by
 [`rules/gherkin-standards.md`](../rules/gherkin-standards.md).
 
 The acceptance tier is executed and reported via
-[`workflows/qa-run-harness.md`](../workflows/qa-run-harness.md) and consumed as
+[`workflows/qa-run.md`](../workflows/qa-run.md) and consumed as
 epic evidence by
 [`workflows/helpers/epic-testing.md`](../workflows/helpers/epic-testing.md).
 
@@ -1146,8 +1146,8 @@ set:
   (`qa-ledger.schema.json`) and reuses the same `scripts/lib/qa/` and
   `scripts/lib/findings/` decision seams, so a `/qa-assist` item flows through
   the identical dedup, classification, and promotion machinery later.
-- **[`workflows/qa-run-harness.md`](../workflows/qa-run-harness.md)**
-  (`/qa-run-harness`) — the **automated complement**: it steps a *known* set of
+- **[`workflows/qa-run.md`](../workflows/qa-run.md)**
+  (`/qa-run`) — the **automated complement**: it steps a *known* set of
   Gherkin `.feature` scenarios through a real browser, asserting `Then`
   outcomes semantically against the accessibility snapshot and bundling
   console/network problems into structured `F#` findings for operator sign-off.
@@ -1420,6 +1420,5 @@ For Stories already in flight, use one of the three options above.
 | *helper* `workflows/helpers/epic-deliver-story`               | Per-Story worker called by `/deliver`'s wave loop; not an operator slash command. See [`helpers/epic-deliver-story.md`](../workflows/helpers/epic-deliver-story.md).         |
 | *helper* `workflows/helpers/single-story-deliver`             | Per-Story worker called by `/deliver`; not an operator slash command. See [`helpers/single-story-deliver.md`](../workflows/helpers/single-story-deliver.md).                |
 | *helper* `workflows/helpers/code-review.md`                   | Auto-invoked by `/deliver`'s `delivery.code-review` state (scope: epic); not a slash command.                                                                            |
-| `/git-commit-all`                                | Stage and commit all changes                                                                                                                                                 |
-| `/git-push`                                      | Stage, commit, and push to remote                                                                                                                                            |
+| `/git-deliver`                                   | Ad-hoc delivery of working-tree changes — detects the git setup and escalates to commit, commit + push, or commit + push + PR (auto-merge armed).                            |
 | `epic-reconcile.js --explicit-delete`            | Hard reset — close orphaned Epic-scoped issues per `.agents/epics/<id>.yaml`                                                                                                 |

package/.agents/docs/configuration.md

@@ -748,8 +748,8 @@ number of keys.
 | `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json` | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
 | `delivery.worktreeIsolation.nodeModulesStrategy`     | `per-worktree`                        | `per-worktree`                             | npm-only repo (`package-lock.json`); worktree init runs `npm ci` per tree.                                                       |
 
-When a consumer runs `/agents-update`, the
-[`agents-sync-config`](../workflows/helpers/agents-sync-config.md)
+When a consumer runs `/mandrel-update`, the
+[`mandrel-sync-config`](../workflows/helpers/mandrel-sync-config.md)
 helper validates the project config against the schema, then adds any
 template-introduced keys the project does not already define. Project-side
 values that validate are preserved unconditionally — including optional keys
@@ -821,10 +821,10 @@ project-specific knob:
 1. Confirm the key is **already declared in the schema** at
    [`.agents/schemas/agentrc.schema.json`](../schemas/agentrc.schema.json)
    — if it isn't, the AJV validators will reject it on the next
-   `/agents-update`.
+   `/mandrel-update`.
 2. Set the key in `.agentrc.json`. Don't add it to the template unless it
    should ship to all consumers.
-3. Run `/agents-update` to confirm the helper preserves the key on round-trip.
+3. Run `/mandrel-update` to confirm the helper preserves the key on round-trip.
 
 ### Extending list-valued keys without losing template defaults
 
@@ -898,7 +898,7 @@ This is a framework-level change, not a project-level one. The path is:
    [`config-resolver.js`](../scripts/lib/config-resolver.js).
 4. Add tests under `tests/lib/config-*.test.js` and confirm
    `tests/config-schema-mirror-drift.test.js` passes.
-5. Document the key in this file and update `agents-sync-config.md` only if
+5. Document the key in this file and update `mandrel-sync-config.md` only if
    the merge semantics differ from the default (project-wins) rule.
 
 ---
@@ -979,10 +979,10 @@ allowlists drift project-to-project.
 
 ### Cadence
 
-Run `/fewer-permission-prompts` **once per `/agents-update`
+Run `/fewer-permission-prompts` **once per `/mandrel-update`
 invocation**, immediately after the package upgrade re-materializes
 `.agents/` and before the bump commit lands. The cadence is codified in
-[`/agents-update` Step 3.6](../workflows/agents-update.md). The
+[`/mandrel-update` Step 3.6](../workflows/mandrel-update.md). The
 operator who just bumped `.agents/` has the freshest transcript context
 in the active session, which is exactly what the skill scans, so this
 is the cheapest time to surface new high-frequency calls.
@@ -1024,7 +1024,7 @@ on the next cadence run if they remain high-frequency, so the cost of
 deferral is bounded.
 
 Stage the accepted `.claude/settings.json` diff alongside the
-`/agents-update` bump commit so the reviewer sees the framework pointer
+`/mandrel-update` bump commit so the reviewer sees the framework pointer
 move and the allowlist response in the same diff.
 
 ---
@@ -1093,7 +1093,7 @@ mandrel uninstall --include-github # acknowledge GitHub-side follow-ups
 - Resolver entry point —
   [`config-resolver.js`](../scripts/lib/config-resolver.js)
 - Sync helper —
-  [`agents-sync-config.md`](../workflows/helpers/agents-sync-config.md)
+  [`mandrel-sync-config.md`](../workflows/helpers/mandrel-sync-config.md)
 - Bootstrap script —
   [`bootstrap.js`](../scripts/bootstrap.js)
 - Quality gates runbook (CRAP onboarding, MI ratchet, lint ratchet) —

package/.agents/docs/workflows.md

@@ -25,11 +25,10 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (27)
+## Commands (25)
 
 | Command | Description |
 | --- | --- |
-| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/audit-architecture` | Audit architectural boundaries, module coupling, and layering violations; emit a structured findings report keyed to High/Medium/Low severity. |
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
@@ -48,11 +47,10 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/deliver` | Unified delivery entry point. Inspects the ticket type(s) and Epic-reference state of the supplied IDs, composes a sequential segment plan over any mix of Epics and standalone Stories, then delegates each segment to the Epic wave loop or the standalone multi-Story fan-out — preserving every flag and the parallel-delivery contract of the retired commands. |
 | `/explain` | Walk the operator through a code change until they genuinely understand it. Targets a PR, a branch, or the working-tree diff, then drives the `core/knowledge-transfer` skill (restate-first, why-ladder, mastery gates, persistent checklist) with an operator-controlled stop at every checkpoint. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
-| `/git-commit-all` | Stage every untracked and modified file, then create a single conventional-commit on the current branch (no push). |
+| `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/git-merge-pr` | Analyze, validate, resolve conflicts, and merge a given pull request by number. |
-| `/git-pr-all` | Stage all outstanding changes, commit, push to a feature branch, and open a pull request with native auto-merge enabled. |
-| `/git-push` | Commit all outstanding changes then push to the remote repository. |
+| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
-| `/qa-run-harness` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |
+| `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |

package/.agents/schemas/qa-finding.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "QaFinding",
-  "description": "Structured `F#` finding emitted by the agent-driven QA harness (`.agents/workflows/qa-run-harness.md`, Epic #3214). One object per genuine problem surfaced while sweeping a consumer's Gherkin scenarios through chrome-devtools MCP: a non-allowlisted console error, a failed/error-status network request, or a gross design-token violation. Findings are validated against this schema before they are bundled by likely root cause into operator-approved follow-up ticket drafts (the harness never files tickets autonomously). The shape mirrors the F# convergence in Tech Spec #3285 and is produced in its console-derived subset by `.agents/scripts/lib/qa/console-allowlist.js`.",
+  "description": "Structured `F#` finding emitted by the agent-driven QA harness (`.agents/workflows/qa-run.md`, Epic #3214). One object per genuine problem surfaced while sweeping a consumer's Gherkin scenarios through chrome-devtools MCP: a non-allowlisted console error, a failed/error-status network request, or a gross design-token violation. Findings are validated against this schema before they are bundled by likely root cause into operator-approved follow-up ticket drafts (the harness never files tickets autonomously). The shape mirrors the F# convergence in Tech Spec #3285 and is produced in its console-derived subset by `.agents/scripts/lib/qa/console-allowlist.js`.",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/.agents/scripts/apply-quality-bootstrap.js

@@ -2,11 +2,11 @@
 
 /**
  * apply-quality-bootstrap.js — Story #4171
- * (refactor(agents-update): extract the quality-bootstrap heredoc into a
+ * (refactor(mandrel-update): extract the quality-bootstrap heredoc into a
  * tested script)
  *
  * Replaces the inline `node -e "Promise.all([...])"` heredoc that Step 3.5 of
- * the `/agents-update` workflow used to carry. That shape was fragile in three
+ * the `/mandrel-update` workflow used to carry. That shape was fragile in three
  * ways: it broke across shells (PowerShell vs bash quoting / backticks), it
  * had no test so it silently drifted when the two helper signatures moved, and
  * it could not be invoked or dry-run independently.

package/.agents/scripts/lib/bootstrap/ci-workflow-template.js

@@ -180,7 +180,7 @@ export const CI_WORKFLOW_RELATIVE_PATH = '.github/workflows/ci.yml';
  * `unchanged`. When the file is absent the action is `created`. When the
  * file exists with operator-authored differences the helper preserves it
  * and returns `custom-workflow-skip` along with the rendered body so the
- * bootstrap caller (or `/agents-update`) can offer a side-by-side diff.
+ * bootstrap caller (or `/mandrel-update`) can offer a side-by-side diff.
  *
  * Network-free; safe to invoke under tests with a tmp `projectRoot`.
  *

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -242,7 +242,7 @@ export function ensureQualityNpmScripts(ctx) {
  * underneath the project config at read time, so a key whose intended
  * value equals the framework default would be written redundantly — and
  * would then be flagged `[REDUNDANT]` by the sync-agentrc helper on the
- * next /agents-update. Default-aware seeding keeps the two helpers from
+ * next /mandrel-update. Default-aware seeding keeps the two helpers from
  * contradicting each other.
  *
  * Returns `{ merged, addedKeys[] }` so the caller can report exactly

package/.agents/scripts/lib/config/defaults.js

@@ -9,7 +9,7 @@
  * (tests/config/full-agentrc-runtime-parity.test.js) keeps the two in
  * lockstep.
  *
- * Story #1995: the `/agents-update` sync helper consults this module
+ * Story #1995: the `/mandrel-update` sync helper consults this module
  * (not the template directly) to decide whether a project value is
  * "just the default" and therefore safe to omit from `.agentrc.json`.
  *

package/.agents/scripts/lib/config/sync-agentrc.js

@@ -16,7 +16,7 @@
  *      untouched. Operators who want a leaner config can prune the
  *      redundant keys by hand.
  *
- * Outcome: after `/agents-update`, `.agentrc.json` contains only keys
+ * Outcome: after `/mandrel-update`, `.agentrc.json` contains only keys
  * that materially diverge from framework defaults, plus the
  * consumer-identity keys with no sensible framework default (owner,
  * repo, operatorHandle).

package/.agents/scripts/lib/config-resolver.js

@@ -199,7 +199,7 @@ function applyDefaults(raw) {
     // `#/$defs/qa`). It needs no default-layering — the harness resolver
     // (`resolveQaContract`) owns normalization and required-field
     // enforcement — it only needs to survive the reshape so
-    // `/qa-run-harness` Step 0 can read it off the resolved wrapper.
+    // `/qa-run` Step 0 can read it off the resolved wrapper.
     ...(raw.qa !== undefined ? { qa: raw.qa } : {}),
   };
 }

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -26,6 +26,15 @@
  * "clean sprint" retro trailer), emit `epic.merge.ready`. Otherwise emit
  * `epic.merge.blocked` with a non-empty reason.
  *
+ * Code-review parse-miss policy (Story #4222): a code-review comment that is
+ * present but whose severity bullets cannot be parsed is treated as a DISTINCT
+ * condition — surfaced via the `codeReviewUnparseable` signal — and FAILS OPEN
+ * rather than blocking. Failing closed on a format miss is indistinguishable,
+ * to the operator and to downstream telemetry, from a real disqualifying
+ * finding; a parser miss must never masquerade as "the signal said no" inside
+ * a generic `epic.merge.blocked`. Genuine critical/high findings still block,
+ * because those require the counts to have parsed.
+ *
  * Critical contract:
  *   - The verdict for any given input set is byte-identical to the
  *     pre-inlining legacy module's output — this file is its
@@ -229,11 +238,30 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
     : { critical: null, high: null, medium: null, suggestion: null };
   if (!codeReviewFound) {
     reasons.push('code-review structured comment not found on Epic');
-    return { codeReviewFound, severity };
+    return { codeReviewFound, codeReviewUnparseable: false, severity };
   }
-  if (severity.critical === null || severity.high === null) {
-    reasons.push('code-review severity bullets could not be parsed');
-    return { codeReviewFound, severity };
+  // "Present but unparseable" is a DISTINCT condition from "present and says
+  // no" (Story #4222). The canonical renderer
+  // (`review-providers/findings-renderer.js`) always emits all four severity
+  // bullets, so a body whose critical/high counts we cannot extract is a
+  // FORMAT MISS, not a disqualifying signal. Failing closed here — pushing a
+  // generic block reason — is indistinguishable, to the operator and to
+  // downstream telemetry (the mandrel-bench Autonomy dimension), from a real
+  // critical finding: it stalls an otherwise-clean unattended run for a
+  // non-reason.
+  //
+  // Chosen policy: FAIL OPEN on an unparseable code-review body. We surface
+  // the condition explicitly via the `codeReviewUnparseable` signal so
+  // telemetry can tell a parser miss from a true HITL hand-off, but we do NOT
+  // add a disqualifying `reasons[]` entry — the absence of a parseable
+  // critical/high count cannot, on its own, block a run whose other signals
+  // are clean. Genuine disqualifying review findings (critical > 0 /
+  // high > 0) still block below, because those require the counts to have
+  // parsed successfully.
+  const codeReviewUnparseable =
+    severity.critical === null || severity.high === null;
+  if (codeReviewUnparseable) {
+    return { codeReviewFound, codeReviewUnparseable, severity };
   }
   if (severity.critical > 0) {
     reasons.push(`code-review has ${severity.critical} 🔴 Critical Blocker(s)`);
@@ -241,7 +269,7 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
   if (severity.high > 0) {
     reasons.push(`code-review has ${severity.high} 🟠 High Risk finding(s)`);
   }
-  return { codeReviewFound, severity };
+  return { codeReviewFound, codeReviewUnparseable, severity };
 }
 
 function evaluateRetroSignals(retro, reasons) {
@@ -287,6 +315,7 @@ function evaluateRetroSignals(retro, reasons) {
  *     storyStatuses: string[],
  *     storyBlockers: number,
  *     severity: { critical: number|null, high: number|null, medium: number|null, suggestion: number|null },
+ *     codeReviewUnparseable: boolean,
  *     retroCompact: boolean,
  *     codeReviewFound: boolean,
  *     retroFound: boolean,
@@ -308,6 +337,7 @@ export function deriveAutoMergeVerdict({ state, codeReview, retro }) {
       storyStatuses: stateSig.storyStatuses,
       storyBlockers: stateSig.storyBlockers,
       severity: reviewSig.severity,
+      codeReviewUnparseable: reviewSig.codeReviewUnparseable,
       retroCompact: retroSig.retroCompact,
       codeReviewFound: reviewSig.codeReviewFound,
       retroFound: retroSig.retroFound,

package/.agents/scripts/lib/qa/qa-context-hydrator.js

@@ -1,7 +1,7 @@
 /**
  * QA context hydrator — Story #3805, Epic #3798 (f1-shared-qa-core).
  *
- * Both QA front-ends (`/qa-explore` and `/qa-run-harness`) need to load the
+ * Both QA front-ends (`/qa-explore` and `/qa-run`) need to load the
  * *grounded* surface context for an Epic before they reason about what to test:
  * the Epic body, its linked context tickets (PRD / Tech Spec / Acceptance
  * Spec), the project's `.feature` files, the implementation files the surface

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -1,7 +1,7 @@
 /**
  * `qa` contract resolver — Epic #3214, Story #3294.
  *
- * The agent-driven QA harness (`/qa-run-harness`) needs the
+ * The agent-driven QA harness (`/qa-run`) needs the
  * consumer's `.agentrc.json` `qa` block to know where the `.feature` root
  * lives, how to sign in, and which personas the seam accepts. The block is
  * *optional in the schema* (most repos never bind the harness, so config

package/.agents/scripts/{agents-update-preflight.js → mandrel-update-preflight.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * agents-update-preflight.js — Story #4170
- * (feat(agents-update): add a first-run preflight before the updater)
+ * mandrel-update-preflight.js — Story #4170
+ * (feat(mandrel-update): add a first-run preflight before the updater)
  *
- * A first-run preflight for the `/agents-update` workflow. The workflow
+ * A first-run preflight for the `/mandrel-update` workflow. The workflow
  * otherwise jumps straight to `npx mandrel update` with no guard rails;
  * this preflight catches three day-0 failure modes *before* the version
  * bump:
@@ -33,7 +33,7 @@
  * `lib/cli/update.js` itself — the CLI stays git-free and
  * side-effect-scoped; this is a workflow-layer concern.
  *
- * The detection logic is a pure function (`runAgentsUpdatePreflight`) that
+ * The detection logic is a pure function (`runMandrelUpdatePreflight`) that
  * takes injectable probes so it is unit-testable without touching the real
  * filesystem, git index, or network. The CLI wrapper wires the real probes
  * and maps a blocker finding to a non-zero exit code.
@@ -128,7 +128,7 @@ export function makeProbes(projectRoot) {
  *   consumer-shape hard stop). `ok` is true when there are no findings of
  *   any severity.
  */
-export function runAgentsUpdatePreflight({ probes }) {
+export function runMandrelUpdatePreflight({ probes }) {
   /** @type {PreflightFinding[]} */
   const findings = [];
 
@@ -153,7 +153,7 @@ export function runAgentsUpdatePreflight({ probes }) {
     findings.push({
       id: 'consumer-shape',
       severity: 'blocker',
-      summary: `Not a Mandrel consumer project (${missing.join('; ')}). Run /agents-update from a consumer repo that depends on "mandrel" and has a materialized .agents/ tree — not the framework repo itself or an unrelated project.`,
+      summary: `Not a Mandrel consumer project (${missing.join('; ')}). Run /mandrel-update from a consumer repo that depends on "mandrel" and has a materialized .agents/ tree — not the framework repo itself or an unrelated project.`,
       fix: 'cd into the consumer project root, or run `npm install -D mandrel && npx mandrel sync` to bootstrap one.',
     });
   }
@@ -194,7 +194,7 @@ export function runAgentsUpdatePreflight({ probes }) {
 export function reportPreflight(result, logger) {
   if (result.ok) {
     logger.info(
-      '✅ [agents-update-preflight] All checks passed — safe to run `npx mandrel update`.',
+      '✅ [mandrel-update-preflight] All checks passed — safe to run `npx mandrel update`.',
     );
     return;
   }
@@ -208,11 +208,11 @@ export function reportPreflight(result, logger) {
   }
   if (result.blocked) {
     logger.error(
-      '[agents-update-preflight] Hard stop: do not run `npx mandrel update` until the blocker above is resolved (exit 2).',
+      '[mandrel-update-preflight] Hard stop: do not run `npx mandrel update` until the blocker above is resolved (exit 2).',
     );
   } else {
     logger.warn(
-      '[agents-update-preflight] Warnings only — review them, then proceed if intentional.',
+      '[mandrel-update-preflight] Warnings only — review them, then proceed if intentional.',
     );
   }
 }
@@ -220,7 +220,7 @@ export function reportPreflight(result, logger) {
 async function main() {
   const projectRoot = process.cwd();
   const probes = makeProbes(projectRoot);
-  const result = runAgentsUpdatePreflight({ probes });
+  const result = runMandrelUpdatePreflight({ probes });
   reportPreflight(result, Logger);
   // Machine-parsable JSON envelope on stdout for tooling / the workflow to
   // read. Use process.stdout.write (not console.log) per the no-console
@@ -230,6 +230,6 @@ async function main() {
 }
 
 runAsCli(import.meta.url, main, {
-  source: 'agents-update-preflight',
+  source: 'mandrel-update-preflight',
   propagateExitCode: true,
 });

package/.agents/scripts/sync-agentrc.js

@@ -4,8 +4,8 @@
  * sync-agentrc.js — default-aware `.agentrc.json` reconciliation (Story #1995).
  *
  * Replaces the manual procedure formerly described in
- * `.agents/workflows/helpers/agents-sync-config.md`. Invoked by
- * `/agents-update` Step 3 after the package upgrade re-materializes `.agents/`.
+ * `.agents/workflows/helpers/mandrel-sync-config.md`. Invoked by
+ * `/mandrel-update` Step 3 after the package upgrade re-materializes `.agents/`.
  *
  * Contract:
  *   - Validates the project config against the framework schema. On

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-16T00:37:23.856Z",
+  "generatedAt": "2026-06-16T16:35:27.286Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -577,7 +577,7 @@
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-harness/SKILL.md",
-      "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run-harness` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run-harness.md`; this skill is the conventions reference it leans on.",
+      "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run.md`; this skill is the conventions reference it leans on.",
       "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": null

package/.agents/skills/stack/qa/playwright-bdd/SKILL.md

@@ -71,7 +71,7 @@ authoring.
   single `defineBddConfig` block that lists `features` and `steps` paths.
 - Register the Cucumber HTML/JSON reporter alongside the Playwright HTML
   reporter so a headless CI invocation emits machine-readable evidence
-  alongside the agent-driven `/qa-run-harness` sweep.
+  alongside the agent-driven `/qa-run` sweep.
 - Use Playwright projects (not Cucumber profiles) for browser matrix fan-out —
   keeps sharding, retries, and trace config in one place.
 
@@ -99,7 +99,7 @@ authoring.
   tag vocabularies in the runner config; extend via `@domain-*` only.
 - Wire tag-filtered headless runs to a single npm script so operators never
   reconstruct the generate-then-run sequence by hand; the agent-driven
-  `/qa-run-harness` selector mirrors the same tag expressions for browser sweeps.
+  `/qa-run` selector mirrors the same tag expressions for browser sweeps.
 - Fail the run if generation produces zero matching scenarios — a silent empty
   suite is worse than a red build.
 
@@ -184,5 +184,5 @@ those outcomes.
 
 - Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
 - Browser-level conventions: `.agents/skills/stack/qa/playwright/SKILL.md`.
-- Operator entry point: `.agents/workflows/qa-run-harness.md`.
+- Operator entry point: `.agents/workflows/qa-run.md`.
 - Evidence handoff: `.agents/workflows/helpers/epic-testing.md`.

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -2,11 +2,11 @@
 name: qa-harness
 description:
   Conventions for the agent-driven QA harness that drives Gherkin scenarios
-  through a real browser. Use when executing `/qa-run-harness` or instrumenting
+  through a real browser. Use when executing `/qa-run` or instrumenting
   a live surface — covers navigation-first execution, per-surface console and
   network capture, design-token visual checks, and the framework-generic
   heuristic cards for turning signal into findings. The harness procedure lives
-  in `.agents/workflows/qa-run-harness.md`; this skill is the conventions
+  in `.agents/workflows/qa-run.md`; this skill is the conventions
   reference it leans on.
 ---
 
@@ -26,7 +26,7 @@ description:
 Guidance for executing the agent-driven QA harness through a real browser (the
 chrome-devtools MCP surface). The harness **procedure** — argument parsing,
 step ordering, contract resolution sequence — is the SSOT in
-[`.agents/workflows/qa-run-harness.md`](../../../../workflows/qa-run-harness.md);
+[`.agents/workflows/qa-run.md`](../../../../workflows/qa-run.md);
 this skill shows **how** to apply the instrumentation and inspection
 conventions that procedure depends on. The assertion-tier rules it enforces
 live in [`testing-standards.md`](../../../../rules/testing-standards.md)
@@ -212,7 +212,7 @@ QA evidence ticket.
 
 ## 7. Cross-References
 
-- Run procedure (SSOT): [`qa-run-harness.md`](../../../../workflows/qa-run-harness.md).
+- Run procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
 - Console filter module: [`console-allowlist.js`](../../../../scripts/lib/qa/console-allowlist.js).
 - Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).
 - Scenario prose: [`gherkin-authoring`](../gherkin-authoring/SKILL.md).