mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/plan-reachability.js

@@ -1,27 +1,12 @@
 /**
- * plan-reachability.js — deterministic draft-ticket reachability check for
- * the persist surface (Epic #4474 PR6, design §4: the 8.4 reachability
- * critic demoted from a fresh-context sub-agent to a persist-side scan).
+ * plan-reachability.js — deterministic persist-side scan of draft tickets'
+ * route paths against the nav registry, run before any provider call so an
+ * orphaned surface is fixed by a free one-line amend.
  *
- * Route-glob scan of the paths a Story declares vs the
- * `planning.navigation.navRegistry` token list, run over the **draft**
- * ticket set inside `plan-persist.js` step 4.5, before any provider call,
- * so an orphaned surface is caught while a one-line targeted amend is
- * still free (nothing has been written to GitHub yet).
- *
- * Plan-level coverage semantics (the convergence contract): a route-adding
- * story that never references the nav registry produces orphan surfaces —
- * UNLESS every one of its route paths is also mentioned by some story in
- * the plan that DOES reference the registry (the "navigation owner"). That
- * is exactly what the documented recovery produces: the author appends the
- * single reachability Story (which cites the orphaned routes and the nav
- * registry) in one targeted amend, and the re-run persist passes.
- *
- * Silent no-op when `planning.navigation` is unconfigured (`routeGlobs`
- * empty) — reported as `status: 'skipped'` so the caller can append the
- * audit record to the plan-metrics ledger.
- *
- * Pure over its inputs (tickets + resolved config), no I/O.
+ * A route-adding Story that never cites the registry is an orphan unless
+ * every one of its route paths is mentioned by some registry-citing Story in
+ * the plan (the navigation owner). `skipped` when `routeGlobs` is empty.
+ * Pure, no I/O.
  */
 
 import {
@@ -30,37 +15,28 @@ import {
   resolveNavConfig,
 } from './plan-navigation.js';
 
-/**
- * Fallback tokens when `navRegistry` is unconfigured but `routeGlobs` is.
- */
+/** Used when `navRegistry` is unconfigured but `routeGlobs` is. */
 const FALLBACK_REGISTRY_TOKENS = ['nav registry', 'navigation'];
 
 /**
  * @typedef {Object} ReachabilityOrphan
  * @property {string} story The offending draft story's slug (or title).
- * @property {string[]} paths The route-matching paths with no navigation
- *   owner anywhere in the plan.
+ * @property {string[]} paths Route paths with no navigation owner.
  */
 
 /**
  * @typedef {Object} DraftReachabilityResult
  * @property {'skipped'|'ok'|'orphans'} status
  * @property {string[]} reasons
- * @property {ReachabilityOrphan[]} orphans Empty unless `status` is
- *   `'orphans'`.
+ * @property {ReachabilityOrphan[]} orphans
  * @property {number} scanned Draft stories scanned (0 when skipped).
  */
 
 /**
- * Evaluate draft-ticket reachability against the configured navigation
- * surface.
- *
  * @param {object} input
  * @param {Array<{ slug?: string, title?: string, body?: string }>} input.tickets
- *   The draft ticket set the persist is about to create (fan-out: the
- *   authored `tickets.json`; amend: the merged set).
- * @param {object} [input.config] Resolved `.agentrc.json` (threads
- *   `planning.navigation`).
+ *   The draft ticket set about to be created.
+ * @param {object} [input.config] Resolved `.agentrc.json`.
  * @returns {DraftReachabilityResult}
  */
 export function evaluateDraftReachability({ tickets, config }) {
@@ -82,7 +58,6 @@ export function evaluateDraftReachability({ tickets, config }) {
       ? navRegistry.map((t) => t.toLowerCase())
       : FALLBACK_REGISTRY_TOKENS;
 
-  // Pass 1: per-story scan — declared paths, route matches, registry refs.
   const scannedStories = stories.map((story) => {
     const body = typeof story?.body === 'string' ? story.body : '';
     const paths = extractStoryPaths(body);
@@ -92,8 +67,7 @@ export function evaluateDraftReachability({ tickets, config }) {
     return { story, paths, routePaths, referencesRegistry };
   });
 
-  // Pass 2: navigation owners — every path mentioned by a
-  // registry-referencing story is covered plan-wide.
+  // Every path a registry-citing Story mentions is covered plan-wide.
   const coveredPaths = new Set();
   for (const s of scannedStories) {
     if (!s.referencesRegistry) continue;
@@ -135,9 +109,6 @@ export function evaluateDraftReachability({ tickets, config }) {
 }
 
 /**
- * Render the named soft-failure message the persist CLI prints — the
- * orphan-surface list plus the one-targeted-amend recovery contract.
- *
  * @param {DraftReachabilityResult} result A `status: 'orphans'` result.
  * @returns {string}
  */

package/.agents/scripts/lib/orchestration/plan-run-labels/reap.js

@@ -1,47 +1,18 @@
 /**
- * plan-run-labels/reap.js — the cohort label's end of life (Story #5189).
- *
- * `plan-persist` mints one `plan-run::<id>` label per run so the Stories one
- * plan authored stay filterable in the GitHub UI. That is load-bearing while
- * any Story in the cohort is open, and inert the moment they are all closed —
- * but nothing expressed the second half, so the vocabulary grew one label per
- * persist forever. A consumer repository measured 235 `plan-run::` labels out
- * of 313 total; past that a paged label listing stops seeing the labels that
- * sort after the pile, and every list-then-create caller starts failing.
- *
- * This module is the **one decision engine** behind both surfaces that act on
- * that end of life: the per-Story close tail (automatic, incremental) and
- * `prune-plan-run-labels.js` (manual, whole-repository). Keeping the decision
- * here rather than in either caller is what stops the two from disagreeing
- * about when a label is spent.
- *
- * **The decision.** A cohort label is reapable only when it carries at least
- * one issue and every issue carrying it is closed. The "at least one" clause
- * is the subtle half: a label carrying *zero* issues is indistinguishable from
- * one an in-flight persist has just minted before creating its Stories, and
- * deleting it would break that run. So a zero-issue label is reported under an
- * `unreferenced` reason and reaped only under an explicit opt-in — a default
- * sweep is safe to run concurrently with a persist.
- *
- * **Never load-bearing.** Both surfaces treat a reap failure as a warning.
- * Label hygiene is a chore; nothing downstream reads the cohort label as an
- * input (see `PLAN_RUN_LABEL_PREFIX`'s own docblock), so a failed delete costs
- * a stale label and nothing else.
+ * plan-run-labels/reap.js — the one decision engine for reaping spent
+ * `plan-run::<id>` cohort labels, shared by the close tail and the manual
+ * sweep so the two cannot disagree. A reap failure is only ever a warning.
  *
  * @module lib/orchestration/plan-run-labels/reap
- * @see Story #5189
  */
 
 import { PLAN_RUN_LABEL_PREFIX } from '../plan-persist/story-ops.js';
 
 /**
- * Why a cohort label was — or was not — judged reapable. One reason per
- * label, so a `--json` report is auditable without re-deriving anything.
- *
  * - `all-closed`   — carries issues, every one closed. Reapable.
- * - `open-stories` — at least one issue still open. Not reapable, ever.
- * - `unreferenced` — carries no issues at all. Reapable only under the
- *   explicit opt-in, because an in-flight persist looks exactly like this.
+ * - `open-stories` — at least one issue still open. Never reapable.
+ * - `unreferenced` — carries no issues. Reapable only under explicit opt-in,
+ *   because an in-flight persist's freshly minted label looks exactly like this.
  */
 export const REAP_REASONS = Object.freeze({
   ALL_CLOSED: 'all-closed',
@@ -50,12 +21,6 @@ export const REAP_REASONS = Object.freeze({
 });
 
 /**
- * Is `name` a plan-run cohort label?
- *
- * The prefix is imported from `plan-persist/story-ops.js` rather than
- * re-declared: minting and reaping must not be able to drift onto two
- * different strings, which is exactly the failure a copied literal invites.
- *
  * @param {unknown} name
  * @returns {boolean}
  */
@@ -64,10 +29,7 @@ function isPlanRunLabel(name) {
 }
 
 /**
- * Project an arbitrary label collection onto the sorted, de-duplicated set of
- * cohort label names. Accepts either bare strings (a ticket's `labels[]`) or
- * `{ name }` rows (the label listing port), so both callers hand this whatever
- * their own read returned.
+ * Sorted, de-duplicated cohort label names from strings or `{ name }` rows.
  *
  * @param {Array<string|{ name?: string }>} [names]
  * @returns {string[]}
@@ -82,13 +44,8 @@ function selectCohortLabels(names) {
 }
 
 /**
- * Decide one cohort label.
- *
- * Reads through `listIssuesByLabel({ state: 'all' })` — the paginating read
- * port — so the verdict is never a function of how many issues fit on one API
- * page. `state` is compared case-insensitively against `closed` and anything
- * else counts as open: an unknown state must never be read as "safe to
- * delete".
+ * Decide one label via the paginating read port. Any state other than
+ * `closed` counts as open: an unknown state is never "safe to delete".
  *
  * @param {{ provider: object, label: string, includeUnreferenced?: boolean }} args
  * @returns {Promise<{
@@ -142,12 +99,7 @@ async function decideCohortLabel({
 }
 
 /**
- * Decide a set of cohort labels.
- *
- * Sequential on purpose. The whole-repository sweep can face hundreds of
- * labels, and a fan-out over a shared REST budget buys wall-clock at the cost
- * of the one property an operator auditing a pile actually needs: a
- * deterministic, label-ordered report.
+ * Sequential on purpose, for a deterministic label-ordered report.
  *
  * @param {{
  *   provider: object,
@@ -171,13 +123,8 @@ async function evaluateCohortLabels({
 }
 
 /**
- * Decide, then (unless `check`) delete.
- *
- * A delete that throws is recorded in `failed[]` and warned about rather than
- * propagated: one unreachable label must not abandon the rest of a sweep, and
- * on the close path it must not touch the land. A delete the provider reports
- * as a no-op (`deleted: false` — the label was already gone) is still a
- * success; that is what makes a re-run idempotent.
+ * Decide, then (unless `check`) delete. A throwing delete is recorded in
+ * `failed[]`, never propagated; an already-gone label counts as success.
  *
  * @param {{
  *   provider: object,
@@ -225,18 +172,8 @@ async function reapCohortLabels({
 }
 
 /**
- * The automatic surface's entry point: reap the cohort labels carried by the
- * Story that just closed.
- *
- * The Story's own label set comes from `getTicket` (labels are immutable for
- * this purpose, so a cached snapshot is fine); every *state* judgment comes
- * from the fresh `listIssuesByLabel` read inside {@link decideCohortLabel}, so
- * a primed ticket cache cannot make a still-open sibling look closed.
- *
- * A Story whose own issue has not yet registered as closed — the merge webhook
- * that fires `Closes #<id>` is not instantaneous — simply reports
- * `open-stories` and is left alone. Deferring is the safe direction, and the
- * manual sweep is the backstop that collects whatever a race leaves behind.
+ * Every state judgment is a fresh read; a Story not yet registered closed is
+ * deferred to the manual sweep.
  *
  * @param {{
  *   storyId: number,
@@ -275,11 +212,7 @@ export async function reapPlanRunLabelsForStory({
 }
 
 /**
- * The manual surface's entry point: sweep every cohort label in the repository.
- *
- * Reads the whole label vocabulary through the paginating listing port and
- * projects it onto the cohort axis here, so the sweep is bounded by what the
- * repository actually holds rather than by an API page size.
+ * Sweep every cohort label in the repository.
  *
  * @param {{
  *   provider: object,
@@ -309,15 +242,7 @@ export async function sweepCohortLabels({
   return { totalLabels: rows.length, evaluated: labels.length, ...outcome };
 }
 
-/**
- * Test-only surface. The five helpers below compose the two exported entry
- * points (`reapPlanRunLabelsForStory`, `sweepCohortLabels`) and have no
- * production consumer outside this module, so exporting each one individually
- * would advertise five API surfaces nothing imports — and `dead-exports
- * --production` correctly reports each as dead. They are still worth unit
- * testing per arm, which is what this barrel is for; it follows the same
- * `__testing` idiom `git-probes.js` and `source-classifier.js` use.
- */
+/** Test-only barrel, so `dead-exports --production` sees no unused exports. */
 export const __testing = {
   isPlanRunLabel,
   selectCohortLabels,

package/.agents/scripts/lib/orchestration/plan-runner/worktree-sweep.js

@@ -1,33 +1,11 @@
 /**
- * plan-runner/worktree-sweep.js
+ * plan-runner/worktree-sweep.js — plan-boot sweep that force-removes
+ * `.worktrees/story-<id>/` entries whose Story is closed or `agent::done`,
+ * after draining the pending-cleanup manifest.
  *
- * Reap-sweep run at plan boot (via `drainPendingCleanupAtBoot` in
- * `lib/orchestration/epic-plan-spec/phases/drain.js`, wired into
- * `plan-persist.js`). Iterates the `.worktrees/story-<id>/`
- * entries registered with git, looks up each parent Story, and force-removes
- * any whose Story is already closed or labeled `agent::done`.
- *
- * The `--force` flag is intentional. By the time a Story is `agent::done`
- * its branch has already been merged into the Epic branch (via
- * `single-story-close.js`), so any residue left in the worktree — dirty
- * build artifacts, an interrupted rebase, a stray Windows lock — is noise.
- * The safety rails in `WorktreeManager.reap` exist for the _active_ close
- * path; at plan time we already know the Story is done and want the
- * directory gone no matter what.
- *
- * Public API:
- *   - `sweepStaleStoryWorktrees({ provider, repoRoot, git?, logger?, fsRm?, worktreeRoot? })`
- *
- * Also drains any `.worktrees/.pending-cleanup.json` manifest left behind
- * by Stage 1 (`removeWorktreeWithRecovery` → fs-rm-retry exhaustion, see
- * `../worktree/lifecycle/pending-cleanup.js`). Entries whose Stage 1 retry now
- * succeeds are removed from the manifest; entries reaching
- * MAX_SWEEP_ATTEMPTS emit an `OPERATOR ACTION REQUIRED: persistent-lock`.
- *
- * Returns `{
- *   reaped, skipped,
- *   drainedPending, persistentPending, stillPending
- * }`.
+ * `--force` is deliberate: a done Story's branch is already merged, so any
+ * residue (dirty artifacts, an interrupted rebase, a Windows lock) is noise;
+ * the `WorktreeManager.reap` safety rails are for the active close path.
  */
 
 import path from 'node:path';
@@ -56,20 +34,13 @@ function storyIdFromPath(wtPath) {
 }
 
 /**
- * Scan registered worktrees and force-remove any whose parent Story is
- * done (closed or `agent::done`). Never touches worktrees whose Story is
- * still open — those are live or in-flight.
- *
- * Provider reads are fanned out at concurrency 8 via `concurrentMap`; the
- * subsequent `git worktree remove` calls stay sequential because they
- * mutate `.git/worktrees/`.
+ * Never touches a worktree whose Story is still open.
  *
  * @param {object} opts
- * @param {object} opts.provider    ITicketingProvider-compatible; only
- *                                  `getTicket(id)` is required.
+ * @param {object} opts.provider    Only `getTicket(id)` is required.
  * @param {string} opts.repoRoot    Absolute path to the main checkout.
- * @param {object} [opts.git]       `{ gitSpawn }` injection for tests.
- * @param {object} [opts.logger]    `{ info, warn, error }`.
+ * @param {object} [opts.git]
+ * @param {object} [opts.logger]
  * @returns {Promise<{
  *   reaped: Array<{ storyId: number, path: string }>,
  *   skipped: Array<{ storyId: number|null, path: string, reason: string }>,
@@ -95,11 +66,8 @@ export async function sweepStaleStoryWorktrees(opts = {}) {
   const resolvedWorktreeRoot =
     worktreeRoot ?? path.join(repoRoot, '.worktrees');
 
-  // Stage 2 + Stage 3: drain pending-cleanup manifest before touching the
-  // live worktree list. Retrying the Stage 1 sequence here picks up entries
-  // whose Windows file locks have since released; entries still stuck get
-  // their handle-holders enumerated and terminated (Windows only) so the
-  // ledger self-heals across sprints instead of accumulating.
+  // Drain the pending-cleanup manifest first so entries whose Windows locks
+  // have released self-heal instead of accumulating.
   const drainResult = await forceDrainPendingCleanup({
     repoRoot,
     worktreeRoot: resolvedWorktreeRoot,
@@ -121,10 +89,8 @@ export async function sweepStaleStoryWorktrees(opts = {}) {
 
   const entries = parseWorktreePorcelain(listRes.stdout || '');
 
-  // Phase 1 — fan out provider reads. Each mapper call captures its own
-  // error so a single transient provider hiccup doesn't trip
-  // concurrentMap's first-rejection-wins policy and abort the whole sweep;
-  // we want the original per-entry skip/continue semantics preserved.
+  // Each mapper captures its own error so one provider hiccup cannot abort
+  // the sweep via concurrentMap's first-rejection-wins policy.
   const reads = await concurrentMap(
     entries,
     async (entry) => {
@@ -142,10 +108,8 @@ export async function sweepStaleStoryWorktrees(opts = {}) {
     { concurrency: TICKET_READ_CONCURRENCY },
   );
 
-  // Phase 2 — sequential `git worktree remove`. These mutate
-  // .git/worktrees/ and the per-worktree admin dir; serializing avoids
-  // racing git's own locking on Windows where a half-removed entry can
-  // leave a partial admin dir that the next remove then trips over.
+  // Removes stay sequential: they mutate .git/worktrees/, and racing git's
+  // locking on Windows can leave a partial admin dir the next remove trips on.
   for (const r of reads) {
     if (r.kind === 'no-path' || r.kind === 'non-story') continue;
     if (r.kind === 'provider-error') {
@@ -198,8 +162,6 @@ export async function sweepStaleStoryWorktrees(opts = {}) {
     );
   }
 
-  // Drop any lingering worktree registrations. Cheap; safe to run whether
-  // or not we actually removed anything.
   git.gitSpawn(repoRoot, 'worktree', 'prune');
 
   return {

package/.agents/scripts/lib/orchestration/plan-text-hygiene.js

@@ -1,30 +1,9 @@
 /**
- * plan-text-hygiene.js — the advisory draft-Story lints: `open-question`
- * over body prose (Story #4599; narrowed to one lint by Story #5312) and
- * `pinned-identifier` over `acceptance[]` (Story #5323).
- *
- * A Story is executed by a non-interactive sub-agent, so an operator-directed
- * open question persisted into its body ("Flag if…", "TBD", "confirm with the
- * operator", a trailing `?`) can never be answered where it is read. This
- * module makes that class checkable at the one point a re-author loop exists —
- * the persist dry-run, which lists every match as a **warning** and proceeds.
- *
- * Story #5312 deleted the sibling `dangling-citation` and `slicing-mass`
- * lints with the critic gate that surfaced them: both scored prose shape the
- * authoring model already judges, and neither ever changed a persisted body.
- *
- * `pinned-identifier` is the one lint that scores the **binding** half of the
- * ticket; its classifier lives in
- * [`pinned-identifier-lint.js`](pinned-identifier-lint.js), which shares no
- * vocabulary with the prose heuristic here.
- *
- * Advisory by contract: findings are deterministic text for the dry-run's
- * warning list. They never gate persist and spawn nothing.
- *
- * Pure, synchronous, no I/O. Operates on the draft `stories.json` array,
- * reusing `parse()` from `lib/story-body/story-body.js` for section access.
- * An unparseable draft body is skipped, not failed — hygiene is advisory
- * and the persist validators own structural rejection.
+ * plan-text-hygiene.js — advisory draft-Story lints for the persist dry-run:
+ * `open-question` over body prose (a non-interactive sub-agent can never
+ * answer "TBD" or "confirm with the operator") and `pinned-identifier` over
+ * `acceptance[]`. Findings are warnings only; an unparseable body is skipped,
+ * since structural rejection belongs to the persist validators. Pure, no I/O.
  *
  * @module lib/orchestration/plan-text-hygiene
  */
@@ -32,14 +11,8 @@
 import { parse } from '../story-body/story-body.js';
 import { findPinnedIdentifiers } from './pinned-identifier-lint.js';
 
-/** Truncation length for the `evidence` excerpt on each finding. */
 const EVIDENCE_MAX_CHARS = 160;
 
-/**
- * Operator-directed open-question phrasings. Each match is an instruction
- * or question aimed at a human, which a non-interactive delivery sub-agent
- * can never answer.
- */
 const OPEN_QUESTION_MARKERS = [
   /\bflag if\b/i,
   /\bTBD\b/,
@@ -55,16 +28,13 @@ const OPEN_QUESTION_MARKERS = [
  */
 
 /**
- * Private-use sentinel standing in for one extracted inline code span. It
- * carries no question marker and no sentence boundary, so it is inert for
- * the heuristic while keeping the sentence split where the span sat.
+ * Private-use stand-in for an inline code span: inert to the heuristic but
+ * keeps the sentence split where the span sat.
  */
 const CODE_SLOT = '\uE000';
 
 /**
- * Replace fenced code blocks with a space and each inline code span with a
- * positional slot, so code content (shell snippets, grep patterns, JSON)
- * never trips a prose heuristic.
+ * Remove code so shell snippets or patterns never trip a prose heuristic.
  *
  * @param {string} text
  * @returns {string}
@@ -74,8 +44,7 @@ function stripCodeSpans(text) {
 }
 
 /**
- * Split prose into sentence-ish units with code content removed. Newlines
- * are boundaries too, so a bullet list yields one unit per bullet.
+ * Newlines are boundaries too: one unit per bullet.
  *
  * @param {string} text
  * @returns {string[]}
@@ -88,8 +57,6 @@ function splitSentences(text) {
 }
 
 /**
- * Truncate an excerpt for the finding's `evidence` field.
- *
  * @param {string} text
  * @returns {string}
  */
@@ -101,9 +68,6 @@ function excerpt(text) {
 }
 
 /**
- * open-question: operator-directed phrasing (or a trailing `?`) in prose a
- * non-interactive sub-agent executes.
- *
  * @param {string} prose - Raw Goal/Spec prose.
  * @param {string} slug
  * @returns {TextHygieneFinding[]}
@@ -130,12 +94,8 @@ function findOpenQuestions(prose, slug) {
 }
 
 /**
- * Evaluate the advisory lints over a draft Story array.
- *
  * @param {{ draftStories?: Array<object>|null }} args - The draft
- *   `stories.json` array (raw Story objects with top-level `slug` /
- *   `body`). Null/absent evaluates to zero findings (the single-delivery
- *   shape authors no draft tickets).
+ *   `stories.json` array; null/absent yields no findings.
  * @returns {{ findings: TextHygieneFinding[] }}
  */
 export function evaluateTextHygiene({ draftStories = null } = {}) {
@@ -147,8 +107,6 @@ export function evaluateTextHygiene({ draftStories = null } = {}) {
     try {
       body = parse(story?.body).body;
     } catch {
-      // Advisory lint: an unparseable body is the persist validators'
-      // rejection to make, not this evaluator's.
       continue;
     }
     const goal = typeof body.goal === 'string' ? body.goal : '';