mandrel 1.91.0 → 1.92.0

package/.agents/workflows/plan.md

@@ -1,21 +1,21 @@
 ---
 description:
   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
-  (sectioned Epic body: Tech Spec + Acceptance Table, then decomposition)
-  or the standalone-Story authoring path — and absorbs every planning flag.
+  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 [Epic ID] | --idea "<seed>" | --from-notes <path>
 
 ## Role
 
-Router. `/plan` owns argument parsing and path selection only — all phase
+Router. `/plan` owns argument parsing and path selection only — all step
 content lives in the two path helpers:
 
-- [`helpers/plan-epic.md`](helpers/plan-epic.md) — the full Epic planning
-  pipeline (Tech Spec + Acceptance Table folded into the Epic body, work
-  breakdown, healthcheck, handoff).
+- [`helpers/plan-epic.md`](helpers/plan-epic.md) — the 3-step Epic planning
+  path (interrogate → author → persist; Tech Spec + Acceptance Table folded
+  into the Epic body, then the Story backlog or a single-delivery marker).
 - [`helpers/plan-story.md`](helpers/plan-story.md) — the standalone-Story
   authoring path (context envelope → host-LLM draft → HITL → issue create).
 
@@ -28,25 +28,27 @@ path; no new classification machinery exists.
 
 | Invocation | Behavior |
 | --- | --- |
-| `/plan --idea "<seed>"` | Ideation → **scope triage**. Verdict `epic` → run [`helpers/plan-epic.md`](helpers/plan-epic.md) from Phase 1 (Idea Refinement). Verdict `story` → run [`helpers/plan-story.md`](helpers/plan-story.md) Phases 1–3. Verdict `borderline` → present both options and let the operator choose. |
-| `/plan <epicId>` | Existing-Epic path — run [`helpers/plan-epic.md`](helpers/plan-epic.md) from Phase 5. When the helper's story-sized advisory fires (the Epic is really one Story), convert **internally** by switching to [`helpers/plan-story.md`](helpers/plan-story.md) — do not re-triage and do not hop commands. |
+| `/plan --idea "<seed>"` | Ideation → **scope triage**. Verdict `epic` → run [`helpers/plan-epic.md`](helpers/plan-epic.md) from its ideation entry. Verdict `story` → run [`helpers/plan-story.md`](helpers/plan-story.md) Phases 1–3. Verdict `borderline` → present both options and let the operator choose. |
+| `/plan <epicId>` | Existing-Epic path — run [`helpers/plan-epic.md`](helpers/plan-epic.md) from its existing-Epic entry. When the helper's story-sized advisory fires (the Epic is really one Story), convert **internally** by switching to [`helpers/plan-story.md`](helpers/plan-story.md) — do not re-triage and do not hop commands. |
 | `/plan --from-notes <path>` | Internal handoff target (e.g. from `/audit-to-stories`). The notes file already encodes the path decision; do **not** re-run scope triage. Route per the notes' declared shape. |
 
 ## Flags
 
-`/plan` absorbs every flag the two retired planning commands accepted and
-forwards them to the active path helper:
+`/plan` absorbs every planning flag and forwards it to the active path
+helper:
 
 | Flag | Path | Meaning |
 | --- | --- | --- |
 | `--idea "<seed>"` | both | Seed text; triggers scope triage. |
 | `--from-notes <path>` | both | Pre-triaged handoff notes; skips triage. |
-| `--force` | Epic | Close + recreate an existing ticket tree on re-plan. |
-| `--force-review` | Epic | Force the operator review gate even when risk routing would skip it. |
+| `--force` | Epic | Re-plan: overwrite managed sections in place and close + recreate the ticket tree. |
+| `--amend` | Epic | Change-request delta persist: tickets carry `op: add\|modify\|keep\|close`; close ops require `--explicit-delete` after the dry-run diff. |
+| `--force-review` | Epic | Force the gate #2 operator review even when risk routing would skip it. |
 | `--allow-over-budget` | Epic | Permit a decomposition that exceeds the framework `maxTickets` reviewability budget. |
