mandrel 2.30.0 → 2.32.0

package/.agents/scripts/lib/signals/write.js

@@ -1,18 +1,18 @@
 /**
- * `lib/signals/write.js` — thin re-export of the signals/traces writer.
+ * `lib/signals/write.js` — thin re-export of the signals writer.
  *
  * The real implementation lives at `../observability/signals-writer.js`
  * (Epic #1030 / Story #1041). This module exists so callers can converge
- * on `lib/signals/` for both reads and writes — the reader barrel landed
- * in Epic #1181 / Story #1438, but the writer surface was still split
- * across `lib/observability/`. New code should `import { appendSignal }
- * from './lib/signals/index.js'` (or `'./lib/signals/write.js'` for a
- * narrower import); legacy direct imports from `lib/observability/` keep
- * working unchanged.
+ * on `lib/signals/` for the write surface. New code should
+ * `import { appendSignal } from './lib/signals/index.js'` (or
+ * `'./lib/signals/write.js'` for a narrower import); legacy direct imports
+ * from `lib/observability/` keep working unchanged.
+ *
+ * `appendTrace` was removed in Story #5003 together with the tool-trace
+ * hook — its only producer — and the viewer that was its only reader.
  */
 
 export {
   appendSignal,
-  appendTrace,
   forEachLine,
 } from '../observability/signals-writer.js';

package/.agents/scripts/lib/story-body/story-body.js

@@ -21,7 +21,6 @@
  *   wide:                { reason } | null,// declared-wide footprint (optional)
  *   reason_to_exist:     string | null,    // one-sentence cohesion reason (optional)
  *   depends_on:          string[],         // blocker story slugs or #ids
