mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -199,90 +199,6 @@ export function seedStoryBranchRef({
   }
 }
 
-/**
- * Ensure an Epic branch exists and is published to `origin`. Handles all
- * four states of the (local, remote) matrix.
- *
- * @param {string} epicBranch
- * @param {string} baseBranch
- * @param {string} cwd
- * @param {{ progress?: (phase: string, message: string) => void }} [opts]
- */
-export async function ensureEpicBranch(epicBranch, baseBranch, cwd, opts = {}) {
-  assertBranchSafe(epicBranch, baseBranch);
-  const progress = opts.progress ?? (() => {});
-
-  // Short-circuit: if we're already on the epic branch, just sync with remote.
-  // This avoids redundant checkout calls and prevents the edge case where
-  // branchExistsLocally returns false while we're on the branch (detached HEAD,
-  // worktree race), which would route into the create path and fail on -b.
-  const onBranch = currentBranch(cwd);
-  if (onBranch === epicBranch) {
-    const remote = branchExistsRemotely(epicBranch, cwd);
-    if (remote) {
-      progress('GIT', `Already on ${epicBranch}. Syncing with remote.`);
-      await gitPullWithRetry(cwd, 'origin', epicBranch);
-    } else {
-      progress('GIT', `Already on ${epicBranch}. Publishing to remote.`);
-      gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-    }
-    return;
-  }
-
-  const local = branchExistsLocally(epicBranch, cwd);
-  const remote = branchExistsRemotely(epicBranch, cwd);
-
-  if (!local && !remote) {
-    progress('GIT', `Creating Epic branch: ${epicBranch} (from ${baseBranch})`);
-    gitSync(cwd, 'checkout', baseBranch);
-    await gitPullWithRetry(cwd, 'origin', baseBranch);
-    gitSync(cwd, 'checkout', '-b', epicBranch);
-    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-    _assertOnBranch(cwd, epicBranch);
-    return;
-  }
-
-  if (local && !remote) {
-    progress(
-      'GIT',
-      `Epic branch exists locally only: ${epicBranch}. Publishing.`,
-    );
-    gitSync(cwd, 'checkout', epicBranch);
-    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-    _assertOnBranch(cwd, epicBranch);
-    return;
-  }
-
-  if (!local && remote) {
-    progress('GIT', `Tracking remote Epic branch: ${epicBranch}`);
-    gitSync(cwd, 'checkout', '-b', epicBranch, `origin/${epicBranch}`);
-    await gitPullWithRetry(cwd, 'origin', epicBranch);
-    _assertOnBranch(cwd, epicBranch);
-    return;
-  }
-
-  progress('GIT', `Epic branch exists. Syncing: ${epicBranch}`);
-  gitSync(cwd, 'checkout', epicBranch);
-  await gitPullWithRetry(cwd, 'origin', epicBranch);
-  _assertOnBranch(cwd, epicBranch);
-}
-
-/**
- * Post-operation assertion: verify HEAD is on the expected branch.
- * Guards against TOCTOU races where a parallel agent switches branches
- * between our checkout and pull.
- */
-function _assertOnBranch(cwd, expected) {
-  const actual = currentBranch(cwd);
-  if (actual !== expected) {
-    throw new Error(
-      `[git-branch-lifecycle] Branch assertion failed after checkout. ` +
-        `Expected HEAD on '${expected}', found '${actual}'. ` +
-        `A concurrent process may have switched branches.`,
-    );
-  }
-}
-
 /**
  * Check out a Story branch, creating it from `epicBranch` if neither local
  * nor remote exists. Non-destructive: if the branch already exists, this
@@ -337,80 +253,6 @@ export async function checkoutStoryBranch(
   gitSync(cwd, 'checkout', '-b', storyBranch, epicBranch);
 }
 
-/**
- * Ensure an Epic branch ref exists locally and is published to `origin`,
- * **without moving HEAD**. Designed for the worktree bootstrap path where
- * the main checkout must not switch branches (a parallel agent may be
- * working there, or the tree may be dirty).
- *
- * Uses `git branch` (not `checkout -b`) to create refs, and `git push` to
- * publish. Callers that need HEAD on the epic branch should use
- * `ensureEpicBranch()` instead.
- *
- * @param {string} epicBranch
- * @param {string} baseBranch
- * @param {string} cwd
- * @param {{ progress?: (phase: string, message: string) => void }} [opts]
- */
-/**
- * Pure: choose the action to take for `ensureEpicBranchRef` given whether
- * the branch exists locally and/or remotely. One of:
- *   - `'noop'` — both refs exist; nothing to do.
- *   - `'fetch'` — only remote exists; fetch into local.
- *   - `'publish-existing'` — only local exists; push it.
- *   - `'create-and-publish'` — neither exists; create from base then push.
- *
- * @param {boolean} local
- * @param {boolean} remote
- * @returns {'noop' | 'fetch' | 'publish-existing' | 'create-and-publish'}
- */
-export function planEnsureEpicBranchRefAction(local, remote) {
-  if (local) return remote ? 'noop' : 'publish-existing';
-  return remote ? 'fetch' : 'create-and-publish';
-}
-
-export function ensureEpicBranchRef(epicBranch, baseBranch, cwd, opts = {}) {
-  assertBranchSafe(epicBranch, baseBranch);
-  const progress = opts.progress ?? (() => {});
-
-  // `ensureEpicBranchRef` is always called after a `git fetch origin` (via
-  // `cachedGitFetch` / `fetchMainRefs` in `bootstrapWorktree`). The
-  // remote-tracking refs are therefore authoritative, so we check
-  // `refs/remotes/origin/<branch>` locally rather than issuing a second
-  // network `ls-remote` call.
-  const action = planEnsureEpicBranchRefAction(
-    branchExistsLocally(epicBranch, cwd),
-    branchExistsViaTrackingRef(epicBranch, cwd),
-  );
-
-  if (action === 'noop') {
-    progress('GIT', `Epic branch ref exists (local+remote): ${epicBranch}`);
-    return;
-  }
-
-  if (action === 'fetch') {
-    progress('GIT', `Fetching remote Epic branch ref: ${epicBranch}`);
-    const res = gitSpawn(cwd, 'fetch', 'origin', `${epicBranch}:${epicBranch}`);
-    if (res.status !== 0) {
-      throw new Error(
-        `ensureEpicBranchRef: failed to fetch ${epicBranch}: ${res.stderr}`,
-      );
-    }
-    return;
-  }
-
-  if (action === 'create-and-publish') {
-    progress(
-      'GIT',
-      `Creating Epic branch ref: ${epicBranch} (from ${baseBranch})`,
-    );
-    gitSync(cwd, 'branch', epicBranch, baseBranch);
-  }
-
-  progress('GIT', `Publishing Epic branch: ${epicBranch}`);
-  gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-}
-
 /**
  * Ensure an arbitrary branch exists locally, creating from `baseBranch` if
  * missing. Used by the dispatcher's task-dispatch path where the expected

package/.agents/scripts/lib/git-utils.js

@@ -315,20 +315,6 @@ export function gitPullWithRetry(cwd, ...args) {
   return gitWithContentionRetry(cwd, ['pull', '--rebase'], args);
 }
 
-/**
- * Resolves the canonical branch name for an Epic.
- * v5 Standard: epic/[EPIC_ID]
- * @param {string|number} epicId
- * @returns {string}
- */
-export function getEpicBranch(epicId) {
-  const id = typeof epicId === 'number' ? epicId : Number.parseInt(epicId, 10);
-  if (!Number.isFinite(id) || id <= 0) {
-    throw new Error(`getEpicBranch: invalid epicId: ${epicId}`);
-  }
-  return `epic/${id}`;
-}
-
 /**
  * Sanitize a string into a URL/branch-safe slug.
  * Lowercases, replaces non-alphanumeric characters with hyphens,

package/.agents/scripts/lib/json-utils.js

@@ -2,8 +2,7 @@
  * json-utils.js — shared JSON-shape helpers.
  *
  * Hoisted out of five callers (`lib/baselines/writer.js`,
- * `lib/config/defaults.js`, `lib/observability/baseline-refresh-rate.js`,
- * `lib/observability/perf-aggregator.js`, `lib/signals/schema.js`) which
+ * `lib/config/defaults.js`, `lib/signals/schema.js`) which
  * shipped functionally-equivalent copies of these predicates. See Story
  * #2464.
  *

package/.agents/scripts/lib/label-constants.js

@@ -135,20 +135,6 @@ export const PLANNING_LABELS = {
  */
 export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
 
