mandrel 1.94.0 → 2.0.0

package/.agents/docs/workflows.md

@@ -49,13 +49,13 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report. |
 | `/audit-seo` | Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets. |
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
-| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --idea or opens standalone Stories. |
+| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --seed-file or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/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. |
+| `/deliver` | Unified delivery entry point. Delivers one or more Stories via the single deliver-story engine — story-<id> → PR → main. Sequences N>1 by depends\_on and runs the per-run epilogue once at the end. |
 | `/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-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. |
 | `/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 3-step Epic path (interrogate → author → persist) or the standalone-Story authoring path — and absorbs every planning flag. |
+| `/plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default (folded Tech Spec in the Story body); splits into N>1 only under the default-single split policy. |
 | `/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` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |

package/.agents/instructions.md

@@ -8,15 +8,17 @@ set. You MUST strictly adhere to the following rules:
 
 ## 1. System Guardrails & Initialization
 
-### A. Persona Routing & Execution
+### A. Role Framing (no persona packs)
 
-When a task carries a `persona::<role>` label, or a user explicitly instructs
-"Act as [Role/Persona]" in chat, retrieve and strictly adopt the rules in
-`.agents/personas/[role].md`. Personas are advisory role framing, not a runtime
-injection — read the file when the label or the instruction points you at one.
+v2 has **no** `.agents/personas/` packs and **no** `persona::*` GitHub labels.
+Behavioral constraints come from this file, always-on / on-demand rules, and
+skills. Role-scoped spawn contexts (when used) live under `.agents/agents/`
+via `delivery.routing.roleScopedAgents`. QA auth identities (`qa.personas`)
+are a separate fixture concept — not agent behavior packs.
 
-- **Fallback:** If no persona is indicated, or the named file is missing,
-  default to `.agents/personas/engineer.md`.
+If a user says "act as [role]" in chat, apply the matching skill / workflow
+guidance (e.g. QA skills for verification work, security skill for threat
+modeling) rather than looking for a persona file.
 
 ### B. Skill Activation
 
@@ -202,18 +204,14 @@ hand back to the operator. Do not paper over the loop with another
 just-in-case retry.
 
 This protocol is not soft-prompt-only — it has a runtime substrate. While
-executing as a Story delivery sub-agent (via `helpers/epic-deliver-story`
-or `helpers/single-story-deliver`), you MUST emit a `story.heartbeat`
-lifecycle event on every Task transition (or whenever you stall on a
-long-running step) so the parent `/deliver` idle watchdog (§ 2e of
-`.agents/workflows/helpers/deliver-epic.md`, re-ticked every 30 minutes via
-`wave-tick.js --check-idle 30`) can distinguish a child still making
-progress from a dead one. If you genuinely cannot proceed, transition to
-`agent::blocked` and exit non-zero — never fall silent. A child with no
-recent `story.heartbeat`, no commit on its `story-<id>` branch, and no
-`agent::blocked` label is exactly the failure mode the idle watchdog is
-built to catch, and the watchdog will re-dispatch (or escalate) the Story
-without your participation.
+executing as a Story delivery sub-agent (via `helpers/deliver-story`), you
+MUST emit a `story.heartbeat` lifecycle event on every Task transition (or
+whenever you stall on a long-running step) so the parent `/deliver`
+sequencer can distinguish a child still making progress from a dead one. If
+you genuinely cannot proceed, transition to `agent::blocked` and exit
+non-zero — never fall silent. A child with no recent `story.heartbeat`, no
+commit on its `story-<id>` branch, and no `agent::blocked` label is exactly
+the stall shape the parent run must detect and escalate.
 
 ### J. HITL Blocker Escalation (Safe Execution)
 
@@ -243,8 +241,7 @@ resolve by this **total ordering** (higher wins):
    (§ 1.E).
 2. **This file** — `.agents/instructions.md`.
 3. **Global rules** — `.agents/rules/*.md` (§ 1.F).
-4. **The active persona** — `.agents/personas/[role].md` (§ 1.A).
-5. **Skills** — `.agents/skills/**/SKILL.md` (§ 1.B).
+4. **Skills** — `.agents/skills/**/SKILL.md` (§ 1.B).
 
 Two carve-outs refine the ordering:
 
@@ -252,18 +249,18 @@ Two carve-outs refine the ordering:
   tier overlap, the narrower, more-specific statement governs the broader one
   (e.g. a stack-specific skill refines a general core skill; a per-rule
   statement refines a cross-rule one).
-- **`rules/security-baseline.md` is inviolable.** No persona, skill, or local
-  override may relax a security MUST. A security constraint that conflicts
-  with any lower-tier guidance — or with a local override — always wins,
-  regardless of its tier position above.
+- **`rules/security-baseline.md` is inviolable.** No skill or local override
+  may relax a security MUST. A security constraint that conflicts with any
+  lower-tier guidance — or with a local override — always wins, regardless of
+  its tier position above.
 
 ---
 
 ## 2. FinOps & Token Budgeting (Economic Guardrails)
 
 Mandrel does **not** enforce live LLM spend from response metadata. It caps
-**hydrated prompt size** (`delivery.maxTokenBudget`, section-aware elision) and
-runs optional **pre-dispatch estimates** (`delivery.preflight.*`); your host
+**planning context budget** (`planning.context.maxBytes`) and related
+envelopes; your host
 runtime owns session quota and hard stops. The config keys, the ≈4-char/token
 estimate, and the elision behaviour are reference detail — see
 [`docs/execution-reference.md` § FinOps & token budgeting](docs/execution-reference.md#finops--token-budgeting-economic-guardrails).
@@ -283,7 +280,7 @@ budget grounds.
      ensures (generates or reuses) a per-Epic docs digest — a single compact
      outline (path, byte size, heading outline with line numbers, and the
      first paragraph under each `##`) built from `project.docsContextFiles`