- *   estimated_test_files: number | null,   // absent → null (informational)
  * }
  * ```
  *
@@ -79,7 +78,6 @@ import { suggestPathEntryFix } from './body-format-lints.js';
  * @property {{ reason: string }|null} wide      - Declared-wide footprint (reason), or null.
  * @property {string|null}   reason_to_exist     - One-sentence cohesion reason ("why this Story exists"), or null.
  * @property {string[]}      depends_on          - Blocking story slugs / issue refs.
- * @property {number|null}   estimated_test_files - Test surface count or null.
  * @property {string|null}   mandrel_version     - Framework version stamped at authoring, or null.
  * @property {string|null}   authored_at         - Authoring date (YYYY-MM-DD) stamped at authoring, or null.
  */
@@ -334,7 +332,7 @@ const META_BLOCK_RE = /<!--\s*meta:\s*([\s\S]*?)\s*-->/;
 const META_OBJECT_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
 
 /**
- * Extract the `wide` / `estimated_test_files` fields from the trailing
+ * Extract the `wide` / `reason_to_exist` fields from the trailing
  * `<!-- meta: {...} -->` comment block written by {@link serialize}. Returns
  * canonical-shaped values (null when absent or malformed) so the parser
  * round-trips the meta block faithfully.
@@ -350,13 +348,12 @@ const META_OBJECT_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
  * rather than dropping or re-deriving it.
  *
  * @param {string} markdown
- * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, estimated_test_files: number|null, mandrel_version: string|null, authored_at: string|null }}
+ * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, mandrel_version: string|null, authored_at: string|null }}
  */
 function extractMeta(markdown) {
   const result = {
     wide: null,
     reason_to_exist: null,
-    estimated_test_files: null,
     mandrel_version: null,
     authored_at: null,
   };
@@ -377,9 +374,6 @@ function extractMeta(markdown) {
 
   result.wide = normalizeWide(parsed.wide);
   result.reason_to_exist = normalizeReasonToExist(parsed.reason_to_exist);
-  if (typeof parsed.estimated_test_files === 'number') {
-    result.estimated_test_files = parsed.estimated_test_files;
-  }
   if (
     typeof parsed.mandrel_version === 'string' &&
     parsed.mandrel_version.trim()
@@ -579,7 +573,6 @@ function isMachineMarkerLine(line) {
 function parseUnstructuredBody(input, preamble, footer) {
   const warnings = [
     'unstructured-body: no structured sections found; returning minimal body from preamble text.',
-    'test-surface-unestimated: estimated_test_files not present.',
   ];
   const body = {
     goal: preamble || input.trim(),
@@ -593,7 +586,6 @@ function parseUnstructuredBody(input, preamble, footer) {
     wide: null,
     reason_to_exist: null,
     depends_on: extractBlockedBy(footer),
-    estimated_test_files: null,
     mandrel_version: null,
     authored_at: null,
   };
@@ -688,11 +680,6 @@ function parseTextListSection(lines) {
  * `result.warnings` to detect legacy path entries that should be
  * migrated.
  *
- * Informational finding emitted on `result.warnings`:
- * - `test-surface-unestimated` — when `estimated_test_files` is absent
- *   from both a structured body and the markdown. Callers that care about
- *   test-surface coverage SHOULD surface this to the operator.
- *
  * @param {string|object} input - Markdown string or already-structured body object.
  * @returns {ParseResult}
  * @throws {StoryBodyParseError} When the body is structurally unrecoverable.
@@ -765,20 +752,16 @@ export function parse(input) {
   const non_goals = parseTextListSection(sections.get('non_goals') ?? []);
   const dependsOn = extractBlockedBy(footer);
 
-  // --- Recover wide / estimated_test_files from the meta block ---
+  // --- Recover wide / reason_to_exist / provenance from the meta block ---
   // serialize() writes these into a trailing `<!-- meta: {...} -->` comment
   // so round-trips preserve them. Absent meta block → canonical null defaults.
+  // Unknown keys are ignored, so a body carrying a retired meta field parses
+  // clean and simply drops it.
   const meta = extractMeta(input);
-  const estimated_test_files = meta.estimated_test_files;
   const wide = meta.wide;
   const reason_to_exist = meta.reason_to_exist;
   const mandrel_version = meta.mandrel_version;
   const authored_at = meta.authored_at;
-  if (estimated_test_files === null) {
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-  }
 
   const body = {
     goal,
@@ -792,7 +775,6 @@ export function parse(input) {
     wide,
     reason_to_exist,
     depends_on: dependsOn,
-    estimated_test_files,
     mandrel_version,
     authored_at,
   };
@@ -834,13 +816,6 @@ function parseStructuredObject(obj) {
     body[name] = STRUCTURED_FIELD_NORMALIZERS[kind](obj[name], warnings);
   }
 
-  // estimated_test_files is the one warning-coupled scalar: absent (== null)
-  // warns; a non-number, non-null value stays null silently.
-  body.estimated_test_files = normalizeEstimatedTestFiles(
-    obj.estimated_test_files,
-    warnings,
-  );
-
   // Provenance stamp (preserved verbatim; never re-derived here).
   body.mandrel_version = normalizeProvenanceString(obj.mandrel_version);
   body.authored_at = normalizeProvenanceString(obj.authored_at);
@@ -917,25 +892,6 @@ const STRUCTURED_FIELD_NORMALIZERS = {
   reasonToExist: (raw) => normalizeReasonToExist(raw),
 };
 
-/**
- * Normalize `estimated_test_files`: a number passes through; an absent
- * (`null`/`undefined`) value warns `test-surface-unestimated`; any other
- * value stays `null` silently.
- *
- * @param {unknown} raw
- * @param {string[]} warnings
- * @returns {number|null}
- */
-function normalizeEstimatedTestFiles(raw, warnings) {
-  if (typeof raw === 'number') return raw;
-  if (raw == null) {
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-  }
-  return null;
-}
-
 /**
  * Normalize a provenance stamp field (`mandrel_version` / `authored_at`) to
  * a non-empty trimmed string or `null`.
@@ -1066,11 +1022,11 @@ const SERIALIZE_SECTIONS = [
 
 /**
  * Build the trailing `<!-- meta: {...} -->` block carrying the fields that
- * have no human-readable section (`wide`, `reason_to_exist`,
- * `estimated_test_files`). Returns the empty string when no meta field is
- * present so {@link serialize} appends nothing.
+ * have no human-readable section (`wide`, `reason_to_exist`). Returns the
+ * empty string when no meta field is present so {@link serialize} appends
+ * nothing.
  *
- * Key insertion order (`wide` → `reason_to_exist` → `estimated_test_files` →
+ * Key insertion order (`wide` → `reason_to_exist` →
  * `mandrel_version` → `authored_at`) is load-bearing: it fixes the serialized
  * JSON byte sequence the parser's meta round-trip and the unit suite assert
  * against. The provenance stamp keys are appended **last** so every
@@ -1089,9 +1045,6 @@ function serializeMetaBlock(body) {
   if (reasonToExist !== null) {
     metaFields.reason_to_exist = reasonToExist;
   }
-  if (typeof body.estimated_test_files === 'number') {
-    metaFields.estimated_test_files = body.estimated_test_files;
-  }
   if (typeof body.mandrel_version === 'string' && body.mandrel_version.trim()) {
     metaFields.mandrel_version = body.mandrel_version.trim();
   }
@@ -1153,9 +1106,9 @@ function serializeFooter(body, opts) {
  * `## Goal`, `## Slicing`, `## Spec`, `## Changes`, `## Acceptance`,
  * `## Verify`, `## References`, `## Non-Goals` (each omitted when empty).
  *
