npm - mandrel - Versions diffs - 2.7.0 → 2.9.0 - Mend

mandrel 2.7.0 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (95) hide show

package/.agents/README.md +104 -330
package/.agents/agents/auditor.md +135 -0
package/.agents/agents/plan-critic.md +80 -0
package/.agents/audit-checklists/dependencies.md +7 -0
package/.agents/audit-checklists/documentation.md +1 -0
package/.agents/docs/SDLC.md +69 -162
package/.agents/docs/configuration.md +159 -499
package/.agents/docs/quality-gates.md +59 -180
package/.agents/instructions.md +170 -295
package/.agents/rules/changelog-style.md +8 -66
package/.agents/rules/ci-remediation.md +65 -124
package/.agents/rules/gherkin-standards.md +10 -31
package/.agents/rules/git-conventions-reference.md +28 -61
package/.agents/rules/git-conventions.md +1 -1
package/.agents/rules/orchestration-error-handling.md +5 -15
package/.agents/rules/security-baseline.md +7 -13
package/.agents/rules/shell-conventions.md +4 -13
package/.agents/rules/test-seams.md +2 -2
package/.agents/rules/testing-standards.md +7 -17
package/.agents/schemas/agentrc.schema.json +21 -0
package/.agents/scripts/audit-to-stories.js +51 -0
package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js +120 -55
package/.agents/scripts/lib/config-settings-schema.js +32 -0
package/.agents/scripts/lib/findings/semantic-issue-search.js +43 -5
package/.agents/scripts/lib/observability/terse-result.js +114 -0
package/.agents/scripts/lib/orchestration/complexity-gate.js +207 -0
package/.agents/scripts/lib/orchestration/plan-context.js +3 -0
package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +221 -8
package/.agents/scripts/lib/orchestration/single-story-close/runner.js +55 -14
package/.agents/scripts/lib/orchestration/story-close/emit-blocked.js +9 -3
package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +4 -1
package/.agents/scripts/lib/orchestration/task-body-validator.js +13 -40
package/.agents/scripts/lib/story-body/body-format-lints.js +215 -0
package/.agents/scripts/lib/story-body/story-body.js +18 -2
package/.agents/scripts/lib/templates/decomposer-prompts.js +16 -0
package/.agents/scripts/providers/github/issues.js +54 -7
package/.agents/scripts/providers/github/search-budget.js +124 -0
package/.agents/scripts/providers/github/search-query.js +71 -0
package/.agents/scripts/single-story-confirm-merge.js +14 -5
package/.agents/scripts/single-story-init.js +19 -3
package/.agents/scripts/sync-branch-from-base.js +9 -3
package/.agents/skills/core/api-and-interface-design/SKILL.md +23 -297
package/.agents/skills/core/api-and-interface-design/reference.md +76 -0
package/.agents/skills/core/browser-testing-with-devtools/SKILL.md +20 -327
package/.agents/skills/core/browser-testing-with-devtools/reference.md +74 -0
package/.agents/skills/core/code-review-and-quality/reference.md +16 -398
package/.agents/skills/core/debugging-and-error-recovery/reference.md +14 -281
package/.agents/skills/core/documentation-and-adrs/reference.md +42 -338
package/.agents/skills/core/git-workflow-and-versioning/SKILL.md +28 -326
package/.agents/skills/core/idea-refinement/SKILL.md +67 -193
package/.agents/skills/core/security-and-hardening/SKILL.md +15 -31
package/.agents/skills/core/security-and-hardening/reference.md +15 -273
package/.agents/skills/skills.index.json +5 -5
package/.agents/skills/stack/qa/gherkin-authoring/SKILL.md +16 -222
package/.agents/skills/stack/qa/gherkin-authoring/reference.md +157 -0
package/.agents/skills/stack/qa/playwright/SKILL.md +0 -29
package/.agents/skills/stack/qa/qa-explore-driving/SKILL.md +19 -23
package/.agents/skills/stack/qa/qa-harness/SKILL.md +35 -53
package/.agents/skills/stack/qa/vitest/SKILL.md +0 -29
package/.agents/workflows/audit-accessibility.md +34 -108
package/.agents/workflows/audit-architecture.md +35 -123
package/.agents/workflows/audit-clean-code.md +19 -78
package/.agents/workflows/audit-data-model.md +32 -100
package/.agents/workflows/audit-dependencies.md +47 -111
package/.agents/workflows/audit-devops.md +16 -83
package/.agents/workflows/audit-documentation.md +46 -93
package/.agents/workflows/audit-navigability.md +26 -80
package/.agents/workflows/audit-performance.md +40 -106
package/.agents/workflows/audit-privacy.md +17 -80
package/.agents/workflows/audit-quality.md +35 -99
package/.agents/workflows/audit-security.md +20 -78
package/.agents/workflows/audit-seo.md +20 -98
package/.agents/workflows/audit-sre.md +20 -88
package/.agents/workflows/audit-to-stories.md +1 -8
package/.agents/workflows/audit-ux-ui.md +17 -80
package/.agents/workflows/deliver.md +54 -9
package/.agents/workflows/git-cleanup.md +50 -275
package/.agents/workflows/helpers/audit-lens-core.md +230 -0
package/.agents/workflows/helpers/code-review.md +11 -23
package/.agents/workflows/helpers/deliver-story-reference.md +114 -17
package/.agents/workflows/helpers/deliver-story.md +36 -186
package/.agents/workflows/helpers/qa-core.md +174 -0
package/.agents/workflows/helpers/qa-run-scenario-reference.md +35 -0
package/.agents/workflows/helpers/qa-run-scenario.md +11 -25
package/.agents/workflows/helpers/worktree-lifecycle.md +6 -67
package/.agents/workflows/mandrel-update.md +7 -13
package/.agents/workflows/plan.md +44 -17
package/.agents/workflows/qa-assist.md +140 -269
package/.agents/workflows/qa-explore.md +125 -316
package/.agents/workflows/qa-run.md +180 -380
package/docs/CHANGELOG.md +30 -0
package/package.json +1 -1
package/.agents/workflows/helpers/audit-dual-path.md +0 -59
package/.agents/workflows/helpers/audit-self-check.md +0 -70
package/.agents/workflows/helpers/audit-severity-scale.md +0 -19