-     — at `temp/epic-<epicId>/docs-digest.md` (`plan-context.js`, via the
+     — at `temp/run-<id>/docs-digest.md` (`plan-context.js`, via the
      shared generator in
      `.agents/scripts/lib/orchestration/docs-digest.js`; the same file the
      `/deliver` story sub-agents below already consume). Use the digest to
@@ -303,19 +300,13 @@ budget grounds.
      hard cutover: there is no read-every-`docsContextFiles`-file branch
      retained.
    - **Digest-first Reading (`/deliver` story sub-agents)**: A `/deliver`
-     Story delivery sub-agent (dispatched via `helpers/epic-deliver-story` or
-     `helpers/single-story-deliver`) does **not** re-read the full
-     `project.docsContextFiles` set per Story. Instead it reads the **per-Epic
-     docs digest** — the same file and shape described above — that
-     `epic-deliver-prepare.js` writes to
-     `temp/epic-<epicId>/docs-digest.md` and the parent threads into the
-     child prompt as `docsDigestPath`. Use the digest to decide which docs are
-     relevant to the Story at hand, then **pull the full file on demand**
-     (reading the section at the line number the digest names) when a section
-     bears on the change. When `docsDigestPath` is null (the project has no
-     `project.docsContextFiles` configured) there is no digest to read and no
-     per-Story docs mandate — read a full doc only if the Story's own context
-     points you at one. This is the hard cutover from the former
+     Story delivery sub-agent (dispatched via `helpers/deliver-story`) does
+     **not** re-read the full `project.docsContextFiles` set per Story. When
+     the caller threads a `docsDigestPath`, use that compact outline to decide
+     which docs are relevant, then **pull the full file on demand**. When
+     `docsDigestPath` is null there is no digest to read and no per-Story docs
+     mandate — read a full doc only if the Story's own context points you at
+     one. This is the hard cutover from the former
      read-every-file-per-Story rule: delivery children no longer ingest the
      whole docs set up front.
    - **Standalone-Story planning path (`story-plan.js --emit-context`)**:
@@ -396,24 +387,23 @@ budget grounds.
 
 ---
 
-## 5. Git & Epic Protocol (Strict Standards)
+## 5. Git & Story Protocol (Strict Standards)
 
 To maintain a clean and readable repository history, you MUST follow these
-strict conventions for all epic-related Git operations. See
+strict conventions for all Story-related Git operations. See
 [`.agents/rules/git-conventions.md`](rules/git-conventions.md) for the full
 canonical reference.
 
 ### A. Branch Naming (Canonical)
 
-Epic execution uses two branch shapes. The runtime creates and maintains
-them automatically; agents commit on the execution branch only.
+v2 delivery uses one branch shape. The runtime creates and maintains it
+via `single-story-init.js`; agents commit on that branch only.
 
-| Purpose          | Format                       | Owner                  | Notes                                                                                         |
-| ---------------- | ---------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
-| Story execution  | `story-<storyId>`            | `story-init.js` | Per-Story worktree at `.worktrees/story-<storyId>/`. All Story implementation commits land here. |
-| Epic integration | `epic/<epicId>`              | `/deliver` slash command | Story branches merge into this branch with `--no-ff`. Pushed per wave.                       |
+| Purpose         | Format            | Owner                   | Notes                                                                 |
+| --------------- | ----------------- | ----------------------- | --------------------------------------------------------------------- |
+| Story execution | `story-<storyId>` | `single-story-init.js`  | Per-Story worktree at `.worktrees/story-<storyId>/`. PR target is `main` (squash + required checks). There is no `epic/<id>` integration branch and no `--no-ff` wave merge. |
 
-- **Verification**: After `story-init.js` returns, confirm
+- **Verification**: After `single-story-init.js` returns, confirm
   `git branch --show-current` reports `story-<storyId>` before making any
   commits. If it does not, **STOP** and re-init.
 
@@ -429,31 +419,30 @@ prompted.
 
 ### C. History Hygiene
 
-Prioritize a clean `epic/[EPIC_ID]` branch. Story branches are merged into
-the Epic branch automatically by `helpers/epic-deliver-story` (via
-`story-close.js`); the Epic branch reaches `main` via the pull request that
-`/deliver` opens at the end of its run — the operator merges through
-the GitHub UI. There is no in-script merge to `main`.
-
-### D. Ticket hierarchy (2-tier)
-
-Mandrel uses a **2-tier ticket hierarchy** (Epic → Story).
-Acceptance criteria and verification steps live inline on the Story
-body (`acceptance[]` / `verify[]`); there is no Feature tier and no
-`type::task` ticket layer. Thematic grouping lives as prose in the
-Epic body (which also carries the folded Tech Spec sections).
-
-- The decomposer emits only `type::epic` and `type::story` issues;
-  Stories attach directly to the Epic.
-- Each Story-implementation phase is executed by
-  `helpers/epic-deliver-story` (Epic-attached) or
-  `helpers/single-story-deliver` (standalone). There is no per-Task
-  sub-loop; the agent authors commit subjects directly per
-  [`rules/git-conventions.md`](rules/git-conventions.md) and references
-  the parent Story via `(refs #<storyId>)`.
-- Story branches, the Epic-branch integration target, the wave-loop
-  fan-out, and the `epic/<id>` → `main` PR merge model are the same
-  as Section 5.A.
+Every Story reaches `main` via its own PR (`story-<id>` → squash + required
+checks). `helpers/deliver-story` / `single-story-close.js` open that PR;
+there is no Epic integration branch and no in-script push to `main`.
+
+### D. Ticket hierarchy (Story-only)
+
+v2 collapses the ticket model to **Story**. Acceptance criteria and
+verification steps live inline on the Story body (`acceptance[]` /
+`verify[]`); the folded Tech Spec lives inline in `## Spec` (over-budget
+Specs fail closed — split or tighten; never write under `docs/`). Optional
+`depends_on` edges order rare multi-Story plan-runs.
+
+- `/plan` emits one or more `type::story` issues (default N=1); N>1 shares a
+  `plan-run::<id>` label.
+- Each Story is executed by `helpers/deliver-story` (invoked from
+  [`/deliver`](workflows/deliver.md)). There is no per-Task sub-loop; the
+  agent authors commit subjects directly per
+  [`rules/git-conventions.md`](rules/git-conventions.md) and references the
+  Story via `(refs #<storyId>)`.
+- Branch model matches Section 5.A (`story-<id>` → PR → `main`).
+- There is no `type::epic` / `type::task` label and no Epic issue form. An
+  Epic is at most an optional untyped human umbrella issue outside
+  orchestration; `/deliver` refuses tickets that still carry an
+  `Epic: #N` footer.
 
 ---
 
@@ -471,12 +460,12 @@ To keep the repository clean and avoid polluting the Git history:
 
 ## 7. Complexity-Aware Execution
 
-The dispatcher automatically calculates the execution plan for an Epic. A
-Story is a **capability slice a frontier model delivers and self-verifies in
-one pass** — a broad footprint is normal when the change is cohesive. The
-numeric sizing backstop lives in one place: `DEFAULT_TASK_SIZING` in
-`.agents/scripts/lib/orchestration/ticket-validator-sizing.js` (operator
-override via `planning.taskSizing`). Do not re-slice a capability-sized
+`/plan` sizes each Story as a **capability slice a frontier model delivers
+and self-verifies in one pass** — a broad footprint is normal when the
+change is cohesive. The session-capacity backstop lives in one place:
+`DEFAULT_MODEL_CAPACITY` in
+`.agents/scripts/lib/orchestration/ticket-validator-sizing.js` (framework
+constant — not operator-tunable). Do not re-slice a capability-sized
 Story into per-module fragments just because it touches many files.
 
 ### A. When You See `⚠️ COMPLEXITY WARNING`

package/.agents/rules/ci-remediation.md

@@ -1,12 +1,11 @@
 # CI Failure Triage & Remediation
 
 This rule applies when a delivery path is watching a pull request's CI checks
-and a required check is red (or repeatedly slow) — the Epic Phase 8
-watch-and-iterate loop
-([`deliver-epic.md`](../workflows/helpers/deliver-epic.md)) and the standalone
+and a required check is red (or repeatedly slow) — the `/deliver` router
+([`deliver.md`](../workflows/deliver.md)) runs each Story through the
 single-Story Step 4 CI watch + fix loop
-([`single-story-deliver.md`](../workflows/helpers/single-story-deliver.md))
-both hand off to it. It is the single triage brain those mechanisms defer to:
+([`deliver-story.md`](../workflows/helpers/deliver-story.md)), which hands off
+to it. It is the single triage brain that mechanism defers to:
 the watcher (`pr-watch-with-update.js`) surfaces the failing check, the run
 link, and the failure signature; this rule decides what to do next.
 
@@ -50,18 +49,15 @@ path) or surfaces it inline (standalone path) — start from that digest.
 A deterministic failure caused by the diff is remediated at source. Use the
 existing per-check fix table — do **not** duplicate it here:
 