- * `wide`, `reason_to_exist`, and `estimated_test_files` are emitted as a
- * fenced `<!-- meta -->` comment block so round-trips preserve them without
- * polluting the human-readable body.
+ * `wide` and `reason_to_exist` are emitted as a fenced `<!-- meta -->`
+ * comment block so round-trips preserve them without polluting the
+ * human-readable body.
  *
  * @param {StoryBody} body
  * @param {SerializeOptions} [opts]

package/.agents/scripts/lib/temp-retention.js

@@ -31,7 +31,7 @@
  * ## Keep-class
  *
  * `signals.ndjson` is the artifact whose value *starts* when the run ends —
- * `signals-view`, `acceptance-eval`, and the loop-health check all read it
+ * `acceptance-eval` and the loop-health check both read it
  * long after the Story merged. It is excluded twice over: it is not in the
  * evidence basename allowlist, and {@link KEEP_BASENAMES} is re-checked at
  * the deletion site. Defence in depth is warranted for the one file whose

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -109,7 +109,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\` / \`estimated_test_files\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -151,7 +151,6 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
 - **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
-- **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 - **Observed-behavior claims open with \`Current state (verified <date>)\`.** Any Spec claim about how the codebase behaves today MUST open with that preamble (e.g. \`Current state (verified 2026-07-17): …\`) so a reader can tell a verified observation from an assumption, and can tell when the observation went stale.
 - **Intent-then-proxy acceptance shape.** When an acceptance item verifies through a proxy check (a grep, a file-exists probe, an exit-code test), state the intent clause before the proxy check — what outcome the check stands in for — so the proxy never becomes the goal (e.g. "the workflow names hygiene findings as re-author input: \`grep -n "textHygiene" …\` exits 0").
 - **Slicing checkpoints are one line each.** Each \`## Slicing\` checkpoint is a single line naming the checkpoint; implementation detail lives in \`## Spec\`, never duplicated into Slicing. A Slicing section outweighing its Spec is a defect the text-hygiene lint flags.
@@ -171,7 +170,7 @@ The Story is executed by a frontier-model deliverer that reads the codebase itse
 
 #### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
 
-Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. The two auto-fixable rules (\`changes-path-entry-shape\`, \`verify-tier-suffix\`) also emit the corrected form in the dry-run failure output, but authoring them right up front avoids the round-trip entirely.
+Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. \`verify-tier-suffix\` is the one rule persist repairs for you: when the tier is unambiguously inferable from the command, persist appends it and proceeds; when it is not, the entry is still rejected and you must choose the tier. \`changes-path-entry-shape\` emits the corrected form in the dry-run failure output but is never applied for you.
 
 ${bodyFormatLintChecklist}
 
@@ -231,35 +230,38 @@ Declaring \`wide\` with a non-empty reason **lifts the hard session-mass rejecti
 
 #### UI / TESTID INVARIANCE (per CLAUDE.md safety rule):
 
-- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST end \`changes\` with one of:
-  - \`data-testid invariance: <list of testids that MUST be preserved>\`, or
-  - \`data-testid changes: <old> -> <new>\` paired with a corresponding \`tests/e2e/*.spec.ts\` edit in the same story or a depends_on Story.
+Every \`changes[]\` entry is a \`{ path, assumption }\` object — a prose bullet there is rejected by the parser, so the testid contract is carried where prose belongs:
+
+- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST carry the testid contract as a top-level \`acceptance[]\` item, one of:
+  - \`"data-testid invariance: <list of testids that MUST be preserved>"\`, or
+  - \`"data-testid changes: <old> -> <new>, with the matching tests/e2e/*.spec.ts selector updated"\` — paired with that \`tests/e2e/*.spec.ts\` file in \`changes[]\`, in the same Story or a depends_on Story.
+- State the preserved-testid set in \`## Non-Goals\` prose as well when the Story deliberately renames nothing.
 - Renaming a testid without the matching e2e edit is FORBIDDEN.
 
 #### BRAND / COPY / STYLE WORK:
 
-- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the Epic body"]\`. Silence on style sourcing is a smell.
+- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the plan seed"]\`. Silence on style sourcing is a smell.
 
-### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has \`new\`-disposition rows):
-The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file. (These Gherkin \`.feature\` files are BDD artifacts, unrelated to any ticket tier.)
+### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when your plan verifies against a scenario that does not exist yet):
+The plan-context envelope's \`bddScenarios\` field is the index of Gherkin scenarios that **already exist on \`main\`** — one row per scenario, carrying its \`.feature\` file path, line, scenario title and tags. It is the live signal for this rule: a \`.feature\` path + scenario your plan needs but that appears in no \`bddScenarios\` row does not exist yet. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file.
 
-When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create the \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
+When **one or more** \`.feature\` scenarios your plan verifies against are absent from \`bddScenarios\`, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
 
 - **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against").
 - **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
-- **changes**: one entry per distinct \`.feature\` file named in a \`new\` row, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
+- **changes**: one entry per distinct absent \`.feature\` file, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
 - **acceptance**: MUST assert (a) every new \`.feature\` file exists AND (b) every new scenario within them carries an \`@skip\` tag. Keep these observable (a grep/validate command exits 0, a file exists at a path).
 - **verify**: a grep/validate command (tier \`validate\`), NOT an e2e runner — verifying that a file exists with the required tags needs no browser/playwright run. Example: \`grep -rL '@skip' tests/features/<area>/*.feature (validate)\` paired with an existence check.
 - Each implementation Story whose \`verify[]\` references one of these scaffolded \`.feature\` paths MUST \`depends_on\` the scaffold Story (so the scaffold lands in an earlier wave). Omitting the link trips the soft \`missing-bdd-scaffold\` validator finding.
 
-When the Acceptance Spec contains **zero \`new\`-disposition rows** (every row is \`updated\` or \`unchanged\`), do NOT emit a scaffold Story — there is nothing to create.
+When every scenario your plan verifies against is already present in \`bddScenarios\`, do NOT emit a scaffold Story — there is nothing to create.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work):
-When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
+When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same plan whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
 "Scope verification note: this story's deliverable may already be satisfied by Story #<slug-or-id>'s AC — before implementing, \`git diff main -- <path>\` against the upstream Story branch and confirm whether a substantive edit is still required, or whether only a cross-reference remains."
 This prevents the executing agent from redoing work the upstream Story already merged.
 
-CRITICAL: Dependencies should follow execution blockers. Stories attach directly to the Epic — never emit a 'parent_slug' field.
+CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
 IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
 
 ### REVIEWABILITY BUDGET (Story #2798):

package/.agents/scripts/lib/ticket-body-sections.js

@@ -53,11 +53,10 @@ export const TICKET_BODY_SECTIONS = Object.freeze({
 export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
 
 /**
- * Regex matching the Tech Spec's required opening heading (same variants
- * `spec-section-validator.js` accepts). Exported so it is the single
- * source of truth for this pattern — `spec-section-validator.js`,
- * `consolidation-precondition.js` all import
- * it rather than each carrying their own copy.
+ * Regex matching the Tech Spec's `## Delivery Slicing` heading, tolerating
+ * the `Delivery ` qualifier and casing variants. Exported so it is the single
+ * source of truth for this pattern — `consolidation-precondition.js` imports
+ * it rather than carrying its own copy.
  */
 export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
 

