mandrel 2.0.0 → 2.1.0

package/.agents/scripts/lib/validation-evidence.js

@@ -3,15 +3,12 @@
  *
  * Tech Spec #819 §"Evidence record (Story 7)". Each successful gate run
  * writes a record keyed by `{ gateName, commitSha, commandConfigHash }` to
- * a per-Epic-tree path under the resolved `tempRoot`:
+ * a storyId-anchored path under the resolved `tempRoot`:
  *
- *   - Epic-scoped (scopeId === epicId):
- *       `<tempRoot>/epic-<epicId>/validation-evidence.json`
- *   - Story-scoped (scopeId === storyId):
- *       `<tempRoot>/epic-<epicId>/story-<storyId>/validation-evidence.json`
+ *   `<tempRoot>/standalone/stories/story-<storyId>/validation-evidence.json`
  *
- * Both paths sit inside the per-Epic durable workspace (Epic #1030, Stories
- * #1039 + #1054) and are gitignored via `temp/`.
+ * The path is gitignored via `temp/`. v2.0.0 removed the Epic tier along
+ * with the Epic-keyed `<tempRoot>/epic-<epicId>/…` keyspace.
  *
  * A subsequent caller can `shouldSkip(...)` to learn whether the same gate
  * has already passed against the current HEAD with an identical
@@ -34,7 +31,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Ajv from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
-import { epicTempDir, storyTempDir } from './config/temp-paths.js';
+import { storyTempDir } from './config/temp-paths.js';
 
 export const SCHEMA_VERSION = 1;
 const DEFAULT_TEMP_DIR = 'temp';
@@ -97,37 +94,28 @@ function requirePositiveInt(value, label) {
 
 /**
  * Compute the absolute path of the evidence file for `scopeId` under the
- * per-Epic temp tree.
+ * storyId-anchored temp tree.
  *
- * The resolution rule mirrors `lib/config/temp-paths.js`:
- *   - `scopeId === epicId` → `<tempRoot>/epic-<epicId>/validation-evidence.json`
- *   - `scopeId !== epicId` → treated as a Story id → `<tempRoot>/epic-<epicId>/story-<scopeId>/validation-evidence.json`
- *
- * **Standalone keyspace (Story #4250).** When `opts.standalone === true`,
+ * **Standalone keyspace (Story #4250).** `opts.standalone` must be `true`:
  * the Story has no parent Epic, so the evidence file is anchored on the
  * Story id alone at
  * `<tempRoot>/standalone/stories/story-<scopeId>/validation-evidence.json`
- * (the `storyTempDir(null, sid)` layout from Story #2874). In this mode
- * `epicId` is ignored — callers MUST NOT feed a `0`/`null` epicId into the
- * Epic-keyed branch (the historical bug this keyspace replaces). Outside
- * standalone mode `epicId` remains required.
+ * (the `storyTempDir(null, sid)` layout from Story #2874).
  *
- * The legacy flat `temp/validation-evidence-<scopeId>.json` layout is no
- * longer supported — Epic-scoped callers must thread the Epic id through
- * (Epic #1030 follow-up to Story #1054). The synthetic config bag passed to
- * `epicTempDir` / `storyTempDir` keeps the resolver from doing a disk-bound
- * `.agentrc.json` lookup; bare callers can pass `tempDir` via `opts` to
- * override the default `'temp'`.
+ * The legacy flat `temp/validation-evidence-<scopeId>.json` layout and the
+ * Epic-keyed `<tempRoot>/epic-<epicId>/…` layout are both gone. The
+ * synthetic config bag passed to `storyTempDir` keeps the resolver from
+ * doing a disk-bound `.agentrc.json` lookup; bare callers can pass
+ * `tempDir` via `opts` to override the default `'temp'`.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean }} opts
  * @returns {string}
  */
 export function evidencePath(scopeId, opts = {}) {
-  const standalone = opts.standalone === true;
-  if (!standalone && opts.epicId == null) {
+  if (opts.standalone !== true) {
     throw new Error(
-      '[validation-evidence] evidencePath requires opts.epicId (Epic-scoped path resolution) unless opts.standalone is set.',
+      '[validation-evidence] evidencePath requires opts.standalone (the storyId-anchored keyspace is the only keyspace).',
     );
   }
   const { cwd, tempDir } = resolveOpts(opts);
@@ -143,18 +131,9 @@ export function evidencePath(scopeId, opts = {}) {
     ? tempDir
     : path.join(cwd, tempDir);
   const configBag = { project: { paths: { tempRoot: absTempRoot } } };
-  let dir;
-  if (standalone) {
-    // Story #4250 — storyId-anchored standalone keyspace. `null` is the
-    // standalone-story sentinel `storyTempDir` accepts (Story #2874).
-    dir = storyTempDir(null, scope, configBag);
-  } else {
-    const epicId = requirePositiveInt(opts.epicId, 'epicId');
-    dir =
-      scope === epicId
-        ? epicTempDir(epicId, configBag)
-        : storyTempDir(epicId, scope, configBag);
-  }
+  // Story #4250 — storyId-anchored standalone keyspace. `null` is the
+  // standalone-story sentinel `storyTempDir` accepts (Story #2874).
+  const dir = storyTempDir(null, scope, configBag);
   return path.join(dir, EVIDENCE_FILENAME);
 }
 
@@ -189,19 +168,17 @@ function emptyDoc(scopeId) {
  * cross-scopeId cases — callers don't have to branch on those failure
  * modes; they manifest as `shouldSkip()` returning `skip: false`.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace.
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object }} opts
  * @returns {{ storyId: number, schemaVersion: number, records: object[] }}
  */
 export function loadEvidence(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
   const file = evidencePath(scopeId, {
     ...resolved,
-    epicId: opts.epicId,
     standalone: opts.standalone,
   });
   if (!resolved.fs.existsSync(file)) return emptyDoc(scopeId);
@@ -223,9 +200,8 @@ export function loadEvidence(scopeId, opts = {}) {
  * Validates the resulting document against the schema before writing — a
  * malformed write throws so the bug surfaces immediately.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace.
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace.
  *
  * @param {{
  *   storyId: number|string,
@@ -235,7 +211,7 @@ export function loadEvidence(scopeId, opts = {}) {
  *   exitCode?: number,
  *   durationMs?: number|null,
  * }} input
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object, now?: Function }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object, now?: Function }} opts
  * @returns {object} The persisted record.
  */
 export function recordPass(
@@ -258,7 +234,6 @@ export function recordPass(
   const resolved = resolveOpts(opts);
   const evidenceOpts = {
     ...resolved,
-    epicId: opts.epicId,
     standalone: opts.standalone,
   };
   const doc = loadEvidence(storyId, evidenceOpts);
@@ -297,13 +272,12 @@ export function recordPass(
  * with a machine-readable `reason` so callers can log why the skip didn't
  * fire.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace. `opts` is forwarded verbatim to
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace. `opts` is forwarded verbatim to
  * `loadEvidence`, so `standalone` flows through unchanged.
  *
  * @param {{ storyId: number|string, gateName: string, currentSha: string, configHash: string }} input
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object }} opts
  * @returns {{ skip: boolean, reason: string, record?: object }}
  */
 export function shouldSkip(
@@ -340,19 +314,17 @@ export function shouldSkip(
  * start of each Story so a re-run always starts clean. Idempotent —
  * absent file is not an error.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved,
- * unless `opts.standalone === true` (Story #4250) routes to the
- * storyId-anchored standalone keyspace.
+ * `opts.standalone` is required (Story #4250) — it routes to the
+ * storyId-anchored keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object }} opts
  * @returns {{ cleared: boolean, path: string }}
  */
 export function forceClear(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
   const file = evidencePath(scopeId, {
     ...resolved,
-    epicId: opts.epicId,
     standalone: opts.standalone,
   });
   if (!resolved.fs.existsSync(file)) return { cleared: false, path: file };

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -156,15 +156,37 @@ export function storyFootprint(story) {
   return out;
 }
 
+/**
+ * Does a declared path contain a glob metacharacter? Mirrors the detection
+ * in `story-body.js#extractChangePaths`, whose `isGlob` flag documents an
+ * "unknown-width footprint" policy that was never implemented downstream.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+function isGlobPath(path) {
+  return path.includes('*') || path.includes('?') || path.includes('{');
+}
+
 /**
  * File-overlap co-dispatch guard. Returns `true` when two Stories' declared
- * file footprints intersect on at least one path — meaning they would race
- * the same file if dispatched onto parallel `story-<id>` branches in the
- * same beat. Two Stories that overlap MUST NOT both appear in one dispatch
- * set; one is withheld until the other clears.
+ * file footprints intersect — meaning they would race the same file if
+ * dispatched onto parallel `story-<id>` branches in the same beat. Two
+ * Stories that overlap MUST NOT both appear in one dispatch set; one is
+ * withheld until the other clears.
  *
- * An empty footprint on either side means "no known overlap" → `false`. A
- * Story that declares no files is therefore never withheld by this guard.
+ * Two deliberate asymmetries:
+ *
+ *   - **An empty footprint means "no known overlap"** → `false`. A Story that
+ *     declares no files is never withheld. This is permissive by necessity:
+ *     an undeclared footprint carries no information, and withholding on
+ *     absence would serialize every run.
+ *   - **A glob footprint overlaps EVERYTHING** → `true` (Story #4539/#4540).
+ *     Comparison is exact-string, so a Story declaring
+ *     `.agents/scripts/lib/**` would not match another declaring
+ *     `.agents/scripts/lib/story-adjacency.js` — the guard would silently
+ *     pass two Stories that genuinely race. Unknown width is not the same as
+ *     no width: fail safe by serializing.
  *
  * @param {StoryRecord} a
  * @param {StoryRecord} b
@@ -176,8 +198,12 @@ export function storiesOverlap(a, b) {
   const fb = storyFootprint(b);
   if (fb.size === 0) return false;
   for (const path of fa) {
+    if (isGlobPath(path)) return true;
     if (fb.has(path)) return true;
   }
+  for (const path of fb) {
+    if (isGlobPath(path)) return true;
+  }
   return false;
 }
 

package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js

@@ -7,7 +7,7 @@
  * on a Windows lock-class failure, the entry is appended to
  * `.worktrees/.pending-cleanup.json`. The plan-time `worktree-sweep.js`
  * reader (shipped in Epic #349) picks up the manifest on the next
- * `/epic-plan-spec` / `/epic-plan-decompose` runs and retries removal
+ * `/plan` run and retries removal
  * (`git worktree remove` then `fs.rm`) — by then the live file handles from Node / AV / the Windows
  * Search indexer are almost always gone. If `MAX_SWEEP_ATTEMPTS` elapses
  * without clearing, an `OPERATOR ACTION REQUIRED: persistent-lock` line

package/.agents/scripts/lib/worktree/lifecycle/reap.js

@@ -15,7 +15,7 @@
 
 import fs from 'node:fs';
 import { rm as fsPromisesRm } from 'node:fs/promises';
-import { isInsideWorktree, samePath, storyIdFromPath } from '../inspector.js';
+import { isInsideWorktree, samePath } from '../inspector.js';
 import { sleepSync } from '../node-modules-strategy.js';
 import { checkMergeReachability } from './merge-reachability.js';
 import { recordPendingCleanup } from './pending-cleanup.js';
@@ -72,21 +72,58 @@ export async function isSafeToRemove(ctx, wtPath, opts = {}) {
 }
 
 /**
- * Returns true iff `branch` is already fully merged into `epicBranch`
- * (i.e. `merge-base --is-ancestor branch epicBranch` exits 0). A missing
- * epicBranch or a git failure both yield false so callers default to the
- * safe, non-forcing behavior.
+ * Returns true iff `branch`'s work is demonstrably already integrated into
+ * `baseRef`. Used only to license discarding a **dirty** tree, so it must
+ * err toward `false`.
+ *
+ * Two-phase:
+ *   1. `merge-base --is-ancestor` — cheap SHA reachability; true for
+ *      fast-forward and merge-commit integration.
+ *   2. `git cherry <baseRef> <branch>` — compares **patch-ids** rather than
+ *      SHAs, marking a commit `-` when an equivalent change already exists
+ *      upstream. All-`-` (or empty) means every commit on the branch is
+ *      present in the base under some SHA.
+ *
+ * **Known limit — this is not a general squash detector.** A squash collapses
+ * N commits into ONE new commit whose patch equals their *combined* diff, so
+ * no individual original commit has an upstream patch-id equivalent and
+ * `git cherry` marks them all `+`. Phase 2 therefore only recognises a
+ * squash-landed branch when the branch had a **single** commit (verified
+ * empirically, Story #4539). A multi-commit squash still reads as unmerged
+ * and the dirty tree is refused — the safe direction, and the same answer
+ * the previous ancestor-only check gave. Detecting the general case needs
+ * the PR's merged state, which this module has no client for.
+ *
+ * A missing ref or a git failure yields false, so callers default to the
+ * safe, non-forcing behavior. Module-private: `ensureSafeOrForceDiscard` is
+ * its only caller, and the symbol it replaced was exported with no consumer
+ * and then baselined as a dead export — repeating that would just hide a
+ * new corpse.
+ *
+ * @param {object} ctx
+ * @param {string} branch
+ * @param {string} baseRef
+ * @returns {boolean}
  */
-export function isStoryAlreadyMergedIntoEpic(ctx, branch, epicBranch) {
-  if (!branch || !epicBranch) return false;
-  const res = ctx.git.gitSpawn(
+function isBranchMergedIntoBase(ctx, branch, baseRef) {
+  if (!branch || !baseRef) return false;
+  const ancestor = ctx.git.gitSpawn(
     ctx.repoRoot,
     'merge-base',
     '--is-ancestor',
     branch,
-    epicBranch,
+    baseRef,
   );
-  return res.status === 0;
+  if (ancestor.status === 0) return true;
+
+  const cherry = ctx.git.gitSpawn(ctx.repoRoot, 'cherry', baseRef, branch);
+  if (cherry.status !== 0) return false;
+  const lines = (cherry.stdout ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  // Every line starting with '+' is a commit with no upstream equivalent.
+  return lines.every((line) => line.startsWith('-'));
 }
 
 /**
@@ -470,28 +507,40 @@ function checkReapPreconditions(ctx, _storyId, opts, wtPath) {
       ok: false,
       result: { removed: false, reason: 'not-a-worktree', path: wtPath },
     };
-  if (storyIdFromPath(wtPath, ctx.worktreeRoot) !== null && !opts.epicBranch) {
-    return {
-      ok: false,
-      result: { removed: false, reason: 'epic-branch-required', path: wtPath },
-    };
-  }
+  // Story #4539 removed an `epic-branch-required` gate here: a
+  // `story-<id>` worktree used to be unreapable unless the caller supplied
+  // an Epic integration branch. v2 has no Epic branch, and the only v2
+  // caller (the close path) never passed one — so EVERY close silently
+  // failed to reap while reporting success, and cleanup fell to the next
+  // boot-sweep.
+  //
+  // Nothing is lost by dropping it. The close path reaps AFTER pushing
+  // `story-<id>` to origin and opening the PR, so the work is durable
+  // off-machine; and the real safety net is unchanged — `isSafeToRemove`
+  // still refuses a dirty tree (`uncommitted-changes`), which is what
+  // actually protects unsaved work.
   return { ok: true };
 }
 
 async function ensureSafeOrForceDiscard(ctx, storyId, wtPath, opts) {
+  const baseRef = opts.baseRef ?? opts.epicBranch ?? null;
   const safety = await isSafeToRemove(ctx, wtPath, {
-    epicBranch: opts.epicBranch ?? null,
+    epicBranch: baseRef,
   });
   if (safety.safe) return { ok: true, discardedPaths: null };
 
   const discardAfterMerge = opts.discardAfterMerge !== false;
   const branchName = `story-${validateStoryId(storyId)}`;
+  // Discarding a dirty tree is only permissible when the branch's work is
+  // demonstrably already integrated. See `isBranchMergedIntoBase` for what
+  // that can and cannot prove — notably a multi-commit squash reads as
+  // unmerged, so the discard is refused and the tree survives. Refusing is
+  // the safe direction: the cost is a stale worktree, not lost work.
   const canForceReap =
     discardAfterMerge &&
     safety.reason === 'uncommitted-changes' &&
-    opts.epicBranch &&
-    isStoryAlreadyMergedIntoEpic(ctx, branchName, opts.epicBranch);
+    baseRef &&
+    isBranchMergedIntoBase(ctx, branchName, baseRef);
   if (!canForceReap) {
     ctx.logger.warn(
       `reap-skipped storyId=${storyId} reason=${safety.reason} path=${wtPath}`,

package/.agents/scripts/lib/worktree/lifecycle-manager.js

@@ -7,7 +7,7 @@
  *   - `creation.js`         — `ensure`
  *   - `registry-sync.js`    — `pathFor`, `list`, `prune`, `getWorktreeList`,
  *                             `invalidateWorktreeCache`, `findByPath`
- *   - `reap.js`             — `isSafeToRemove`, `isStoryAlreadyMergedIntoEpic`,
+ *   - `reap.js`             — `isSafeToRemove`,
  *                             `removeWorktreeWithRecovery`, `reap`
  *   - `gc.js`               — `gc`
  *   - `drift-detection.js`  — `sweepStaleLocks`
@@ -26,7 +26,6 @@ export { sweepStaleLocks } from './lifecycle/drift-detection.js';
 export { gc } from './lifecycle/gc.js';
 export {
   isSafeToRemove,
-  isStoryAlreadyMergedIntoEpic,
   reap,
   removeWorktreeWithRecovery,
 } from './lifecycle/reap.js';

package/.agents/scripts/plan-context.js

@@ -18,8 +18,14 @@
  *                             Stories. Envelope carries `sourceTickets[]`.
  *
  * Flags:
+ *   --out <path>     Also write the envelope to <path> (parent dirs created).
+ *                    `/plan` points this at `<plan-dir>/plan-context.json`,
+ *                    which is where `plan-persist.js` auto-discovers the
+ *                    `--tickets` source ids from (Story #4554). Without a
+ *                    captured envelope persist cannot know a `--tickets` run
+ *                    happened, and superseding degrades to the
+ *                    `--source-tickets` flag.
  *   --pretty         Pretty-print the JSON envelope.
- *   --full-context   Bypass the planning-context budget (unbounded body).
  *
  * stdout is reserved for the JSON envelope (Story #2278 discipline):
  * `routeAllOutputToStderr()` runs before any pipeline code so a captured
@@ -34,13 +40,15 @@
 // first import so the check runs before any third-party-importing sibling
 // module is evaluated (Story #3432).
 import './lib/runtime-deps/ensure-installed.js';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import {
   resolveConfig,
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
-import { routeAllOutputToStderr } from './lib/Logger.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
 import { buildPlanContext } from './lib/orchestration/plan-context.js';
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
@@ -84,8 +92,8 @@ export async function emitPlanContext({
   provider,
   config,
   settings,
-  fullContext = false,
   pretty = false,
+  outPath = null,
   cwd,
   stdout = process.stdout,
 }) {
@@ -98,24 +106,48 @@ export async function emitPlanContext({
     provider,
     config,
     settings,
-    fullContext,
     cwd,
   });
   const json = pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
   stdout.write(`${json}\n`);
+  if (outPath) await writeEnvelopeFile(outPath, json);
   return envelope;
 }
 
+/**
+ * Persist the envelope to `--out` so `plan-persist.js` can derive the
+ * `--tickets` source ids from it without an operator re-typing them.
+ *
+ * Writing is part of emitting, not a best-effort extra: a failed write means
+ * persist will silently see no source tickets, so it throws rather than
+ * warning past the problem.
+ *
+ * @param {string} outPath
+ * @param {string} json
+ */
+async function writeEnvelopeFile(outPath, json) {
+  const resolved = path.resolve(outPath);
+  try {
+    await mkdir(path.dirname(resolved), { recursive: true });
+    await writeFile(resolved, `${json}\n`, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `[plan-context] cannot write envelope to ${resolved}: ${err.message}`,
+    );
+  }
+  Logger.info(`[plan-context] wrote envelope to ${resolved}`);
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {
       seed: { type: 'string' },
       'seed-file': { type: 'string' },
       tickets: { type: 'string' },
+      out: { type: 'string' },
       pretty: { type: 'boolean', default: false },
-      'full-context': { type: 'boolean', default: false },
     },
     strict: true,
   });
@@ -185,8 +217,8 @@ async function main() {
         provider,
         config,
         settings,
-        fullContext: values['full-context'],
         pretty: values.pretty,
+        outPath: values.out || null,
       }),
   );
 }