-/**
- * Delivery-routing labels (Epic #4474 PR4 — design §2 mode matrix).
- * `delivery::single` marks an Epic whose plan was persisted in the
- * spec-only single-delivery mode: no Story tree exists and the Delivery
- * Slicing table of the Epic body's Tech Spec is the audit trail.
- * `plan-persist.js` applies it when the risk verdict declares
- * `deliveryShape: "single"`; a fan-out re-persist over the same Epic
- * removes it. The marker is **inert until #4475** lands the deliver-side
- * reader — nothing in the deliver path consumes it yet.
- */
-export const DELIVERY_LABELS = {
-  SINGLE: 'delivery::single',
-};
-
 /** Palette for the taxonomy; consumed by label-taxonomy.js. */
 export const LABEL_COLORS = {
   TYPE: '#7057FF',
@@ -156,5 +142,4 @@ export const LABEL_COLORS = {
   STATUS_BLOCKED: '#D93F0B',
   ACCEPTANCE: '#FBCA04',
   PLANNING: '#FEF2C0',
-  DELIVERY: '#BFD4F2',
 };

package/.agents/scripts/lib/label-taxonomy.js

@@ -14,7 +14,6 @@
 import {
   ACCEPTANCE_LABELS,
   AGENT_LABELS,
-  DELIVERY_LABELS,
   LABEL_COLORS,
   PLANNING_LABELS,
   STATUS_LABELS,
@@ -51,7 +50,7 @@ export const LABEL_TAXONOMY = [
   {
     name: AGENT_LABELS.CLOSING,
     color: LABEL_COLORS.AGENT,
-    description: 'Close preflight passed; awaiting merge into the Epic branch',
+    description: 'Close preflight passed; awaiting merge into the base branch',
   },
   {
     name: AGENT_LABELS.DONE,
@@ -84,16 +83,6 @@ export const LABEL_TAXONOMY = [
     description:
       'Historical operator override for the retired post-plan healthcheck',
   },
-
-  // Delivery routing — applied by `plan-persist.js` when the risk verdict
-  // declares `deliveryShape: "single"` (Epic #4474 PR4). Inert until #4475
-  // lands the deliver-side reader.
-  {
-    name: DELIVERY_LABELS.SINGLE,
-    color: LABEL_COLORS.DELIVERY,
-    description:
-      'Single-delivery plan — no Story tree; the Delivery Slicing table is the audit trail (#4474/#4475)',
-  },
 ];
 
 /** @type {Array<{ name: string, type: 'single_select', options?: string[] }>} */

package/.agents/scripts/lib/observability/active-story-env.js

@@ -2,14 +2,14 @@
  * Active-Story env-var propagation (Epic #1030 Story #1043 / Task #1061).
  *
  * The PreToolUse / PostToolUse trace hook in
- * `lib/observability/tool-trace-hook.js` resolves the active Epic +
- * Story from `process.env.CC_EPIC_ID` and `process.env.CC_STORY_ID`.
- * This module is the single writer/clearer of those vars:
+ * `lib/observability/tool-trace-hook.js` resolves the active Story from
+ * `process.env.CC_STORY_ID`. This module is the single writer/clearer of
+ * that var:
  *
- *   - `setActiveStoryEnv({ epicId, storyId, workCwd })` is called from
+ *   - `setActiveStoryEnv({ storyId, workCwd })` is called from
  *     `single-story-init.js` after the worktree is materialised. It sets the
- *     vars on the current `process.env` (so any child commands the
- *     orchestrator spawns inherit them) and exports them to a sibling
+ *     var on the current `process.env` (so any child commands the
+ *     orchestrator spawns inherit it) and exports it to a sibling
  *     `.env.local` inside the worktree. The harness re-spawns the
  *     agent with that file's contents loaded, so the trace hook fires
  *     with the right ids on the *next* tool call after init returns.
@@ -37,96 +37,76 @@ const ENV_LOCAL_BASENAME = '.env.local';
 /**
  * Names of the env vars we own. Keeping the list central makes the
  * round-trip (set on init, clear on close) trivially auditable —
- * grep `CC_EPIC_ID` / `CC_STORY_ID` / `CC_SLICE_ID` to find every read site.
- *
- * Epic #4476 (M5) added `CC_SLICE_ID` (the single-delivery analogue of
- * `CC_STORY_ID` — set on the ONE long guarded session so the PostToolUse
- * hook can emit `slice.heartbeat` off the token stream) and `CC_OPERATOR`
- * (the resolved lease-owner handle, stamped onto hook-emitted heartbeats so
- * `latestHeartbeatForOwner` keeps resolving a live claim). The clear path
- * wipes all four so no stale context leaks past close.
+ * grep `CC_STORY_ID` / `CC_EPIC_ID` to find every read site.
+ *
+ * `CC_STORY_ID` is the one var this module writes. `CC_EPIC_ID` is retained
+ * on the CLEAR path only: v2 has no Epics and nothing here sets it, but
+ * `tool-trace-hook.js`'s `resolveActiveStory` still reads it, so wiping it at
+ * close keeps the trace path's "no stale context past close" contract honest
+ * against a value that leaked in from outside (a pre-upgrade `.env.local` the
+ * harness already loaded, or an operator's shell).
+ *
+ * `CC_SLICE_ID` / `CC_OPERATOR` were removed with the heartbeat substrate:
+ * their only writer was the never-called `setActiveSliceEnv` and their only
+ * reader the deleted `hook-heartbeat.js`.
  */
-export const ACTIVE_STORY_ENV_KEYS = [
-  'CC_EPIC_ID',
-  'CC_STORY_ID',
-  'CC_SLICE_ID',
-  'CC_OPERATOR',
-];
+export const ACTIVE_STORY_ENV_KEYS = ['CC_EPIC_ID', 'CC_STORY_ID'];
 
 /**
  * Render the `.env.local` body. One `KEY=value` line per var, LF
  * line endings (the harness's dotenv parser tolerates CRLF too but LF
  * keeps the file deterministic across Windows / macOS / Linux).
  *
- * Story #2874 — when `epicId === null` (standalone Story, no parent
- * Epic), the `CC_EPIC_ID=` line is omitted entirely. The trace
- * hook's no-op contract reads "var absent from env" as the signal,
- * so emitting an empty `CC_EPIC_ID=` line would set the var to the
- * empty string and change the contract.
+ * Only `CC_STORY_ID` is emitted: v2 Stories are standalone, so there is no
+ * parent Epic to key. The trace hook's no-op contract reads "var absent from
+ * env" as the signal, so no `CC_EPIC_ID=` line is written at all — an empty
+ * one would set the var to the empty string and change the contract.
  *
  * Exported for testing.
  *
- * @param {{ epicId: number|null, storyId: number }} input
+ * @param {{ storyId: number }} input
  * @returns {string}
  */
-export function renderActiveStoryEnvFile({ epicId, storyId }) {
-  const lines = [
+export function renderActiveStoryEnvFile({ storyId }) {
+  return [
     '# Auto-managed by .agents/scripts/lib/observability/active-story-env.js',
     '# Re-generated on every story-init; deleted on story-close.',
-  ];
-  if (epicId !== null) lines.push(`CC_EPIC_ID=${epicId}`);
-  lines.push(`CC_STORY_ID=${storyId}`, '');
-  return lines.join('\n');
+    `CC_STORY_ID=${storyId}`,
+    '',
+  ].join('\n');
 }
 
 /**
- * Set `CC_EPIC_ID` / `CC_STORY_ID` on the current process and (when
- * `workCwd` is provided) export them to `<workCwd>/.env.local`.
+ * Set `CC_STORY_ID` on the current process and (when `workCwd` is provided)
+ * export it to `<workCwd>/.env.local`.
  *
- * Idempotent: re-running with the same ids is a no-op on disk; with
- * different ids the `.env.local` is overwritten.
+ * Idempotent: re-running with the same id is a no-op on disk; with a
+ * different id the `.env.local` is overwritten.
  *
- * Story #2874 — `epicId: null` is the standalone-Story sentinel.
- * When passed:
- *   - `CC_EPIC_ID` is removed from `env` (the var MUST NOT be set
- *     to an empty string — the trace hook's `resolveActiveStory`
- *     no-op contract is keyed on the var's absence).
- *   - The rendered `.env.local` omits the `CC_EPIC_ID=` line.
- *   - `CC_STORY_ID` behaviour is unchanged.
- * All other invalid `epicId` values (`0`, negative, NaN, non-integer)
- * still throw — `null` is the only standalone signal.
+ * v2 Stories are standalone — there is no parent Epic — so `CC_EPIC_ID` is
+ * never set, and any pre-existing value is removed: the trace hook's
+ * `resolveActiveStory` no-op contract is keyed on the var's absence, and a
+ * stale epic id would key this Story's traces to a foreign Epic directory.
  *
- * @param {{ epicId: number|null, storyId: number, workCwd?: string,
+ * @param {{ storyId: number, workCwd?: string,
  *           env?: NodeJS.ProcessEnv, fs?: typeof nodeFs,
  *           logger?: { warn?: (m: string) => void } }} args
  * @returns {{ envSet: boolean, fileWritten: boolean, filePath: string|null }}
  */
 export function setActiveStoryEnv({
-  epicId,
   storyId,
   workCwd,
   env = process.env,
   fs = nodeFs,
   logger,
 } = {}) {
-  if (epicId !== null && (!Number.isInteger(epicId) || epicId <= 0)) {
-    throw new Error(
-      `[active-story-env] epicId must be a positive integer or null; got ${epicId}`,
-    );
-  }
   if (!Number.isInteger(storyId) || storyId <= 0) {
     throw new Error(
       `[active-story-env] storyId must be a positive integer; got ${storyId}`,
     );
   }
 
-  if (epicId === null) {
-    // Standalone Story — ensure CC_EPIC_ID is absent so the trace
-    // hook's no-op contract sees "no epic" rather than "epic=''".
-    if ('CC_EPIC_ID' in env) delete env.CC_EPIC_ID;
-  } else {
-    env.CC_EPIC_ID = String(epicId);
-  }
+  if ('CC_EPIC_ID' in env) delete env.CC_EPIC_ID;
   env.CC_STORY_ID = String(storyId);
 
   let fileWritten = false;
@@ -134,13 +114,9 @@ export function setActiveStoryEnv({
   if (typeof workCwd === 'string' && workCwd.length > 0) {
     filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
     try {
-      fs.writeFileSync(
-        filePath,
-        renderActiveStoryEnvFile({ epicId, storyId }),
-        {
-          encoding: 'utf8',
-        },
-      );
+      fs.writeFileSync(filePath, renderActiveStoryEnvFile({ storyId }), {
+        encoding: 'utf8',
+      });
       fileWritten = true;
     } catch (err) {
       logger?.warn?.(
@@ -192,100 +168,3 @@ export function clearActiveStoryEnv({
   }
   return { envCleared: true, fileRemoved, filePath };
 }
-
-/**
- * Render the single-delivery `.env.local` body. The single-delivery executor
- * (`deliver-epic-single.md`) walks the Delivery Slicing table inside ONE long
- * session; there is no Story fan-out and thus no `CC_STORY_ID`. Instead the
- * "current slice" is exported as `CC_SLICE_ID` so the PostToolUse hook emits
- * `slice.heartbeat` — the watchdog's forward-progress signal for the single
- * session — as a free byproduct of tool activity.
- *
- * `CC_STORY_ID` MUST be absent (its presence would make the hook emit
- * `story.heartbeat` and the trace path key off a non-existent Story). The
- * optional `operator` handle is emitted as `CC_OPERATOR` only when supplied.
- *
- * Exported for testing.
- *
- * @param {{ epicId: number, sliceId: string, operator?: string }} input
- * @returns {string}
- */
-export function renderActiveSliceEnvFile({ epicId, sliceId, operator }) {
-  const lines = [
-    '# Auto-managed by .agents/scripts/lib/observability/active-story-env.js',
-    '# Re-generated on every slice-start; deleted on epic-close.',
-    `CC_EPIC_ID=${epicId}`,
-    `CC_SLICE_ID=${sliceId}`,
-  ];
-  if (typeof operator === 'string' && operator.length > 0) {
-    lines.push(`CC_OPERATOR=${operator}`);
-  }
-  lines.push('');
-  return lines.join('\n');
-}
-
-/**
- * Set `CC_EPIC_ID` / `CC_SLICE_ID` (+ optional `CC_OPERATOR`) on the current
- * process and, when `workCwd` is provided, export them to
- * `<workCwd>/.env.local` for the harness to reload on the next tool call. The
- * single-delivery analogue of {@link setActiveStoryEnv}; called at each
- * `slice.start` boundary so the hook's throttled `slice.heartbeat` is keyed to
- * the slice currently being implemented.
- *
- * `CC_STORY_ID` is explicitly removed so a prior Story context (if any ever
- * leaked in) cannot make the hook emit the wrong heartbeat shape.
- *
- * @param {{ epicId: number, sliceId: string, operator?: string|null,
- *           workCwd?: string, env?: NodeJS.ProcessEnv, fs?: typeof nodeFs,
- *           logger?: { warn?: (m: string) => void } }} args
- * @returns {{ envSet: boolean, fileWritten: boolean, filePath: string|null }}
- */
-export function setActiveSliceEnv({
-  epicId,
-  sliceId,
-  operator,
-  workCwd,
-  env = process.env,
-  fs = nodeFs,
-  logger,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new Error(
-      `[active-story-env] epicId must be a positive integer; got ${epicId}`,
-    );
-  }
-  if (typeof sliceId !== 'string' || sliceId.length === 0) {
-    throw new Error(
-      `[active-story-env] sliceId must be a non-empty string; got ${sliceId}`,
-    );
-  }
-  const normOperator =
-    typeof operator === 'string' && operator.length > 0 ? operator : undefined;
-
-  if ('CC_STORY_ID' in env) delete env.CC_STORY_ID;
-  env.CC_EPIC_ID = String(epicId);
-  env.CC_SLICE_ID = sliceId;
-  if (normOperator) env.CC_OPERATOR = normOperator;
-  else if ('CC_OPERATOR' in env) delete env.CC_OPERATOR;
-
-  let fileWritten = false;
-  let filePath = null;
-  if (typeof workCwd === 'string' && workCwd.length > 0) {
-    filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
-    try {
-      fs.writeFileSync(
-        filePath,
-        renderActiveSliceEnvFile({ epicId, sliceId, operator: normOperator }),
-        { encoding: 'utf8' },
-      );
-      fileWritten = true;
-    } catch (err) {
-      logger?.warn?.(
-        `[active-story-env] Failed to write ${filePath}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-  }
-  return { envSet: true, fileWritten, filePath };
-}