package/.agents/scripts/lib/worktree/lifecycle/merge-reachability.js

@@ -3,23 +3,25 @@
  *
  * The "is the worktree's work integrated upstream?" half of
  * `isSafeToRemove`. Runs the two-phase reachability gate the parent
- * documents: primary `merge-base --is-ancestor HEAD epicRef`, and a
- * fallback `git log --grep=resolves #<storyId>` against the Epic ref when
- * the ancestry check returns "not an ancestor".
+ * documents: primary `merge-base --is-ancestor HEAD baseRef`, and a
+ * `git cherry` patch-equivalence fallback when the ancestry check returns
+ * "not an ancestor".
  *
  * The fallback exists because a post-merge rebase or force-push can drop
- * the local branch ref off the merged tip — the `(resolves #N)` token on
- * the Epic's `--no-ff` merge commit (emitted by
- * `story-close/merge-runner.js`) is the durable proof the Story was
- * integrated.
+ * the local branch ref off the merged tip, so SHA reachability alone
+ * under-reports integration.
+ *
+ * A third phase used to sit between the two: a `git log --merges
+ * --grep=resolves #<storyId>` probe for the `(resolves #N)` token on the
+ * Epic's `--no-ff` merge commit. Story #5006 removed it — v2 lands every
+ * Story as a **squash** merge onto `main`, which never writes that token,
+ * and the `--no-ff` emitter (`story-close/merge-runner.js`) went with the
+ * Epic pipeline. The probe could only ever return `false`.
  *
  * Pure with respect to the supplied `ctx` bag; the only side effects are
  * the `gitSpawn` calls.
  */
 