-| `--yes` | both | **Non-interactive / headless mode.** Deterministically auto-proceeds the two `/plan` HITL STOP gates — the ideation one-pager / scope-triage confirm (gate #1) and the Phase-7 Epic operator review gate (gate #2) — without waiting for operator input. Parallel to [`/deliver --yes`](deliver.md). Composes with `--allow-over-budget` and with the risk-routed Phase-7 skip (it forces a proceed where those do not apply). Default (flag absent) behavior is unchanged: both gates still STOP for interactive use. |
+| `--yes` | both | **Non-interactive / headless mode.** Deterministically auto-proceeds the two `/plan` HITL STOP gates — gate #1 (exit of interrogate) and gate #2 (risk-routed pre-persist review) — without waiting for operator input. Parallel to [`/deliver --yes`](deliver.md). Composes with `--allow-over-budget` and with the risk-routed gate #2 skip (it forces a proceed where those do not apply). Default (flag absent) behavior is unchanged: both gates still STOP for interactive use. |
 | `--steal` | Epic | Forcibly transfer a foreign Epic-lease. |
-| `--dry-run` | both | Author + validate without GitHub writes. |
+| `--resume` | Epic | Continue a partial persist (rate-limit / crash recovery). |
+| `--dry-run` | Story | Author + validate without GitHub writes (`story-plan.js --dry-run`). |
 | `--body <path>` | Story | Pre-authored Story body file; validate (and create, unless `--dry-run`) without re-authoring. |
 | `--persona <name>` | Story | Override the persona label on the drafted Story. |
 | `--refine` / `--no-refine` | Story | Toggle the draft refinement loop. |
@@ -55,48 +57,48 @@ forwards them to the active path helper:
 the story path (or vice versa) is reported once
 (`[plan] --force has no effect on the story path`) and ignored — never an
 error. The historical bidirectional escalation between the two planning
-commands (story-sized Epic ↘ Story; epic-sized Story draft ↗ Epic) is now
-an **internal branch switch** inside this router: same skills, same
-helpers, no command hop and no operator re-entry.
+commands (story-sized Epic ↘ Story; epic-sized Story draft ↗ Epic) is an
+**internal branch switch** inside this router: same skills, same helpers, no
+command hop and no operator re-entry.
 
 ### Headless / non-interactive mode (`--yes`)
 
 `--yes` is the headless escape hatch for an unattended driver (CI, a
 benchmark harness, or any `claude -p` run with no human at the keyboard). It
-is the `/plan`-side parallel of [`/deliver --yes`](deliver.md), which
-suppresses that command's segment-plan confirmation. `/plan` has exactly
-**two** HITL STOP gates, and `--yes` deterministically auto-proceeds **both**
-without waiting for operator input:
-
-1. **Gate #1 — the ideation one-pager / scope-triage / clarity confirm.**
-   This single conceptual gate has three faces depending on the entry form,
-   and `--yes` auto-proceeds **all three**:
-   - On the `--idea` Epic path,
-     [`helpers/plan-epic.md`](helpers/plan-epic.md) Phase 1 (folding in the
-     Phase 1.5 scope-triage verdict) STOPs to confirm the sharpened one-pager.
+is the `/plan`-side parallel of [`/deliver --yes`](deliver.md). `/plan` has
+exactly **two** HITL STOP gates, and `--yes` deterministically auto-proceeds
+**both** without waiting for operator input:
+
+1. **Gate #1 — the exit of the interrogate step.** One conceptual gate with
+   a face per entry form, and `--yes` auto-proceeds all of them:
+   - On the `--idea` Epic path, the interrogate step of
+     [`helpers/plan-epic.md`](helpers/plan-epic.md) STOPs to confirm the
+     sharpened one-pager, folding in the scope-triage verdict and the
+     duplicate-candidate review.
    - On the `--idea` Story path,
      [`helpers/plan-story.md`](helpers/plan-story.md) Phase 2 STOPs to
      confirm the drafted Story body.
-   - On the existing-Epic (`/plan <epicId>`) path, the Phase 6 Epic Clarity
-     Gate's **needs-refinement** branch STOPs to confirm the refined-body
-     diff before persisting it.
-
-   Under `--yes` each auto-proceeds: the one-pager / draft / refined-body
-   confirm resolves as **approved**, and a `story` / `borderline` triage
-   verdict resolves to its **recommended** branch (the one the gate prose
-   marks "Recommended") rather than prompting the three-way choice. The
-   verdict / clarity scoring is still recorded in chat (one line); only the
-   *wait* is suppressed. The clarity-gate *scoring* itself (deterministic
-   section-presence in Phase 6 step 1) still runs — `--yes` suppresses only
-   the operator confirm of the proposed refinement.
-2. **Gate #2 — the Phase-7 Epic operator review gate.** When risk routing
-   forces a review (`planningRisk.requiresReview === true`, or the operator
-   also passed `--force-review`),
-   [`helpers/plan-epic.md`](helpers/plan-epic.md) Phase 7 STOPs for operator
-   approval of the updated Epic body (its Tech Spec sections and
-   `## Acceptance Table`) before decomposition.
-   Under `--yes` this review auto-proceeds straight to Phase 8 exactly as
-   on the low-risk auto-proceed path.
+   - On the existing-Epic (`/plan <epicId>`) path, the interrogate step
+     STOPs to confirm the folded re-plan / clarity-refinement / advisory
+     outcomes (the Clarity Gate's refined-body diff among them).
+
+   Under `--yes` each resolves as **approved**, and a `story` /
+   `borderline` triage verdict resolves to its **Recommended** branch rather
+   than prompting the three-way choice. **The interrogation itself runs
+   exactly one bounded pass**: no operator questions are asked — facts come
+   from the codebase, and every unresolved unknown lands in the one-pager's
+   **Key Assumptions** section instead of a question, so a headless driver
+   can never hang inside a free-form interrogation. The verdict / clarity
+   scoring is still recorded in chat (one line); only the *wait* is
+   suppressed — the deterministic clarity *scoring* inside the
+   `plan-context.js` envelope always runs.
+2. **Gate #2 — the risk-routed pre-persist review.** When the authored risk
+   verdict routes to review (high risk, or the operator also passed
+   `--force-review`), [`helpers/plan-epic.md`](helpers/plan-epic.md) step 3
+   STOPs for operator approval of the assembled plan (spec, tickets, risk,
+   and `deliveryShape` in one view) before the persist CLI runs. Under
+   `--yes` this review auto-proceeds straight to the persist call, exactly
+   as on the low-risk auto-proceed branch.
 
 **Composition.** `--yes` is orthogonal to the other planning flags and
 composes cleanly:
@@ -104,111 +106,36 @@ composes cleanly:
 - With **`--allow-over-budget`**: `--yes` suppresses the gate *waits* while
   `--allow-over-budget` still governs the `maxTickets` over-budget persist —
   passing `--yes` alone does **not** waive the budget gate.
-- With the **risk-routed Phase-7 skip**: when risk routing already skips the
-  Phase-7 review (low-risk, no `--force-review`), `--yes` is a no-op for that
-  gate — it only *forces a proceed where the gate would otherwise STOP*, it
-  never *adds* a stop or relaxes any non-HITL validator.
+- With the **risk-routed gate #2 skip**: when risk routing already
+  auto-proceeds the review (low-risk, no `--force-review`), `--yes` is a
+  no-op for that gate — it only *forces a proceed where the gate would
+  otherwise STOP*, it never *adds* a stop or relaxes any non-HITL validator.
 
 **`--yes` suppresses only the HITL operator *waits* above.** It does **not**
-relax any deterministic gate — the Phase 6 Epic Clarity Gate **scoring**
-(section-presence), the Phase 7.5 Tech Spec Section Gate, the file-assumption
-/ DAG validators, the Phase 10 readiness healthcheck, and the `agent::blocked`
-runtime pause all behave exactly as without the flag. A `--yes` run that hits
-one of those still fails closed; the flag is an operator-input suppressor, not
-a validation override. The other operator-input *waits* in the pipeline also
-auto-proceed under `--yes` — the non-blocking Phase 2 duplicate-search pause
-(distinct-Epic confirmed), the Phase 6 clarity refinement-diff confirm
-(refined body approved), and the advisory Phase 8.3/8.4/8.5
-consolidation/critic diffs (consolidated/critic output applied) — since they
-are operator-input waits, not validators. The two *named* HITL STOP gates the
-Story tracks (gate #1, gate #2) are the load-bearing pair; these additional
-waits are auto-proceeded for the same headless reason.
-
-## Boot sweep
-
-Before anything else — ahead of the first-run preflight — run the **protected
-boot sweep** so `/plan` opens against a tidy local checkout instead of one
-still carrying the merged refs of the last delivered Epic or Story:
-
-```bash
-node .agents/scripts/boot-sweep.js \
-  --include 'story-*' --include 'epic/*' \
-  --include 'feat/*' --include 'fix/*' --include 'chore/*'
-```
-
-This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
-base branch (`main`), prunes stale remote-tracking refs, and reaps every local
-branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
-It **never** touches the stash stack, and its `evaluateProtection` partition
-skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
-still-open parent Story ticket — so it is safe to run unattended at the top of
-a planning session. The sweep is **silent on a no-op**: with nothing to reap
-and `main` already current it prints a single summary line
-(`[boot-sweep] reaped 0 local + 0 remote; protected 0.`) and moves on. Its exit
-code is always `0` — a failed sweep is swallowed and reported in the summary,
-never allowed to fail the planning run.
-
-## First-run preflight
-
-Before routing to a path helper, run a **first-run preflight** to catch
-common day-0 issues that would silently degrade every downstream task.
-
-### When the preflight fires
-
-The preflight runs when **any** of these is true:
-
-1. One or more `project.docsContextFiles` entries are absent under the
-   configured `docsRoot`.
-2. One or more present `docsContextFiles` still carry the
-   `<!-- MANDREL:STUB -->` marker (i.e. they are un-edited scaffolded stubs).
-3. The last `mandrel doctor` verdict cached in `temp/doctor-result.json`
-   records `"verdict": "unready"`. An **absent** cache file is no signal —
-   doctor may simply never have run; only an explicit recorded unready
-   verdict fires this signal.
-
-### Preflight procedure
-
-1. **Detect the condition.** Check the three signals above. When none is
-   true, skip the preflight entirely — no operator interaction, no delay.
-2. **Offer to flesh out docs.** Summarize the found condition to the
-   operator (e.g. "3 docsContextFiles are missing" or "architecture.md
-   still carries the stub marker") and ask:
-   > *Do you want to flesh out these docs from the codebase before planning?
-   > [y/N]*
-3. **On acceptance.** Walk through each affected file, read relevant
-   codebase artifacts (source files, README, existing docs), and write real
-   content to replace the stub. Then re-run `mandrel doctor` to confirm
-   readiness. If doctor passes, proceed to routing.
-4. **On decline.** Log one line:
-   > *[plan] Proceeding with degraded doc context — planning quality may be
-   > reduced.*
-   Then continue to the normal routing procedure below.
-
-The preflight is **never a hard stop** — declining continues planning with a
-noted degradation. It only fires when there is a genuine signal (missing or
-stubbed docs, or an unready doctor verdict).
+relax any deterministic gate — the clarity scoring, the Tech Spec section
+gate, the ticket validator / file-assumption / DAG / budget gates, the
+inline readiness healthcheck, and the `agent::blocked` runtime pause all
+behave exactly as without the flag; it is an operator-input suppressor, not
+a validation override. A `--yes` run that hits one of those still fails
+closed. The smaller operator-input waits folded into the two gates — the
+duplicate-candidate review, the clarity refinement-diff confirm, and the
+advisory critic diffs — auto-proceed for the same headless reason.
 
 ## Procedure
 
 1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
    `--body` must be present; anything else is a usage error naming the four
    forms. A `--body` invocation routes to the story path (no triage).
-2. **Boot sweep.** Run the protected boot sweep above
-   (`node .agents/scripts/boot-sweep.js …`) to fast-forward `main`, prune
-   stale remotes, and reap merged-PR branches. Silent on a no-op; never fails
-   the run.
-3. **First-run preflight.** Run the preflight above. Skip when all signals
-   are clear (healthy project).
-4. **Triage (idea path only).** Run the
+2. **Triage (idea path only).** Run the
    [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
    seed. Record the verdict in chat (one line).
-5. **Delegate.** Read the selected path helper **in full** and execute it
-   from its entry phase, forwarding the absorbed flags (including `--yes`).
-   The helper's phase numbering, HITL gates, and scripts are unchanged — this
-   router adds no phase content. When `--yes` is present, the two HITL STOP
-   gates auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
+3. **Delegate.** Read the selected path helper **in full** and execute it
+   from its entry, forwarding the absorbed flags (including `--yes`). The
+   helper's steps, HITL gates, and scripts are the procedure — this router
+   adds no step content. When `--yes` is present, the two HITL STOP gates
+   auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
    above; every deterministic gate still runs.
-6. **Internal returns.** When a path helper would historically have handed
+4. **Internal returns.** When a path helper would historically have handed
    off to the other planning command, switch helpers in-place and continue;
    surface the switch to the operator as a one-line note.
 
@@ -219,6 +146,9 @@ stubbed docs, or an unready doctor verdict).
   planned Epic, `/deliver <storyId>` for a standalone Story.
 - The router never calls planning scripts directly; the path helpers own
   every script invocation.
+- Checkout hygiene (branch sweep) and day-0 doc readiness are owned by
+  [`/git-cleanup`](git-cleanup.md) and `mandrel doctor` respectively —
+  `/plan` runs no boot sweep and no first-run preflight.
 
 ## See also
 

package/docs/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.92.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.91.0...mandrel-v1.92.0) (2026-07-12)
+
+
+### Added
+
+* **plan:** collapse the plan workflow prose to interrogate → author → persist (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4492](https://github.com/dsj1984/mandrel/issues/4492)) ([b7cb068](https://github.com/dsj1984/mandrel/commit/b7cb068fed8c599ce1a42e51b3ff3f7658cb08b1))
+* **plan:** delivery-shape modes — single persist, amend delta (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4491](https://github.com/dsj1984/mandrel/issues/4491)) ([63e97c5](https://github.com/dsj1984/mandrel/commit/63e97c5d4546f1f1245e4d6b33428338d50bcded))
+* **plan:** plan-context emit cli — single envelope for the 3-step collapse (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4489](https://github.com/dsj1984/mandrel/issues/4489)) ([9255067](https://github.com/dsj1984/mandrel/commit/92550676af49ec33ec8ba9f9cc48785254bd53af))
+* **plan:** plan-metrics ledger — measure turns-per-plan before the collapse (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4487](https://github.com/dsj1984/mandrel/issues/4487)) ([d64b3aa](https://github.com/dsj1984/mandrel/commit/d64b3aa275f31c00760cc2ba6637674f1945d408))
+* **plan:** plan-persist cli — single github-write surface for the 3-step collapse (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4490](https://github.com/dsj1984/mandrel/issues/4490)) ([b01b9bf](https://github.com/dsj1984/mandrel/commit/b01b9bf080718f237f394818e0978d6f87f58e49))
+* **plan:** retire the 12-phase delegates — plan pipeline is context → author → persist (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4494](https://github.com/dsj1984/mandrel/issues/4494)) ([98e80f6](https://github.com/dsj1984/mandrel/commit/98e80f6550e6874c5793cfe7535a8d93bb8e7e72))
+* **plan:** risk/size-conditional critics — consolidation, reachability, pre-mortem (refs [#4474](https://github.com/dsj1984/mandrel/issues/4474)) ([#4493](https://github.com/dsj1984/mandrel/issues/4493)) ([a264cb3](https://github.com/dsj1984/mandrel/commit/a264cb3ab0d21167ef444b9f8af8141baeef7b21))
+
 ## [1.91.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.90.0...mandrel-v1.91.0) (2026-07-12)
 
 

package/lib/cli/registry.js

@@ -25,12 +25,12 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-
 import {
   REQUIRED_NODE_CEILING_MAJOR,
   REQUIRED_NODE_FLOOR,
   satisfiesNodeEngine,
 } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
+import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
 import {
   defaultResolvePackageRoot,
   listFiles as listPayloadFiles,
@@ -238,11 +238,14 @@ function runGhAuth({ runner = spawn, env = process.env } = {}) {
  * Injectable seams (used by tests so no real filesystem is touched):
  * - `cwd()` replaces `process.cwd` so tests can pin the consumer root.
  * - `readDir` replaces `fs.readdirSync`.
+ * - `readFile` replaces `fs.readFileSync` (frontmatter `command: false`
+ *   projection opt-out, #4482 — an unreadable source is treated as
+ *   projected, matching the sync script's fail-loud read).
  *
- * @param {{ projectRoot?: string, cwd?: () => string, readDir?: (dir: string) => string[] }} [opts]
+ * @param {{ projectRoot?: string, cwd?: () => string, readDir?: (dir: string) => string[], readFile?: (file: string) => string | null }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
  */
-function runCommandsInSync({ projectRoot, cwd, readDir } = {}) {
+function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
   const getCwd = cwd ?? (() => process.cwd());
   const root = projectRoot ?? getCwd();
   const listDir =
@@ -254,14 +257,29 @@ function runCommandsInSync({ projectRoot, cwd, readDir } = {}) {
         return [];
       }
     });
+  const readSource =
+    readFile ??
+    ((file) => {
+      try {
+        return fs.readFileSync(file, 'utf8');
+      } catch {
+        return null;
+      }
+    });
 
   const srcDir = path.join(root, '.agents', 'workflows');
   const destDir = path.join(root, '.claude', 'commands');
 
   // Only top-level .md files are synced (helpers/ subdirectory excluded by
   // the sync script — they are path-included modules, not slash commands).
+  // Workflows whose frontmatter carries `command: false` (#4482) opt out of
+  // projection and must not count toward the expected command set.
   const sources = listDir(srcDir)
     .filter((f) => !f.startsWith('.'))
+    .filter((f) => {
+      const content = readSource(path.join(srcDir, f));
+      return content == null || !isCommandExcluded(content);
+    })
     .sort();
   const dests = listDir(destDir)
     .filter((f) => !f.startsWith('.'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.91.0",
+  "version": "1.92.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",

package/.agents/schemas/loop-unit.schema.json

@@ -1,70 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/loop-unit.schema.json",
-  "version": "1.0.0",
-  "title": "Loop Unit (recurring-work definition)",
-  "description": "Schema for the YAML frontmatter of a loop unit — a markdown file under .agents/workflows/loops/ that defines a recurring/iterative unit of work with a checkable definition of done. The loop block carries the cadence (how the loop is paced), the goal (what the loop is trying to achieve), an optional verify command/array (the at-keyboard checks proving a round is complete — required for self-paced cadence, optional for interval/cron), a maxRounds backstop, and an onExhaust policy describing what happens when the round cap is hit without the goal being met.",
-  "type": "object",
-  "additionalProperties": true,
-  "required": ["loop"],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "Optional reference to this schema file so YAML editors with $schema-aware autocomplete can resolve it from the unit file itself."
-    },
-    "description": {
-      "type": "string",
-      "description": "Optional human-readable summary of what this loop unit does."
-    },
-    "loop": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["cadence", "goal"],
-      "description": "The loop definition block. Carries the cadence, goal, conditional verify, round cap, and exhaustion policy.",
-      "properties": {
-        "cadence": {
-          "type": "string",
-          "enum": ["self-paced", "interval", "cron"],
-          "description": "How the loop is paced. 'self-paced' lets the agent decide when to run the next round and therefore MUST carry a verify[] so each round has a checkable definition of done. 'interval' and 'cron' are externally scheduled, so verify is optional."
-        },
-        "goal": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Required. What the loop is trying to achieve — the standing objective each round works toward."
-        },
-        "verify": {
-          "description": "Command(s) that prove a round is complete. A single command string or an array of command strings. Required when cadence is 'self-paced'; optional for 'interval' / 'cron'.",
-          "oneOf": [
-            { "type": "string", "minLength": 1 },
-            {
-              "type": "array",
-              "items": { "type": "string", "minLength": 1 },
-              "minItems": 1
-            }
-          ]
-        },
-        "maxRounds": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Optional positive-integer backstop on the number of loop rounds before the onExhaust policy fires."
-        },
-        "onExhaust": {
-          "type": "string",
-          "enum": ["block", "report", "hand-back"],
-          "description": "What happens when maxRounds is hit without the goal met. 'block' transitions to a HITL gate; 'report' emits a summary and stops; 'hand-back' returns control to the caller."
-        }
-      },
-      "allOf": [
-        {
-          "if": {
-            "properties": { "cadence": { "const": "self-paced" } },
-            "required": ["cadence"]
-          },
-          "then": {
-            "required": ["verify"]
-          }
-        }
-      ]
-    }
-  }
-}

package/.agents/scripts/assert-branch.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-
-/* node:coverage ignore file */
-
-/**
- * assert-branch.js — Pre-commit Branch Guard
- *
- * Exits non-zero if the current git branch does not match `--expected`.
- * Intended to be invoked immediately before `git add`/`git commit` in any
- * workflow where multiple agents share a working directory. Prevents the
- * parallel-story contention bug where one agent's `git add` sweeps another
- * agent's WIP after a concurrent `git checkout`.
- *
- * Usage:
- *   node .agents/scripts/assert-branch.js --expected <branch-name>
- *
- * Exit codes:
- *   0 — Current branch matches expected.
- *   1 — Mismatch (stderr explains) or invocation error.
- */
-
-import { fileURLToPath } from 'node:url';
-import { gitSpawn } from './lib/git-utils.js';
-import { Logger } from './lib/Logger.js';
-import { PROJECT_ROOT } from './lib/project-root.js';
-export function assertBranch(expected, { cwd = PROJECT_ROOT } = {}) {
-  if (!expected || typeof expected !== 'string') {
-    return { ok: false, reason: 'missing --expected <branch>' };
-  }
-  const result = gitSpawn(cwd, 'branch', '--show-current');
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      reason: `git branch --show-current failed: ${result.stderr}`,
-    };
-  }
-  const actual = result.stdout;
-  if (actual !== expected) {
-    return {
-      ok: false,
-      reason: `branch mismatch — expected "${expected}", on "${actual}". Another agent may have switched the working directory. STOP: do not commit.`,
-      actual,
-      expected,
-    };
-  }
-  return { ok: true, actual, expected };
-}
-
-const FLAG_SPEC = {
-  expected: { type: 'string' },
-  cwd: { type: 'string' },
-};
-
-function parseArgs(argv) {
-  const out = { expected: null, cwd: null };
-  for (const [name, def] of Object.entries(FLAG_SPEC)) {
-    const idx = argv.indexOf(`--${name}`);
-    if (idx >= 0 && idx + 1 < argv.length && def.type === 'string') {
-      out[name] = argv[idx + 1];
-    }
-  }
-  return out;
-}
-
-// cli-opt-out: synchronous CLI with bespoke main-guard; runAsCli's async-main pattern doesn't fit.
-const isMain = process.argv[1] === fileURLToPath(import.meta.url);
-if (isMain) {
-  const { expected, cwd: flagCwd } = parseArgs(process.argv.slice(2));
-  // Worktree-aware: hooks invoked inside a per-story worktree must guard the
-  // worktree's HEAD, not the main checkout. Resolution precedence:
-  //   --cwd <path>  >  AGENT_WORKTREE_ROOT env  >  PROJECT_ROOT (main checkout)
-  // Flag wins so operators can override even when the env var leaked from a
-  // parent shell.
-  const cwd = flagCwd || process.env.AGENT_WORKTREE_ROOT || PROJECT_ROOT;
-  const result = assertBranch(expected, { cwd });
-  if (!result.ok) {
-    Logger.error(`[assert-branch] ${result.reason}`);
-    process.exit(1);
-  }
-  Logger.info(`[assert-branch] ✅ on ${result.actual}`);
-}