package/.agents/workflows/audit-seo.md CHANGED Viewed

@@ -4,6 +4,19 @@ description: Audit SEO fundamentals and Generative Engine Optimization signals (
 # SEO & Generative Engine Optimization Audit
+You are a Senior Technical SEO & Generative Engine Optimization (GEO) Specialist
+(semantic HTML, JSON-LD Schema, Core Web Vitals) surfacing structural, semantic,
+and content-level improvements that increase discoverability in both traditional
+search indexes and AI answer engines. The shared lens machinery — read-only
+constraint, scope interpretation, report envelope + finding-block skeleton,
+severity scale, self-cross-check, and execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-seo-results.md`. Each finding carries a **Category:**
+(`SEO | GEO | Core Web Vitals | Crawlability`); the report adds a **Detailed
+Audit Table** (an at-a-glance index — not machine-parsed; every row MUST also
+have a full Detailed Findings entry) and a **GEO-Specific Recommendations**
+section.
 ## Applicability
 **Web targets only.** This lens is registered with `target: "web"` in
@@ -14,40 +27,19 @@ checkout (configured navigability `routeGlobs`, a declared web-framework
 dependency, or a tracked `.html` / `.css` / `.jsx` / `.tsx` source file), not
 from an `.agentrc` key, and the probe fails open when indeterminate.
-## Role
-Senior Technical SEO and Generative Engine Optimization (GEO) Specialist. You
-are an expert in semantic HTML, JSON-LD Schema markup, Core Web Vitals, and
-optimizing content structure for both traditional search engines (Google, Bing)
-and Large Language Models (ChatGPT, Perplexity, Gemini).
-## Context & Objective
-You are performing a comprehensive, read-only SEO and GEO audit of this
-codebase. Your goal is to surface structural, semantic, and content-level
-improvements that will increase discoverability in both traditional search
-indexes and AI-powered answer engines — without making any immediate changes.
+## Scope
-## Scope (Story / plan-run mode)
-When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
-following block is populated with the Story (or plan-run) change-set file list.
-Otherwise — for any manual `/audit-<dimension>` invocation — the block
-renders the literal substitution token and you MUST treat it as **no
-scope filter — run the lens codebase-wide** exactly as you would have
-before this section existed.
+Interpret this lens's change-set fence per the core's Scope interpretation:
 ```text
 {{changedFiles}}
 ```
-- If the block above contains a newline-delimited list of file paths,
-  restrict your analysis to those files (and their direct dependencies
-  when the lens explicitly calls for cross-file reasoning).
-- If the block above renders as the literal string `{{changedFiles}}`
-  (i.e. no substitution was supplied), ignore this section entirely and
-  proceed with the full codebase-wide scan defined in the remaining
-  steps.
+## Execution strategy
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy).
 ## Step 0: Indexability gate (run first)
@@ -67,8 +59,6 @@ a login-gated dashboard is *supposed* to be invisible to crawlers, so a missing
 ## Step 1: Framework-aware metadata detection matrix
-> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
 Modern web consumers almost never ship literal `<head><meta></head>` HTML — the
 metadata is produced by a framework mechanism. **Identify the mechanism first,
 then probe the surfaces that mechanism uses.** Reporting "no `<meta>` tags found"
@@ -113,71 +103,3 @@ Evaluate the gathered context against the following dimensions:
 4. **Crawlability:** `robots.txt`, `sitemap.xml` (including generated
    `sitemap.*`/`robots.*` route handlers), and any `noindex` directives that may
    unintentionally block indexable pages.
-## Step 3: Output Requirements
-Generate and save a highly structured Markdown audit report to
-`{{auditOutputDir}}/audit-seo-results.md`, using the exact template below.
-> Grade every finding's severity on the shared
-> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
-```markdown
-# SEO & GEO Audit Report
-## Executive Summary
-[A high-level view of the site's current optimization health, highlighting the
-primary gaps and the most impactful opportunities.]
-## Detailed Audit Table
-[A supplementary at-a-glance index only. Every row MUST also have a full
-`## Detailed Findings` entry below — the Detailed Findings blocks are the
-machine-parsed source of record; this table is not parsed.]
-| Issue               | Impact                      | Category   | Suggested Fix |
-| ------------------- | --------------------------- | ---------- | ------------- |
-| [Issue description] | Critical / High / Med / Low | SEO or GEO | [Brief fix]   |
-## GEO-Specific Recommendations
-[Specific advice on how to make this codebase more readable for AI models —
-e.g., adding specific Schema types, flattening nested DOM structures, or
-reformatting key content as FAQ blocks.]
-## Detailed Findings
-[Mandatory: emit one entry per issue in the Detailed Audit Table above, using
-the following strict structure. Lead each title with the primary file the
-finding lives in:]
-### `path/to/primary-file.ext` — [Short title of the issue]
-- **Category:** [SEO | GEO | Core Web Vitals | Crawlability]
-- **Impact:** [Critical | High | Medium | Low]
-- **Location:** `path/to/primary-file.ext:line`
-- **Current State:** [What exists in the codebase and why it's suboptimal]
-- **Recommendation & Rationale:** [The specific fix and how it improves
-  discoverability or LLM retrieval]
-- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the meta tag now present in the rendered head, or a re-run of this lens]
-- **Agent Prompt:**
-  `[A copy-pasteable, highly specific prompt to execute this fix independently]`
-```
----
-## Constraint
-Do NOT rewrite or modify any files. Do NOT implement the changes. Focus strictly
-on analyzing the code. Output the report and stop.
-## Self-cross-check (mandatory — filter false positives before you finalize)
-Before you write the report artifact from the previous step, run the shared
-adversarial self-cross-check over your Detailed Findings — see
-[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
-per-finding evidence bar, the exclusion list, and the final re-open-and-drop
-pass whose `kept <k> / dropped <d>` counts you record in the Executive
-Summary, so the sequential single-pass path filters unverified findings just as
-the orchestrated path's adversarial reviewer does.

package/.agents/workflows/audit-sre.md CHANGED Viewed

@@ -4,42 +4,33 @@ description: "Audit production-readiness for a release candidate: SLOs, observab
 # Production Release Candidate Audit
-## Role
-Senior Site Reliability Engineer (SRE) & Lead Developer
-## Context & Objective
-You are conducting a rigorous, read-only operational-readiness audit for a
-production release candidate. Your goal is to surface critical risks across
-rollback & recovery paths, observability & instrumentation, resilience &
-failure handling, and runbooks & operational docs — providing a prioritized,
-actionable report that can be handed off for remediation before deployment.
-## Scope (Story / plan-run mode)
-When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
-following block is populated with the Story (or plan-run) change-set file list.
-Otherwise — for any manual `/audit-<dimension>` invocation — the block
-renders the literal substitution token and you MUST treat it as **no
-scope filter — run the lens codebase-wide** exactly as you would have
-before this section existed.
+You are a Senior SRE & Lead Developer running an operational-readiness audit for
+a production release candidate — rollback & recovery paths, observability &
+instrumentation, resilience & failure handling, and runbooks & operational
+docs. The shared lens machinery — read-only constraint, scope interpretation,
+report envelope + finding-block skeleton, severity scale, self-cross-check, and
+execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-sre-results.md`. Each finding carries a **Category:**
+(`Rollback & Recovery | Observability | Resilience | Runbooks`); the report adds
+a **Release Readiness Checklist** table (per-category ✅ Clear / ⚠️ Issues
+Found).
+## Scope
+Interpret this lens's change-set fence per the core's Scope interpretation:
 ```text
 {{changedFiles}}
 ```
-- If the block above contains a newline-delimited list of file paths,
-  restrict your analysis to those files (and their direct dependencies
-  when the lens explicitly calls for cross-file reasoning).
-- If the block above renders as the literal string `{{changedFiles}}`
-  (i.e. no substitution was supplied), ignore this section entirely and
-  proceed with the full codebase-wide scan defined in the remaining
-  steps.
+## Execution strategy
-## Step 1: Resilience Detection Battery (Read-Only, Tool-First)
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy).
-> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
+## Step 1: Resilience Detection Battery (Read-Only, Tool-First)
 This lens audits **operational readiness** — can this release be observed,
 survive failure, and be rolled back? It deliberately does **not** re-audit