-- **Epic Phase 8**:
-  [`deliver-epic-reference.md` § Phase 8 — Watch-and-iterate remediation](../workflows/helpers/deliver-epic-reference.md#phase-8--watch-and-iterate-remediation)
-  (§ 8.1 Remediation).
-- **Standalone Step 4**:
-  [`single-story-deliver-reference.md` § Step 4 — CI watch + fix recovery](../workflows/helpers/single-story-deliver-reference.md#step-4--ci-watch--fix-recovery).
+- **Story Step 4**:
+  [`deliver-story-reference.md` § Step 4 — CI watch + fix recovery](../workflows/helpers/deliver-story-reference.md#step-4--ci-watch--fix-recovery).
 
 In short: lint/format → `npm run lint` + biome apply; maintainability/crap
 baseline drift → re-run the ratcheted script and fix at source (refresh a
 baseline only when the diff demonstrably can't be covered); test failure →
 reproduce with `npm test`, fix source or test; coverage threshold → add tests.
-Commit the fix on the delivery branch (`epic/<epicId>` or `story-<storyId>`),
-push, and re-run the watcher. Auto-merge stays armed across retries.
+Commit the fix on the delivery branch (`story-<storyId>`), push, and re-run the
+watcher. Auto-merge stays armed across retries.
 
 ## Infra, transient, and flaky failures ARE root-cause defects
 

package/.agents/rules/git-conventions-reference.md

@@ -79,15 +79,14 @@ checkout — reaping its own merged refs and fast-forwarding the base branch.
 `/git-cleanup` is a recovery tool, not a routine chore.** The mechanics behind
 that invariant:
 
-Every flow that lands work — `/deliver` (Epic and standalone-Story paths),
-`/git-deliver` — is responsible for leaving the local checkout tidy without
+Every flow that lands work — `/deliver` and `/git-deliver` — is responsible
+for leaving the local checkout tidy without
 operator intervention:
 
-- **Fast-forwarding the base branch is owned by the flow.** The standalone
-  multi-Story path fast-forwards `main` itself in its summary phase (via
-  `git-cleanup.js --fast-forward-main --execute --yes`); the Epic path
-  fast-forwards `epic/<id>` / `main` on its merge-and-reap beat. No workflow
-  ends by telling the operator to "run `/git-cleanup` afterwards to catch up".
+- **Fast-forwarding the base branch is owned by the flow.** `/deliver`
+  fast-forwards `main` itself in its cleanup phase (via
+  `git-cleanup.js --fast-forward-main --execute --yes`). No workflow ends by
+  telling the operator to "run `/git-cleanup` afterwards to catch up".
 - **Reaping merged local refs is owned by the flow's next boot.** `/plan` and
   `/git-deliver` open with a **protected boot sweep**
   (`boot-sweep.js`) that fast-forwards `main`, prunes stale remote-tracking

package/.agents/rules/git-conventions.md

@@ -12,28 +12,22 @@ live in the on-demand
 **before** doing the matching work; the core below is sufficient for every
 routine commit, branch, and PR.
 
-## Canonical Branching (v5 Orchestration)
-
-### Epic Base Branch
-
-Each Epic operates on a dedicated **Epic base branch** named `epic/[EPIC_ID]`
-(e.g., `epic/98`). This branch is created from the project's base branch
-(`main` by default) and serves as the integration target for all Stories
-within that Epic.
-
-### Story-Level Branching
-
-All tasks within a Story MUST be committed to a shared **Story branch**:
-`story-<storyId>` (e.g., `story-104`). The runtime owns Story branch
-creation via `story-init.js`; agents commit on the active Story branch only.
-
-> **Commit subjects.** Under the 2-tier hierarchy
-> (Epic → Story), Stories have no child tickets. Commits
-> land on `story-<storyId>` directly from the agent and the
-> Conventional Commit subject references the parent Story via
-> `(refs #<storyId>)`. See
-> [`.agents/instructions.md` § 5.D](../instructions.md) for the
-> full hierarchy contract.
+## Canonical Branching (v2)
+
+### Story branch → PR → main
+
+Every Story lands on a dedicated **Story branch** named `story-<storyId>`
+(e.g., `story-104`), seeded from `project.baseBranch` (`main` by default).
+The runtime owns branch creation via `single-story-init.js`; agents commit
+on that branch only. Close opens a PR against `main` (squash + required
+checks). There is **no** `epic/<id>` integration branch and no `--no-ff`
+wave merge.
+
+> **Commit subjects.** Stories have no child tickets. Commits land on
+> `story-<storyId>` directly from the agent and the Conventional Commit
+> subject references the Story via `(refs #<storyId>)`. See
+> [`.agents/instructions.md` § 5.D](../instructions.md) for the hierarchy
+> contract.
 
 ## Conventional Commits
 

package/.agents/schemas/acceptance-eval-verdict.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "acceptance-eval-verdict",
   "title": "Acceptance Self-Eval Verdict",
-  "description": "Structured output of one independent (fresh-context) acceptance self-eval round (Story #3819). Produced by the critic pass in the Story-implementation phase (helpers/epic-deliver-story.md Step 1 / helpers/single-story-deliver.md Step 1), written under the gitignored temp tree, and consumed by acceptance-eval.js to enforce the bounded round cap and decide whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. The author MUST NOT be the evaluator — the verdict is an independent judgment of the working diff against each inline acceptance[] item.",
+  "description": "Structured output of one independent (fresh-context) acceptance self-eval round (Story #3819). Produced by the critic pass in the Story-implementation phase (helpers/deliver-story.md Step 1a), written under the gitignored temp tree, and consumed by acceptance-eval.js to enforce the bounded round cap and decide whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. The author MUST NOT be the evaluator — the verdict is an independent judgment of the working diff against each inline acceptance[] item.",
   "type": "object",
   "required": ["storyId", "schemaVersion", "round", "criteria"],
   "properties": {