-import { parseStoryBranch } from '../../git-utils.js';
-import { resolvesGrepArgs } from '../../orchestration/resolves-token.js';
-
 /**
  * Resolve a worktree's `HEAD` to a full commit SHA via
  * `git rev-parse HEAD` (run inside the worktree). Returns
@@ -70,37 +72,6 @@ export function checkHeadAncestor(ctx, headSha, epicRef) {
   };
 }
 
-/**
- * Predicate: did the Epic ref accumulate a `--no-ff` merge commit whose
- * subject names this Story (e.g. `... (resolves #1851)`)? Returns `true`
- * when the grep finds at least one matching merge commit, `false` when it
- * returns empty or fails.
- *
- * Returns `false` for branches that do not match the canonical
- * `story-<id>` shape — the merge-commit subject contract is only
- * guaranteed for story branches.
- *
- * @param {object} ctx
- * @param {string} branch Worktree branch (e.g. `story-1851`).
- * @param {string} epicRef Epic branch ref (e.g. `epic/1831`).
- * @returns {boolean}
- */
-export function hasMergeCommitForStory(ctx, branch, epicRef) {
-  const storyId = parseStoryBranch(branch);
-  if (storyId === null) return false;
-  const grep = ctx.git.gitSpawn(
-    ctx.repoRoot,
-    'log',
-    epicRef,
-    '--merges',
-    '-n',
-    '1',
-    '--pretty=%H',
-    ...resolvesGrepArgs(storyId),
-  );
-  return grep.status === 0 && grep.stdout.trim().length > 0;
-}
-
 /**
  * Predicate: are every commit on `branch` patch-equivalent to a commit
  * already on `epicRef`? Runs `git cherry <epicRef> <branch>` and returns
@@ -140,7 +111,7 @@ export function hasRebasedEquivalents(ctx, branch, epicRef) {
 }
 
 /**
- * Run the full three-phase merge-reachability gate. Returns the same
+ * Run the full two-phase merge-reachability gate. Returns the same
  * `{ safe, reason }` envelope `isSafeToRemove` does, so callers can chain
  * the verdict directly into the parent return value.
  *
@@ -165,9 +136,6 @@ export async function checkMergeReachability(ctx, wtPath, branch, epicRef) {
     };
   }
 
-  if (hasMergeCommitForStory(ctx, branch, epicRef)) {
-    return { safe: true, reason: 'merge-commit-reachable' };
-  }
   if (hasRebasedEquivalents(ctx, branch, epicRef)) {
     return { safe: true, reason: 'rebased-equivalents' };
   }

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

@@ -47,11 +47,10 @@ const WINDOWS_CWD_RE =
  * (branch advanced to a SHA still reachable from the Epic merge commit).
  *
  * When HEAD is no longer an ancestor (force-push that drops or rewrites
- * the merged tip), the function falls back to a `merge-commit-reachable`
- * check: search the Epic ref for a `--no-ff` merge commit whose subject
- * carries this Story's `(resolves #<id>)` token. Such a merge commit
- * proves the Story branch was integrated even though the current HEAD
- * has diverged, so the worktree is still safe to reap.
+ * the merged tip), the function falls back to a `rebased-equivalents`
+ * check: `git cherry` proves every commit on the branch is already
+ * upstream by patch-id even though the current HEAD has diverged, so the
+ * worktree is still safe to reap.
  *
  * `opts.epicBranch` is the integration / base ref the Story must already
  * be merged into (e.g. `main` or a plan-run branch).

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

@@ -54,9 +54,8 @@ export class WorktreeManager {
    * @param {(phase: 'worktree-create'|'bootstrap'|'install') => void} [opts.onPhase]
    *   Optional phase-boundary callback fired from `ensure()` just before each
    *   internal phase (git worktree add, bootstrap-file copy, dependency
-   *   install). Consumed by `story-init` to drive `phase-timer.mark()`
-   *   so `[phase-timing]` log lines attribute wall-clock correctly to the
-   *   sub-phases of worktree provisioning.
+   *   install), so a caller can attribute wall-clock to the sub-phases of
+   *   worktree provisioning.
    */
   constructor({
     repoRoot,

package/.agents/scripts/lint-label-vocabulary.js

@@ -38,8 +38,8 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-
 import { runAsCli } from './lib/cli-utils.js';
+import { walkFilesByExtension } from './lib/fs-walk.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -71,28 +71,6 @@ export const KNOWN_AXES = Object.freeze([
   'planning',
 ]);
 