@@ -111,62 +102,3 @@ Evaluate the release candidate against these **production-readiness** criteria.
   wired into the orchestrator so a bad rollout is caught before it takes
   traffic?
 - **On-Call Escalation:** Is ownership / escalation for this surface documented?
-## Step 3: Output Requirements
-Generate and save a highly structured Markdown audit report to
-`{{auditOutputDir}}/audit-sre-results.md`, using the exact template below.
-> Grade every finding's severity on the shared
-> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
-```markdown
-# Production Release Candidate Audit
-## Executive Summary
-[A brief overview of the release candidate's health. Highlight the most critical
-risks that must be resolved before deployment.]
-## Detailed Findings
-[Group findings by the categories below. Use this structure for each item.
-Lead each title with the primary file the finding lives in:]
-### `path/to/primary-file.ext` — [Short title of the issue]
-- **Category:** [Rollback & Recovery | Observability | Resilience | Runbooks]
-- **Severity:** [Critical | High | Medium | Low]
-- **Location:** `path/to/primary-file.ext:line`
-- **Current State:** [What exists and why it's a risk]
-- **Recommendation:** [The specific fix and rationale]
-- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. `npm test`, a grep that now returns empty, or a re-run of this lens]
-- **Agent Prompt:**
-  `[A copy-pasteable, highly specific prompt to execute this fix independently]`
-## Release Readiness Checklist
-| Category             | Status                     |
-| -------------------- | -------------------------- |
-| Rollback & Recovery  | ✅ Clear / ⚠️ Issues Found |
-| Observability        | ✅ Clear / ⚠️ Issues Found |
-| Resilience           | ✅ Clear / ⚠️ Issues Found |
-| Runbooks             | ✅ Clear / ⚠️ Issues Found |
-```
----
-## Constraint
-Do NOT generate code fixes, edit files, or create branches. This is strictly a
-read-only analysis. Output the report and stop.
-## Self-cross-check (mandatory — filter false positives before you finalize)
-Before you write the report artifact from the previous step, run the shared
-adversarial self-cross-check over your Detailed Findings — see
-[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
-per-finding evidence bar, the exclusion list, and the final re-open-and-drop
-pass whose `kept <k> / dropped <d>` counts you record in the Executive
-Summary, so the sequential single-pass path filters unverified findings just as
-the orchestrated path's adversarial reviewer does.

package/.agents/workflows/audit-to-stories.md CHANGED Viewed

@@ -19,12 +19,6 @@ report under `temp/audits/`. Every `### Finding` block in those reports
 already carries the fields a Story body needs (Severity / Impact,
 Dimension / Category, Current State, Recommendation, Agent Prompt).
-`/audit-to-stories` closes the loop: it parses those reports, groups
-related findings (including across audit dimensions), classifies each
-group as eligible-to-create or already-tracked, and — at the operator's
-choice — either chains into `/plan --seed-file` for a planned Story
-(or N>1 under the split policy) or opens standalone Stories directly.
 The audit producers themselves are **not modified** by this workflow.
 They remain read-only emitters of audit reports.
@@ -295,8 +289,7 @@ and prints a run-summary JSON (create / skip-open / skip-reoccurring /
 suppressed-by-ledger tallies, plus the re-detected open Issue numbers an
 operator may want a "re-detected" comment on). `--dry-run` performs zero GitHub
 writes and skips the ledger write, emitting only the summary. The host
-scheduler owns the cadence; this workflow owns the routing. (This paragraph
-folds in the `loops/nightly-audit.md` starter unit retired in issue 4482.)
+scheduler owns the cadence; this workflow owns the routing.
 ## See also

package/.agents/workflows/audit-ux-ui.md CHANGED Viewed

@@ -4,6 +4,16 @@ description: Audit UX/UI consistency and design system adherence
 # UX/UI & Design System Audit
+You are a Lead Product Designer & Frontend Architect evaluating the frontend for
+UI consistency, UX best practices, and adherence to the project's design system,
+ensuring the app feels premium and cohesive. The shared lens machinery —
+read-only constraint, scope interpretation, report envelope + finding-block
+skeleton, severity scale, self-cross-check, and execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-ux-ui-results.md`. Dimension values:
+`Visual Consistency | UX Best Practices | Accessibility`; the report adds a
+**Micro-animation Opportunities** section.
 ## Applicability
 **Web targets only.** Registered with `target: "web"` in
@@ -11,36 +21,19 @@ description: Audit UX/UI consistency and design system adherence
 on a project with no rendered frontend. See the `target` key's schema
 description for how applicability is probed from the consumer's checkout.
-## Role
-Lead Product Designer & Frontend Architect
-## Context & Objective
+## Scope
-Evaluate the frontend implementation for UI consistency, UX best practices, and
-adherence to the project's design system. Ensure the application feels premium
-and cohesive.
-## Scope (Story / plan-run mode)
-When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
-following block is populated with the Story (or plan-run) change-set file list.
-Otherwise — for any manual `/audit-<dimension>` invocation — the block
-renders the literal substitution token and you MUST treat it as **no
-scope filter — run the lens codebase-wide** exactly as you would have
-before this section existed.
+Interpret this lens's change-set fence per the core's Scope interpretation:
 ```text
 {{changedFiles}}
 ```
-- If the block above contains a newline-delimited list of file paths,
-  restrict your analysis to those files (and their direct dependencies
-  when the lens explicitly calls for cross-file reasoning).
-- If the block above renders as the literal string `{{changedFiles}}`
-  (i.e. no substitution was supplied), ignore this section entirely and
-  proceed with the full codebase-wide scan defined in the remaining
-  steps.
+## Execution strategy
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy).
 ## Step 0: Discover the design-system SSOT (run first)
@@ -66,8 +59,6 @@ ideal. If **no** design-system SSOT exists, say so and downgrade findings to
 ## Step 1: Mechanical detector battery, then LLM triage
-> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
 Run the **mechanical detectors first** (cheap, deterministic greps that surface
 candidates), then apply **LLM triage** to each candidate against the Step 0
 baseline — a mechanical hit is a *candidate*, not automatically a finding.
@@ -107,57 +98,3 @@ baseline — a mechanical hit is a *candidate*, not automatically a finding.
    This lens keeps token/component design-system adherence; defer every WCAG
    success-criterion judgement to the accessibility lens so the two never
    double-report.
-## Step 3: Output Requirements
-Generate and save a highly structured Markdown audit report to
-`{{auditOutputDir}}/audit-ux-ui-results.md`, using the exact template below.
-> Grade every finding's severity on the shared
-> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md).
-```markdown
-# UX/UI & Design System Audit report
-## Executive Summary
-[Overview of design system health (Score 1-10) and adherence to
-tokens/components.]
-## Detailed Findings
-[For every inconsistency or UX improvement identified, use the following strict
-structure. Lead each title with the primary file the finding lives in:]
-### `path/to/primary-file.ext` — [Short title of the issue]
-- **Dimension:** [e.g., Visual Consistency | UX Best Practices | Accessibility]
-- **Impact:** [Critical | High | Medium | Low]
-- **Location:** `path/to/primary-file.ext:line`
-- **Current State:** [What is currently implemented and why it is sub-optimal]
-- **Recommendation & Rationale:** [The specific UI/UX change and how it improves
-  premium feel or usability]
-- **Acceptance signal:** [the command or observable that proves this finding is remediated — e.g. the token now applied in the rendered component, or a re-run of this lens]
-- **Agent Prompt:**
-  `[A copy-pasteable, highly specific prompt to execute this UI change independently]`
-## Micro-animation Opportunities
-- [Suggest 2-3 places where subtle transitions could enhance the "premium"
-  feel.]
-```
-## Constraint
-This is a **read-only** audit. Provide the critique and implementation
-suggestions, but do not modify styles or components.
-## Self-cross-check (mandatory — filter false positives before you finalize)
-Before you write the report artifact from the previous step, run the shared
-adversarial self-cross-check over your Detailed Findings — see
-[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
-per-finding evidence bar, the exclusion list, and the final re-open-and-drop
-pass whose `kept <k> / dropped <d>` counts you record in the Executive
-Summary, so the sequential single-pass path filters unverified findings just as
-the orchestrated path's adversarial reviewer does.

package/.agents/workflows/deliver.md CHANGED Viewed

@@ -34,11 +34,9 @@ Any named ticket that is not `type::story`, or that still carries an
 re-plan as a v2 Story). Resolution refuses the whole set rather than
 silently dropping the offending id and under-delivering.
-> **Retired (Story #4540).** `--run <planRunId>` and the `plan-run::<id>`
-> label are gone, along with `--dep`. Batch identity was the wrong axis:
-> it could not express an edge to a Story planned in another run, while
-> ordering already lives in the dependency edges themselves. Deliver the
-> ids; the graph resolves itself.
+> **No batch identity (Story #4540).** There is no `--run`, `plan-run::<id>`,
+> or `--dep` axis: ordering lives in the dependency edges, so delivering the
+> ids resolves the graph itself.
 ## Flags
@@ -162,11 +160,58 @@ to respect.
      A blocked Story outranks a wedge (its blockers are moot while a human
      owes a decision) but not a cycle (exit 2 — fix the graph first).
-   For each `ready` Story id, read
+   **Dispatch each `ready` Story (role-scoped by default).** When
+   `delivery.routing.roleScopedAgents` is enabled (the **default**) and the
+   host exposes agent dispatch, spawn each ready Story as its own
+   `subagent_type: story-worker` sub-agent — it boots on the role-scoped
+   [`story-worker`](../agents/story-worker.md) context (its own system prompt,
+   no `CLAUDE.md` @-closure) carrying the load-bearing delivery MUSTs
+   standalone. The sub-agent executes
+   [`helpers/deliver-story.md`](helpers/deliver-story.md) end to end
+   (init → implement → acceptance self-eval → close-and-land). Thread into its
+   prompt:
+   - `storyId` — the id to deliver.
+   - `docsDigestPath` — the per-run docs digest (digest-first reading,
+     [`instructions.md` § 3](../instructions.md)); null when
+     `project.docsContextFiles` is unset.
+   - `checklistPath` — the footprint-matched write-time audit checklist,
+     produced at dispatch (below).
+   - the **change-set discipline** — the worker computes the change set once
+     with `computeChangeSet` and hands that one list to every acceptance critic
+     (Story #4593); it never lets a critic re-derive the diff.
+   **Produce `checklistPath` before the spawn (Story #4627).** Compute the
+   payload from the Story's predicted footprint (its `changes[]` /
+   `references[]` path entries) with `buildDispatchChecklist` and write it to
+   the run temp dir, then thread the resulting path (empty when nothing
+   matched):
+   ```bash
+   node --input-type=module -e '
+     import { buildDispatchChecklist } from "<main-repo>/.agents/scripts/lib/audit-suite/index.js";
+     import { parse } from "<main-repo>/.agents/scripts/lib/story-body/story-body.js";
+     // storyBody is the fetched Story issue body.
+     const { changes, references } = parse(process.env.STORY_BODY);
+     const { checklistPath } = buildDispatchChecklist({
+       storyId: <storyId>, changes, references, runTempDir: "temp/run-<id>",
+     });
+     console.log(checklistPath ?? "");
+   '
+   ```
+   `buildDispatchChecklist` (`lib/audit-suite/dispatch-checklist.js`) is a pure
+   function of the footprint and the on-disk checklists; an empty match prints
+   nothing and the worker runs with no write-time checklist — the maker-blind
+   close-scope pass still covers it.
+   **Inline fallback (`roleScopedAgents: false` / no-nesting harness).** When
+   the kill-switch is off, or the host cannot spawn a sub-agent at this nesting
+   depth, do **not** stall: read
    [`helpers/deliver-story.md`](helpers/deliver-story.md) **in full** and
-   execute it (init → implement → ceremony → close-and-land). Under
-   `--yes` / injected helper content, execute directly without a re-read
-   turn.
+   execute it directly, in this turn, threading the same `docsDigestPath` /
+   `checklistPath` / change-set discipline. Under `--yes` / injected helper
+   content, execute directly without a re-read turn. The engine, gates, and
+   terminal envelope are identical either way — only the isolation differs.
 4. **Per-run epilogue (N>1).** Once step 3 reports `epilogueDue: true`
    (every Story done), keyed on the delivered id set: