mandrel 2.0.0 → 2.2.0

package/.agents/scripts/deliver-recover.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * deliver-recover.js — probe a stranded Story's live state and print the ONE
+ * command that resumes it (Story #4543).
+ *
+ * Read-only by construction. This CLI mutates nothing: it reads the ticket's
+ * labels and lease, the Story branch locally and via its tracking ref, the
+ * worktree, and the PR (state + checks), then walks a fixed decision table
+ * and prints one command with the evidence it was derived from. It never
+ * prints a menu — a menu of options is what the operator already has, and it
+ * is the thing they cannot act on.
+ *
+ * The strand this exists for above all others is the **merged-but-label-stale**
+ * Story: a `/deliver` re-run refuses it outright, because
+ * `single-story-init.js` hard-errors on an already-closed Story. Before this
+ * surface, that Story had no automated way back.
+ *
+ * Usage:
+ *   node .agents/scripts/deliver-recover.js --story <STORY_ID> [--cwd <main-repo>]
+ *                                           [--json]
+ *
+ * Exit codes:
+ *   0 — a recovery shape was resolved and its next command printed (including
+ *       the "nothing to recover" shapes). Reading state is not a failure.
+ *   1 — the probe itself could not run (unreadable ticket, bad input).
+ *
+ * @see .agents/scripts/lib/orchestration/deliver-recover.js
+ * @see .agents/schemas/story-deliver-terminal.schema.json
+ */
+
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  recoverStory,
+  renderRecovery,
+} from './lib/orchestration/deliver-recover.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const HELP = `Usage: node .agents/scripts/deliver-recover.js --story <id> [--cwd <main-repo>] [--json]
+
+Probes a Story's live delivery state — labels, lease, branch, worktree, PR
+state and checks — and prints the single next command that resumes it, with
+the evidence it was derived from. Read-only: mutates nothing.
+
+Flags:
+  --story   GitHub issue number of the Story (required).
+  --cwd     Main-repo checkout to probe (default: project root).
+  --json    Emit the full recovery envelope as JSON instead of prose.
+  --help    Show this message.
+`;
+
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      story: { type: 'string' },
+      cwd: { type: 'string' },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+  return {
+    storyId: Number.parseInt(String(values.story ?? ''), 10),
+    cwd: values.cwd ?? null,
+    json: Boolean(values.json),
+    help: Boolean(values.help),
+  };
+}
+
+/**
+ * Probe and report. Exported for testing.
+ */
+export async function runDeliverRecover({
+  storyId: storyIdParam,
+  cwd: cwdParam,
+  json: jsonParam,
+  argv,
+  injectedProvider,
+  injectedConfig,
+  injectedGh,
+  injectedGitSpawn,
+} = {}) {
+  const parsed =
+    storyIdParam !== undefined
+      ? { storyId: storyIdParam, cwd: cwdParam ?? null, json: !!jsonParam }
+      : parseArgv(argv ?? process.argv.slice(2));
+
+  if (parsed.help) {
+    Logger.info(HELP);
+    return { success: true, result: null };
+  }
+  if (!Number.isInteger(parsed.storyId) || parsed.storyId <= 0) {
+    throw new Error(
+      'Usage: node deliver-recover.js --story <STORY_ID> [--cwd <main-repo>] [--json]',
+    );
+  }
+
+  const cwd = parsed.cwd ?? PROJECT_ROOT;
+  const config = injectedConfig || resolveConfig({ cwd });
+  const provider = injectedProvider || createProvider(config);
+
+  const recovery = await recoverStory({
+    storyId: parsed.storyId,
+    cwd,
+    provider,
+    config,
+    gh: injectedGh,
+    gitSpawnFn: injectedGitSpawn,
+  });
+
+  Logger.info(
+    parsed.json ? JSON.stringify(recovery, null, 2) : renderRecovery(recovery),
+  );
+  return { success: true, result: recovery };
+}
+
+runAsCli(import.meta.url, runDeliverRecover, { source: 'deliver-recover' });

package/.agents/scripts/drain-pending-cleanup.js

@@ -8,7 +8,7 @@
  * any still-stuck entries by enumerating the processes holding handles
  * inside the worktree path and terminating them.
  *
- * Invoked by `/deliver`, `/epic-plan-spec` / `/epic-plan-decompose`
+ * Invoked by `/deliver` and `/plan`
  * (via `drainPendingCleanupAtBoot` → `worktree-sweep.js`), and
  * `story-close` so the pending-cleanup ledger drains automatically
  * across the sprint lifecycle. Operators can also run it standalone:

package/.agents/scripts/evidence-gate.js

@@ -13,42 +13,22 @@
  *
  * Usage:
  *   node .agents/scripts/evidence-gate.js \
- *     (--epic-id <epicId> | --standalone) --scope-id <storyOrEpicId> --gate <name> \
+ *     --standalone --scope-id <storyId> --gate <name> \
  *     [--worktree <path>] [--no-evidence] -- <cmd> [args...]
  *
  * Examples:
- *   node .agents/scripts/evidence-gate.js --epic-id 802 --scope-id 817 --gate lint -- npm run lint
- *   node .agents/scripts/evidence-gate.js --epic-id 1030 --scope-id 1030 --gate test -- npm test
- *   node .agents/scripts/evidence-gate.js --epic-id 1114 --scope-id 1120 --gate test \
- *     --worktree .worktrees/story-1120 -- npm test
  *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate lint \
  *     --worktree .worktrees/story-4250 -- npm run lint
+ *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate test \
+ *     --worktree .worktrees/story-4250 -- npm test
  *
- * Either `--epic-id` or `--standalone` is required. When `scope-id ===
- * epic-id` the evidence file is Epic-scoped
- * (`<tempRoot>/epic-<eid>/validation-evidence.json`); when `scope-id !==
- * epic-id` it is Story-scoped under
- * `<tempRoot>/epic-<eid>/story-<sid>/validation-evidence.json`. With
- * `--standalone` (Story #4250) the file is anchored on the Story id alone at
+ * `--standalone` (Story #4250) is required: the evidence file is anchored on
+ * the Story id at
  * `<tempRoot>/standalone/stories/story-<sid>/validation-evidence.json` — the
  * same keyspace the standalone close consults, so the acceptance-self-eval
  * critic's verify[] runs (lint / typecheck) are shared with the close.
- *
- * **Worktree-aware spawn (Story #1120).** `--cwd` (default `PROJECT_ROOT`)
- * is the *evidence cwd* — it locates the per-Epic temp tree under the main
- * checkout's `.git/`. `--worktree` is the *spawn cwd* — when supplied, the
- * gate runner is launched with `cwd: <worktree>` and the HEAD-SHA used as
- * the evidence key is read from the worktree (so caching keys to the Story
- * branch's HEAD, not the main branch's). When `--worktree` is omitted,
- * spawn cwd falls back to `--cwd` (legacy single-tree behaviour).
- *
- * Exit codes:
- *   0 — gate passed (or skipped via evidence)
- *   N — gate failed (passes through the runner's exit code)
- *
- * `--no-evidence` forces the runner regardless of recorded state. The
- * evidence file is gitignored — evidence is a perf optimization, not a
- * trust boundary; pre-push hooks and CI continue to verify independently.
+ * v2.0.0 removed the Epic tier along with the `--epic-id` Epic-keyed
+ * keyspace.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -88,7 +68,6 @@ export function parseWrapperArgs(argv) {
     args: argv,
     options: {
       'scope-id': { type: 'string' },
-      'epic-id': { type: 'string' },
       gate: { type: 'string' },
       'no-evidence': { type: 'boolean', default: false },
       standalone: { type: 'boolean', default: false },
@@ -98,10 +77,8 @@ export function parseWrapperArgs(argv) {
     strict: false,
   });
   const scopeId = Number.parseInt(values['scope-id'] ?? '', 10);
-  const epicId = Number.parseInt(values['epic-id'] ?? '', 10);
   return {
     scopeId: Number.isNaN(scopeId) || scopeId <= 0 ? null : scopeId,
-    epicId: Number.isNaN(epicId) || epicId <= 0 ? null : epicId,
     standalone: values.standalone === true,
     gate: values.gate ?? null,
     useEvidence: values['no-evidence'] !== true,
@@ -126,15 +103,13 @@ function resolveHeadShaDefault(cwd, gitSpawnFn) {
  * Exported for tests + the CLI `main()`.
  *
  * @param {object} params
- * @param {number}   params.scopeId      — Story / Epic ID (positive integer).
- * @param {number|null} [params.epicId]  — Parent Epic id (Epic-keyed path).
- * @param {boolean}  [params.standalone] — When true, route to the
- *   storyId-anchored standalone keyspace instead of the Epic-keyed path
- *   (Story #4250). Substitutes for `epicId`.
+ * @param {number}   params.scopeId      — Story ID (positive integer).
+ * @param {boolean}  [params.standalone] — Required. Routes to the
+ *   storyId-anchored standalone keyspace (Story #4250).
  * @param {string}   params.gate         — Logical gate name (`lint`, `typecheck`, …).
  * @param {boolean}  params.useEvidence  — When false, force the runner.
- * @param {string}   params.cwd          — Evidence cwd (locates the per-Epic
- *   temp tree). The runner is spawned in `worktreePath` when set, else `cwd`.
+ * @param {string}   params.cwd          — Evidence cwd (locates the temp
+ *   tree). The runner is spawned in `worktreePath` when set, else `cwd`.
  * @param {string|null} [params.worktreePath] — Spawn cwd override (Story #1120).
  *   When set, the runner runs in the Story worktree and the HEAD-SHA used as
  *   the evidence cache key is read from the worktree, not from `cwd`.
@@ -159,7 +134,6 @@ export async function runEvidenceGate(params, deps = {}) {
   } = deps;
   const {
     scopeId,
-    epicId,
     standalone = false,
     gate,
     useEvidence,
@@ -168,31 +142,27 @@ export async function runEvidenceGate(params, deps = {}) {
     runnerArgs,
   } = params ?? {};
 
-  // `--epic-id` is required for the Epic-keyed path; `--standalone` (Story
-  // #4250) substitutes for it and routes the evidence file to the
-  // storyId-anchored standalone keyspace so the acceptance-self-eval critic
-  // can record verify[] evidence into the same keyspace the standalone close
-  // consults.
+  // `--standalone` (Story #4250) routes the evidence file to the
+  // storyId-anchored keyspace so the acceptance-self-eval critic can record
+  // verify[] evidence into the same keyspace the standalone close consults.
   if (
     !scopeId ||
-    (!epicId && !standalone) ||
+    !standalone ||
     !gate ||
     !runnerArgs ||
     runnerArgs.length === 0
   ) {
     logger.fatal(
-      'Usage: node evidence-gate.js (--epic-id <epicId> | --standalone) --scope-id <id> --gate <name> [--worktree <path>] [--no-evidence] -- <cmd> [args...]',
+      'Usage: node evidence-gate.js --standalone --scope-id <id> --gate <name> [--worktree <path>] [--no-evidence] -- <cmd> [args...]',
     );
     return { status: 1, skipped: false };
   }
-  // Evidence-store opts shared by shouldSkip + recordPass below. `standalone`
-  // routes to the storyId-anchored keyspace; otherwise the Epic-keyed path
-  // resolves under `epicId`.
-  const evidenceStoreOpts = { cwd, epicId, standalone };
+  // Evidence-store opts shared by shouldSkip + recordPass below.
+  const evidenceStoreOpts = { cwd, standalone };
 
   // Spawn cwd is the worktree when supplied — every gate command sees the
   // Story branch's tree, not the main checkout. Evidence cwd stays anchored
-  // to the main checkout so the per-Epic temp tree resolves under the main
+  // to the main checkout so the temp tree resolves under the main
   // `.git/`. The HEAD-SHA used as the cache key is read from the spawn cwd
   // (the worktree), so cache entries key against the Story branch's HEAD.
   const spawnCwd = worktreePath ?? cwd;

package/.agents/scripts/generate-skills-index.js

@@ -21,6 +21,11 @@
 //   --out <file>   Override the manifest output path (defaults to
 //                  `<root>/.agents/skills/skills.index.json`).
 //
+// Written output is passed through the project formatter (Biome) so that
+// regenerating on a clean tree leaves no format drift behind; the step is
+// best-effort and degrades to plain `JSON.stringify` output where Biome is
+// not installed. See `lib/format-generated-json.js`.
+//
 // Honors AGENT_LOG_LEVEL via the shared `Logger`. Stdout is reserved for
 // the diff text in --check failure mode; informational progress goes to
 // stderr.
@@ -30,6 +35,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseStandardCliArgs } from './lib/cli/standard-args.js';
 import { runAsCli } from './lib/cli-utils.js';
+import { formatGeneratedJson } from './lib/format-generated-json.js';
 import { Logger } from './lib/Logger.js';
 import { parseSkill } from './lib/skills/parse-skill.js';
 import { collectSkillFiles } from './lib/skills/walk-skill-files.js';
@@ -125,6 +131,12 @@ export function buildManifest(repoRoot, { nowIso } = {}) {
  * Serialize a manifest object as canonical JSON: 2-space indent,
  * trailing newline. Two runs against an unchanged corpus produce
  * byte-identical output modulo `generatedAt`.
+ *
+ * This is the *pre-format* shape. `JSON.stringify` expands every array
+ * across multiple lines, while Biome collapses short ones that fit
+ * inside `lineWidth` (`"allowedTools": ["Read", "Bash"]`). Writing this
+ * text verbatim therefore leaves the tree format-dirty on every run —
+ * see `lib/format-generated-json.js`, which reconciles the two.
  */
 export function serializeManifest(manifest) {
   return `${JSON.stringify(manifest, null, 2)}\n`;
@@ -233,8 +245,12 @@ export function run({ argv = [], now = new Date(), repoRoot } = {}) {
   }
 
   const serialized = serializeManifest(fresh);
+  const opts = { cwd: root, filename: 'skills.index.json' };
   fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(outPath, serialized);
+  fs.writeFileSync(
+    outPath,
+    formatGeneratedJson(serialized, opts) ?? serialized,
+  );
   Logger.info(
     `wrote ${path.relative(root, outPath).split(path.sep).join('/')} (${fresh.skills.length} entries)`,
   );

package/.agents/scripts/generate-workflows-doc.js

@@ -91,10 +91,10 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
     'compose. This file is only for "which command does X?" lookups.',
     '',
     'Every command file lives at `.agents/workflows/<name>.md` and is projected',
-    'into a flat `.claude/commands/` tree by `npm run sync:commands` (the',
-    'UserPromptSubmit hook keeps it current) so it shows up as a bare `/<name>`',
-    'slash command (e.g. `/deliver`). The projection writes only',
-    '`.claude/commands/<name>.md` — there is no plugin manifest and no',
+    'into a flat `.claude/commands/` tree by `npm run sync:commands` (kept',
+    'current at install time and on every `mandrel sync`/`update`) so it shows',
+    'up as a bare `/<name>` slash command (e.g. `/deliver`). The projection',
+    'writes only `.claude/commands/<name>.md` — there is no plugin manifest and no',
     'marketplace listing. The commands load in every Claude Code environment.',
     '',
     'Loop units are the one namespaced exception: files under',

package/.agents/scripts/lib/ITicketingProvider.js

@@ -1,7 +1,7 @@
 /**
  * ITicketingProvider — Abstract Ticketing Provider Interface
  *
- * All ticketing interactions in the v5 Epic-centric orchestration are mediated
+ * All ticketing interactions in the v5 Story-centric orchestration are mediated
  * through this interface. Concrete implementations (e.g., `providers/github.js`)
  * extend this class and override every method.
  *
@@ -17,21 +17,6 @@ export class ITicketingProvider {
   // Read Operations
   // ---------------------------------------------------------------------------
 
-  /**
-   * Fetch all Epic tickets in the repository.
-   *
-   * @param {{ state?: 'open'|'closed'|'all' }} [filters={}]
-   * @returns {Promise<Array<{
-   *   id: number,
-   *   title: string,
-   *   labels: string[],
-   *   state: 'open'|'closed'
-   * }>>}
-   */
-  async getEpics(_filters = {}) {
-    throw new Error('Not implemented: getEpics');
-  }
-
   /**
    * Fetch the Epic issue with its body — the single planning document
    * (ideation sections plus the folded Tech Spec / Acceptance Table
@@ -165,9 +150,6 @@ export class ITicketingProvider {
    * }} ticketData - The ticket content and metadata.
    * @returns {Promise<{ id: number, url: string }>}
    */
-  async createTicket(_parentId, _ticketData) {
-    throw new Error('Not implemented: createTicket');
-  }
 
   /**
    * Link an existing issue as a sub-issue of a parent.