-/**
- * Walk a directory tree synchronously, yielding absolute paths of files
- * matching `.md`. Mirrors the walker shape in `check-lifecycle-lint.js`.
- */
-function* walkMd(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return;
-    throw err;
-  }
-  for (const entry of entries) {
-    const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      yield* walkMd(p);
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      yield p;
-    }
-  }
-}
-
 /**
  * Resolve a mixed list of file/directory paths into the flat set of
  * markdown files to scan. Missing paths are silently skipped (the
@@ -116,7 +94,7 @@ function* resolveTargets(targets) {
     for (const entry of stat) {
       const p = path.join(target, entry.name);
       if (entry.isDirectory()) {
-        yield* walkMd(p);
+        yield* walkFilesByExtension(p, '.md');
       } else if (entry.isFile() && entry.name.endsWith('.md')) {
         yield p;
       }

package/.agents/scripts/pr-watch-with-update.js

@@ -6,10 +6,12 @@
  *
  * Polls the PR's required checks to a terminal state and auto-recovers
  * from `mergeStateStatus: BEHIND` (via bounded `gh pr update-branch`
- * calls) by delegating to the shared `watchPrToTerminal` primitive in
- * the lifecycle `Watcher` — the SAME loop the listener runs, so the CLI
- * and the bus path are byte-for-byte equivalent. No lifecycle bus is
- * created; this is a direct, synchronous watch with a real exit code.
+ * calls) by delegating to the `watchPrToTerminal` primitive in
+ * `lib/orchestration/pr-watch.js`. That primitive was shared with the
+ * `Watcher` bus listener until Story #5006 deleted it (nothing emitted at
+ * it); this CLI is now its only caller. Story #5024 retired the bus
+ * outright, so there is no bus to create — this is a direct, synchronous
+ * watch with a real exit code.
  *
  * Slow-vs-failed semantics (Story #4358):
  *   - GREEN — every required check terminal + green → exit 0, unless the
@@ -100,7 +102,7 @@ import {
   retireCiDigest,
   writeCiDigest,
 } from './lib/orchestration/ci-rerun-guard.js';
-import { watchPrToTerminal } from './lib/orchestration/lifecycle/listeners/watcher.js';
+import { watchPrToTerminal } from './lib/orchestration/pr-watch.js';
 import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import { sleep as defaultSleep } from './lib/util/poll-loop.js';
 

package/.agents/scripts/providers/github/cache.js

@@ -5,8 +5,8 @@
  * single `GitHubProvider`, shared by dispatcher, reconciler, and cascade.
  * The outer TTL wrapper is deliberately omitted because `peekFresh` already
  * bounds entries by a caller-supplied `maxAgeMs`, and every other reader
- * trusts the ticket mutators (`updateTicket` / `postComment` /
- * `addSubIssue` / `removeSubIssue`) to call `invalidate` explicitly.
+ * trusts the ticket mutators (`updateTicket` / `postComment`) to call
+ * `invalidate` explicitly.
  *
  * Surface is intentionally narrow: only the methods the provider itself
  * reaches for live here (`has` / `peek` / `peekFresh` / `set` /

package/.agents/scripts/providers/github/comments.js

@@ -7,20 +7,16 @@
  * the upstream `upsertStructuredComment` ticketing helper before the body
  * lands here.
  *
- * Extracted from `../github.js` in Story #2462 / Task #2480. Public
- * surface on `GitHubProvider` is unchanged — `postComment`,
- * `getRecentComments`, `getTicketComments`, and `deleteComment` all
- * delegate here.
+ * Extracted from `../github.js` in Story #2462 / Task #2480. `postComment`,
+ * `getTicketComments`, and `deleteComment` on `GitHubProvider` all delegate
+ * here. Story #5008 dropped the repo-wide `getRecentComments` feed — the
+ * telemetry dashboard that read it was retired and nothing else polls a
+ * cross-issue comment stream.
  *
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
-import { withTransientRetry } from './errors.js';
-import {
-  defaultRetryWarn,
-  paginateRest,
-  parseApiJson,
-} from './request-helpers.js';
+import { paginateRest, parseApiJson } from './request-helpers.js';
 
 // Structured-comment badge — preserved verbatim from the legacy
 // `./github/comments.js`. The upstream `upsertStructuredComment` ticketing
@@ -51,24 +47,6 @@ export class CommentGateway {
     this._hooks = hooks;
   }
 
-  /**
-   * Recent comments across all issues in the repo (sorted newest first).
-   *
-   * @field-manifest /repos/{owner}/{repo}/issues/comments?sort=created:
-   *                 id, body, created_at, user, issue_url
-   */
-  async getRecentComments(limit = 100) {
-    const result = await withTransientRetry(
-      () =>
-        this._gh.api({
-          method: 'GET',
-          endpoint: `/repos/${this.owner}/${this.repo}/issues/comments?sort=created&direction=desc&per_page=${limit}`,
-        }),
-      { label: 'getRecentComments', onRetry: defaultRetryWarn },
-    );
-    return parseApiJson(result) ?? [];
-  }
-
   /**
    * All comments on a single ticket. Used by the upstream
    * `findStructuredComment` ticketing helper, which greps each comment

package/.agents/scripts/providers/github/compose.js

@@ -23,7 +23,6 @@ import { LabelGateway } from './labels.js';
 import { MergeMethodsGateway } from './merge-methods.js';
 import { ProjectBoardGateway } from './project-board.js';
 import * as projects from './projects-v2-graphql.js';
-import { PullRequestGateway } from './prs.js';
 import { SubIssueGateway } from './sub-issues.js';
 import { TicketGateway } from './tickets.js';
 
@@ -50,12 +49,6 @@ export function composeGateways(provider) {
     ghGraphql: (q, v, o) => p.graphql(q, v, o),
     cache: p._cache,
     classifyGithubError,
-    hooks: {
-      getTicket: (id, o) => p.getTicket(id, o),
-      getTickets: (id) => p.getTickets(id),
-      primeTicketCache: (t) => p.primeTicketCache(t),
-      invalidateTicket: (id) => p.invalidateTicket(id),
-    },
   });
   p.comments = new CommentGateway({
     ...ghDeps,
@@ -64,14 +57,6 @@ export function composeGateways(provider) {
   p.labels = new LabelGateway(ghDeps);
   p.branchProtection = new BranchProtectionGateway(ghDeps);
   p.mergeMethods = new MergeMethodsGateway(ghDeps);
-  p.pullRequests = new PullRequestGateway({
-    gh: p._gh,
-    hooks: {
-      getTicket: (id) => p.getTicket(id),
-      addItemToProject,
-      getProjectNumber,
-    },
-  });
   p.issues = new IssuesGateway({
     ...ghDeps,
     hooks: {