mandrel 2.30.0 → 2.32.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js

@@ -0,0 +1,157 @@
+/**
+ * phases/review-override.js — the sanctioned, logged override of a Story-scope
+ * code-review critical blocker.
+ *
+ * Split out of `phases/review-block.js`, which owns the opposite outcome: the
+ * blocker that *holds*. Keeping the two in one module meant one file owning
+ * both "park this Story" and "ship it anyway", and the override's audit trail is
+ * substantial enough — three write surfaces, each independently best-effort —
+ * to be its own reason to change.
+ *
+ * **Why an override exists at all.** A critical review finding halts
+ * `single-story-close.js` before auto-merge, and no flag overrode a review
+ * verdict: `--skip-validation` bypasses the gate chain and `--no-auto-merge`
+ * declines to arm, but neither touches the review. So an operator who had read a
+ * finding and judged it wrong could only land by merging the PR by hand, which
+ * bypasses the gate with no record anywhere of what was overridden or why. This
+ * module does not weaken the gate; it relocates that escape hatch out of an
+ * untraceable hand-merge and into a mandatory-reason audit trail.
+ *
+ * Live provenance: Story #5007 / PR #5022, where a FALSE critical blocker — an
+ * MI finding on files `delivery.quality.gates.maintainability.ignoreGlobs`
+ * exempts, which the `check-baselines.js` ratchet correctly ignored in the same
+ * run — halted a legitimate delivery with a hand-merge as the only way out.
+ */
+
+import { Logger } from '../../../Logger.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../../observability/runtime-friction.js';
+import {
+  postStructuredComment,
+  upsertStructuredComment,
+} from '../../ticketing.js';
+
+/** Cap on the reason text copied into the friction signal's `details`. */
+const REASON_SIGNAL_LIMIT = 500;
+
+/**
+ * Build the audit record posted when an operator overrides a review blocker.
+ * Pure.
+ *
+ * The body restates the count, the reason, and the fact that auto-merge was
+ * armed anyway — an override whose trail says only "overridden" is no better
+ * than the hand-merge it replaces.
+ *
+ * Module-local: an implementation detail of
+ * {@link handleOverriddenReviewBlock}, whose posted body is observable through
+ * that public entry point. Exporting it would add a public symbol no production
+ * path reaches — the exact dead-export shape this repo ratchets against.
+ *
+ * @param {{ prUrl: string, criticalCount: number, reason: string }} args
+ * @returns {string}
+ */
+function buildReviewOverrideBody({ prUrl, criticalCount, reason }) {
+  return [
+    '### Code-review blocker overridden by operator',
+    '',
+    `The Story-scope review reported **${criticalCount} critical blocker(s)** on ${prUrl}.`,
+    'The operator reviewed and rejected the finding(s) and authorized delivery',
+    'with `--override-review-block`; auto-merge was armed.',
+    '',
+    '**Recorded reason:**',
+    '',
+    `> ${reason.split('\n').join('\n> ')}`,
+    '',
+    'The findings comment on the PR is left in place unchanged — this record',
+    'sits beside it rather than resolving it.',
+  ].join('\n');
+}
+
+/**
+ * Post one audit record, swallowing the failure into a warning.
+ *
+ * Every write here is best-effort by design: an override whose audit trail
+ * partly failed must still land the delivery the operator authorized, because
+ * the close would otherwise fail for a reason the operator cannot act on. The
+ * friction signal is the durable record — it is what makes a rising override
+ * count visible to the retro.
+ *
+ * Module-local: the two call sites below are its only callers.
+ *
+ * @param {{ post: () => Promise<unknown>, surface: string }} args
+ * @returns {Promise<boolean>} true when the record landed.
+ */
+async function postAuditRecord({ post, surface }) {
+  try {
+    await post();
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[single-story-close] failed to post review-override record on ${surface}: ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Record an operator-authorized override of a critical code-review blocker,
+ * then let close continue to the auto-merge phase.
+ *
+ * Writes to three surfaces: the Story issue via `upsert` so a re-run does not
+ * stack duplicates; the PR via `post` so the trail is append-only on the surface
+ * a human reviews, and so a reviewer reading the PR need not open the Story to
+ * learn the blocker was overridden; and the friction stream.
+ *
+ * @param {{
+ *   provider: object,
+ *   storyId: number,
+ *   prUrl: string,
+ *   prNumber: number|null,
+ *   criticalCount: number,
+ *   reason: string,
+ *   config?: object,
+ *   emitFrictionFn?: typeof emitRuntimeFriction,
+ * }} args
+ * @returns {Promise<{ overridden: true, reason: string, criticalCount: number }>}
+ */
+export async function handleOverriddenReviewBlock({
+  provider,
+  storyId,
+  prUrl,
+  prNumber,
+  criticalCount,
+  reason,
+  config,
+  emitFrictionFn = emitRuntimeFriction,
+}) {
+  const body = buildReviewOverrideBody({ prUrl, criticalCount, reason });
+  Logger.warn(
+    `[single-story-close] ⚠️ Story-scope review reported ${criticalCount} critical blocker(s) on ` +
+      `PR ${prUrl} — OVERRIDDEN by operator: ${reason}`,
+  );
+  await postAuditRecord({
+    post: () => upsertStructuredComment(provider, storyId, 'friction', body),
+    surface: `Story #${storyId}`,
+  });
+  if (Number.isInteger(prNumber)) {
+    await postAuditRecord({
+      post: () =>
+        postStructuredComment(provider, prNumber, 'notification', body),
+      surface: `PR #${prNumber}`,
+    });
+  }
+  await emitFrictionFn({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCK_OVERRIDDEN,
+    tool: 'single-story-close',
+    details: {
+      prUrl,
+      criticalCount,
+      reason: reason.slice(0, REASON_SIGNAL_LIMIT),
+    },
+    config,
+  });
+  return { overridden: true, reason, criticalCount };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js

@@ -16,13 +16,9 @@
  * actually reaped and every close said it did. Best-effort means the close
  * still succeeds on refusal; it does not mean the close may claim an
  * outcome it never checked.
- *
- * Also clears the trace-hook env vars so subsequent tooling falls back to
- * the no-op branch instead of pointing at a (now-reaped) worktree.
  */
 
 import { Logger } from '../../../Logger.js';
-import { clearActiveStoryEnv } from '../../../observability/active-story-env.js';
 import { WorktreeManager as DefaultWorktreeManager } from '../../../worktree-manager.js';
 
 /**
@@ -92,15 +88,5 @@ export async function reapWorktreePhase({
     }
   }
 
-  // Clear the trace-hook env vars so subsequent tooling falls back to the
-  // no-op branch instead of pointing at a (now-reaped) worktree.
-  try {
-    clearActiveStoryEnv({
-      logger: { warn: (m) => progress('ENV', `⚠️ ${m}`) },
-    });
-  } catch {
-    // Non-fatal.
-  }
-
   return worktreeReaped;
 }

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -29,6 +29,7 @@ import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
 import { ensurePullRequestWith } from './phases/pull-request.js';
 import { pushStoryBranch } from './phases/push.js';
 import { handleCriticalReviewBlock } from './phases/review-block.js';
+import { handleOverriddenReviewBlock } from './phases/review-override.js';
 import { reapWorktreePhase } from './phases/worktree-reap.js';
 import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
 
@@ -201,22 +202,31 @@ async function runPrePushPhases({
 
 async function openAndReviewPr({
   cwd,
+  worktreePath,
   story,
   storyId,
   storyBranch,
   baseBranch,
   provider,
+  config,
+  overrideReviewBlock,
   injectedGh,
   injectedRunCodeReview,
   setPhase = () => {},
 }) {
   setPhase('push');
-  pushStoryBranch({ cwd, storyBranch, gitSync, progress });
+  // Issue #4990 — push from the Story worktree so `pre-push` measures the
+  // tree being sent. `gh` and the review's ref-based diffs below keep the
+  // caller's `cwd`: they read the shared `.git`, so they resolve identically
+  // from either tree.
+  pushStoryBranch({ cwd, worktreePath, storyBranch, gitSync, progress });
   setPhase('pull-request');
   const { url: prUrl, alreadyMerged } = await ensurePullRequestWith({
     cwd,
     storyId,
     storyTitle: story.title,
+    // Scanned for a declared `BREAKING CHANGE:` footer — see pull-request.js.
+    storyBody: story.body,
     storyBranch,
     baseBranch,
     gh: injectedGh,
@@ -244,6 +254,27 @@ async function openAndReviewPr({
   });
   if (reviewOutcome.halted) {
     const criticalCount = reviewOutcome.severity?.critical ?? 0;
+    // The sanctioned override. Checked BEFORE the blocked
+    // transition so an overridden run never touches `agent::blocked`: the
+    // Story is proceeding, and parking it would make the label lie for the
+    // rest of the close.
+    if (overrideReviewBlock) {
+      const override = await handleOverriddenReviewBlock({
+        provider,
+        storyId,
+        prUrl,
+        prNumber,
+        criticalCount,
+        reason: overrideReviewBlock,
+        config,
+      });
+      return {
+        prUrl,
+        prNumber,
+        alreadyMerged: false,
+        reviewOverride: override,
+      };
+    }
     await handleCriticalReviewBlock({
       provider,
       storyId,
@@ -252,10 +283,12 @@ async function openAndReviewPr({
     });
     throw new Error(
       `[single-story-close] Story-scope review reported ${criticalCount} critical blocker(s) on PR ${prUrl}. ` +
-        'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/deliver`.',
+        'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/deliver`. ' +
+        'If you have reviewed a finding and judged it wrong, re-run with ' +
+        '`--override-review-block "<reason>"` rather than merging by hand.',
     );
   }
-  return { prUrl, prNumber, alreadyMerged: false };
+  return { prUrl, prNumber, alreadyMerged: false, reviewOverride: null };
 }
 
 async function releaseLease({
@@ -291,11 +324,9 @@ async function releaseLease({
  * `runBaseSyncPhase`, and a critical-blocker review halt in
  * `openAndReviewPr`) throw before the clean-close lease release at the
  * tail of `runSingleStoryClose`, stranding the operator's lease
- * indefinitely. The standalone lease does **not** expire by TTL: it is
- * fail-closed by design (`lease-guard-shared.js` anchors `heartbeatAt` to
- * now, so `isClaimLive` is true for any foreign assignee regardless of the
- * configured TTL), so a stranded claim is cleared only by `--steal` or
- * de-assignment. That fail-closed-refuses a different operator who picks up
+ * indefinitely. The standalone lease has **no** TTL to expire by (Story
+ * #5006 deleted it): `acquireLease` refuses any foreign assignee outright,
+ * so a stranded claim is cleared only by `--steal` or de-assignment. That fail-closed-refuses a different operator who picks up
  * the blocked Story — exactly the hand-off case. Releasing here closes
  * that gap.
  *
@@ -378,6 +409,7 @@ export async function runSingleStoryClose({
   noWaitForMerge: noWaitForMergeParam,
   maxWaitSeconds: maxWaitSecondsParam,
   mergeWatchMode: mergeWatchModeParam,
+  overrideReviewBlock: overrideReviewBlockParam,
   injectedProvider,
   injectedConfig,
   injectedNotify,
@@ -397,10 +429,11 @@ export async function runSingleStoryClose({
     noWaitForMergeParam,
     maxWaitSecondsParam,
     mergeWatchModeParam,
+    overrideReviewBlockParam,
   });
   if (!options.storyId) {
     throw new Error(
-      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>]',
+      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--override-review-block <reason>]',
     );
   }
 
@@ -725,21 +758,25 @@ async function runClosePipeline({
     leaseArgs,
   );
 
-  const { prUrl, prNumber, alreadyMerged } = await releaseLeaseOnBlock(
-    () =>
-      openAndReviewPr({
-        cwd: options.cwd,
-        story,
-        storyId: options.storyId,
-        storyBranch,
-        baseBranch,
-        provider,
-        injectedGh,
-        injectedRunCodeReview,
-        setPhase,
-      }),
-    leaseArgs,
-  );
+  const { prUrl, prNumber, alreadyMerged, reviewOverride } =
+    await releaseLeaseOnBlock(
+      () =>
+        openAndReviewPr({
+          cwd: options.cwd,
+          worktreePath,
+          story,
+          storyId: options.storyId,
+          storyBranch,
+          baseBranch,
+          provider,
+          config,
+          overrideReviewBlock: options.overrideReviewBlock,
+          injectedGh,
+          injectedRunCodeReview,
+          setPhase,
+        }),
+      leaseArgs,
+    );
   // Reap the per-Story worktree BEFORE the arm (Story #4681). Arming runs
   // `gh pr merge --auto --squash --delete-branch`, which — against an
   // already-mergeable PR — merges immediately and then shells out to local
@@ -837,7 +874,10 @@ async function runClosePipeline({
     gates: {
       validation: options.skipValidation ? 'skipped' : 'passed',
       baseSync: options.skipSync ? 'skipped' : 'passed',
-      codeReview: 'passed',
+      // An overridden blocker reports `overridden`, never
+      // `passed`. The review DID fail; a human authorized shipping anyway, and
+      // the envelope is the machine-readable trail that says so.
+      codeReview: reviewOverride ? 'overridden' : 'passed',
     },
   };
 

package/.agents/scripts/lib/orchestration/single-story-lease-guard.js

@@ -24,18 +24,17 @@
  * operator handle from config and delegates assignee mutation to the pure
  * `ticket-lease.js` primitive.
  *
- * **Fail-closed liveness (audit #3513).** The standalone path has no
- * Epic-scoped lifecycle ledger to read a per-owner `story.heartbeat` from, so
- * there is no live-heartbeat source to feed the lease primitive's liveness
- * check. Defaulting `heartbeatAt` to `null` made *every* foreign claim look
- * stale (`isClaimLive(null) === false`), so the guard silently reclaimed any
- * foreign assignee — leaving it inert as a concurrency guard. We therefore
- * **fail closed**: a foreign assignee is treated as a *live* claim by default
- * and refuses the take (naming the current owner), unless the operator passes
- * `--steal` to forcibly transfer it. This is the safer choice for a guard
- * whose whole job is to stop two operators clobbering the same Story; a
- * genuinely abandoned claim is cleared by hand (or `--steal`) rather than
- * raced into automatically. Unclaimed and self-held tickets still proceed.
+ * **Fail-closed (audit #3513, hard-wired by Story #5006).** The lease
+ * primitive used to reclaim a foreign claim whose heartbeat was older than a
+ * TTL — and with no heartbeat source, *every* foreign claim looked stale, so
+ * the guard silently reclaimed any foreign assignee and was inert as a
+ * concurrency guard. The guard worked around that by anchoring the heartbeat
+ * to `now`; Story #5006 deleted the TTL outright, so the fail-closed
+ * behaviour is now the primitive's own: a foreign assignee refuses the take
+ * (naming the current owner) unless the operator passes `--steal` to forcibly
+ * transfer it. A genuinely abandoned claim is cleared by hand (or `--steal`)
+ * rather than raced into automatically. Unclaimed and self-held tickets still
+ * proceed.
  */
 
 import {
@@ -75,21 +74,19 @@ export function resolveOperator(config) {
 }
 
 /**
- * Acquire (or re-affirm / reclaim) the Story lease for the standalone path.
+ * Acquire (or re-affirm) the Story lease for the standalone path.
  *
- * **Fail-closed:** because the standalone path has no Epic ledger to source a
- * live heartbeat from, a foreign assignee is treated as a live claim and
- * refuses the take by default — the guard throws naming the current owner so
- * the operator can coordinate. Pass `steal: true` (`--steal`) to forcibly
- * transfer it. Unclaimed and self-held tickets proceed without a write.
+ * **Fail-closed:** a foreign assignee refuses the take — the guard throws
+ * naming the current owner so the operator can coordinate. Pass
+ * `steal: true` (`--steal`) to forcibly transfer it. Unclaimed and self-held
+ * tickets proceed without a write.
  *
  * @param {object} opts
  * @param {object} opts.provider           Ticketing provider (getTicket/updateTicket).
  * @param {number} opts.storyId            Story ticket to claim.
- * @param {object} opts.config             Resolved config (operator handle + TTL default).
+ * @param {object} opts.config             Resolved config (operator handle).
  * @param {string} [opts.operator]         Override the resolved operator (tests).
  * @param {boolean} [opts.steal=false]     Forcibly transfer a foreign claim.
- * @param {number} [opts.now]              Injectable clock (epoch ms) for tests.
  * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
  * @throws {Error} When a foreign claim refuses the acquire (no `steal`).
  */
@@ -99,27 +96,19 @@ export async function acquireStoryLease({
   config,
   operator,
   steal = false,
-  now,
 }) {
   const owner = operator ?? resolveOperator(config);
-  // Fail closed: with no live-heartbeat source on the standalone path, the
-  // shared kernel anchors `heartbeatAt` to the same `now` the primitive
-  // evaluates against, so `isClaimLive` returns true for any foreign owner
-  // and `acquireLease` refuses unless `steal` is set.
   return acquireLeaseFailClosed({
     provider,
     ticketId: storyId,
     operator: owner,
     steal,
-    config,
-    now,
-    anchorHeartbeatToNow: true,
     renderRefusal: (result) =>
       `single-story lease: Story #${storyId} is currently held by @${result.owner}. ` +
       'Another /deliver run owns this Story. Coordinate with that ' +
       'operator, or re-run with --steal to forcibly transfer the claim once you ' +
-      'have confirmed the other run is dead. (The standalone path has no Epic ' +
-      'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',
+      'have confirmed the other run is dead. (A foreign assignee always ' +
+      'blocks unless stolen.)',
   });
 }
 
@@ -142,5 +131,5 @@ export async function releaseStoryLease({
   operator,
 }) {
   const owner = operator ?? resolveOperator(config);
-  return releaseLease({ provider, ticketId: storyId, operator: owner, config });
+  return releaseLease({ provider, ticketId: storyId, operator: owner });
 }

package/.agents/scripts/lib/orchestration/spec-spill.js

@@ -6,13 +6,27 @@
  * Spec is treated as a sizing smell (the Story should be split or the Spec
  * tightened), not as a reason to write temporary product docs.
  *
- * The budget reuses the §2 FinOps estimator ({@link estimateTokens}, ~4
- * chars/token) so the threshold speaks the same units as hydration budgets.
+ * This module also **owns** the §2 FinOps token estimator
+ * ({@link estimateTokens}, ~4 chars/token) — the one shared approximation every
+ * fixed framework ceiling speaks in (the Spec budget below, the plan-time
+ * sizing ceilings in `ticket-validator-sizing.js`, and the audit checklist
+ * threading budget). It used to live in a `context-envelope.js` SDK whose
+ * remaining surface had no live caller; the estimator is all that survived.
  *
  * @module lib/orchestration/spec-spill
  */
 
-import { estimateTokens } from './context-envelope.js';
+/**
+ * Rough token estimate: ~4 characters per token. Deliberately cheap and
+ * deterministic — every ceiling that quotes "tokens" is quoting this number,
+ * so the approximation matters far less than every caller sharing one.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  return Math.ceil(String(text ?? '').length / 4);
+}
 
 /**
  * Soft budget (estimated tokens) for an inline `## Spec`. ~1500 tokens ≈ 6KB —

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -1,12 +1,13 @@
 /**
  * phases/review-core.js — the shared Story-scope review spine.
  *
- * Extracted from `phases/code-review.js` (Story #4603). `runStoryReviewCore` is
- * the one implementation both close paths call `runCodeReview` through — the
- * epic-attached phase (`code-review.js#runStoryCodeReview`) and the standalone
- * v2 path (`single-story-close/phases/code-review.js#runStoryScopeReview`) —
- * so it belongs to neither and lives here rather than inside one path's phase
- * file (Story #3653 established the shared-spine contract).
+ * Extracted from the Epic-era `phases/code-review.js` (Story #4603) so the
+ * spine belonged to neither close path. `runStoryReviewCore` is the one
+ * implementation `runCodeReview` is called through; since Story #5006 retired
+ * the Epic-attached phase, its sole caller is the v2 standalone path
+ * (`single-story-close/phases/code-review.js#runStoryScopeReview`). It stays
+ * here — the shared-spine contract (Story #3653) is what keeps the maker-blind
+ * review invocation out of a phase file.
  */
 
 import { countChangedLines } from '../../../audit-suite/index.js';

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -425,7 +425,8 @@ export function persistTerminalEnvelope(
  * machine-readable contract — every invocation emits exactly ONE, and a
  * headless caller parses it out of stdout to decide what happened.
  * `Logger.info` is level-gated, so under the documented
- * `AGENT_LOG_LEVEL=silent` (§ 1.H) the envelope silently vanished and the
+ * `AGENT_LOG_LEVEL=silent` (execution-reference § Log-level control) the
+ * envelope silently vanished and the
  * caller got a bare exit code: precisely the "no envelope at all" outcome
  * Story #4543 exists to remove. A contract payload must not be suppressible
  * by a verbosity knob.

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -45,7 +45,10 @@
  * `body.verify` entries must either name a testing tier in parentheses
  * drawn from `VERIFY_TIER_VALUES` (e.g. `npm run test (unit)`) or be the
  * literal `manual:<reason>` escape hatch when the Story is genuinely
- * unverifiable in isolation.
+ * unverifiable in isolation. `verify-tier-repair.js#normalizeVerifyTiers` runs
+ * first on the persist path (Story #5005) and **repairs** the entries whose
+ * tier `suggestVerifyFix` can infer, so the hard error below is reserved for
+ * the entries only the author can resolve.
  *
  * The errors are batched and surfaced as a single thrown Error so the
  * planner can see every offending slug in one pass instead of fixing one