mandrel 2.56.0 → 2.57.0

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -7,8 +7,9 @@
  * the Stage-1 split-policy validator (`assertAcceptancePartition`).
  *
  * Each Story body is the single executable document: Tech Spec stays inline
- * under `## Spec`. Over-budget Specs fail closed (split / tighten) — never
- * spill to `docs/`. Top-level `acceptance[]` / `verify[]` are the machine
+ * under `## Spec`, at whatever length the work needs (Story #5312 deleted
+ * the token budget that used to refuse it) — never spilled to `docs/`.
+ * Top-level `acceptance[]` / `verify[]` are the machine
  * contract and are synced into the body so the GitHub issue stays complete
  * without requiring the LLM to dual-author the same lists.
  *
@@ -33,7 +34,6 @@ import {
   concurrentMap,
   FANOUT_CONCURRENCY,
 } from '../../util/concurrent-map.js';
-import { assertSpecWithinBudget } from '../spec-spill.js';
 import { assertAcceptancePartition } from '../split-policy-validator.js';
 import {
   externalDependencyId,
@@ -60,13 +60,6 @@ export const PLAN_RUN_LABEL_PREFIX = 'plan-run::';
 /** Stable color for the cohort grouping label (`ensureLabels`). */
 const PLAN_RUN_LABEL_COLOR = '#C5DEF5';
 
-/**
- * Stable color for the `route::lite` ceremony-route hint (Story #4707;
- * hint-only since Story #4722 — `/mandrel-deliver` re-derives the route from the
- * Story body's shape).
- */
-const LITE_ROUTE_LABEL_COLOR = '#D4C5F9';
-
 /** Length of the derived plan-run id (hex chars). */
 const PLAN_RUN_ID_LENGTH = 8;
 
@@ -226,11 +219,10 @@ function extractPlanFingerprint(body) {
  * Labels the authoring pass is never allowed to set. The `agent::*` axis is
  * the runtime's lifecycle state (persist owns the terminal `agent::ready`
  * flip itself), `type::*` is fixed to `type::story` by the v2 hierarchy,
- * `persona::*` is a retired axis, `plan-run::*` is the runtime-derived
- * cohort grouping axis (Story #4692), and `route::*` is the runtime-derived
- * ceremony-route axis (Story #4707) — a hand-authored entry on either
- * derived axis would compete with the deterministic label persist applies
- * itself.
+ * `persona::*` and `route::*` are retired axes (the latter with the
+ * plan-side lite claim, Story #5312), and `plan-run::*` is the
+ * runtime-derived cohort grouping axis (Story #4692) — a hand-authored entry
+ * on it would compete with the deterministic label persist applies itself.
  */
 const FORBIDDEN_LABEL_PREFIXES = Object.freeze([
   'agent::',
@@ -299,8 +291,6 @@ function bodyObjectFromTicket(ticket) {
     verify: ticket.verify ?? [],
     references: ticket.references ?? [],
     non_goals: ticket.non_goals ?? [],
-    wide: ticket.wide ?? null,
-    reason_to_exist: ticket.reason_to_exist ?? null,
     depends_on: ticket.depends_on ?? [],
   }).body;
 }
@@ -398,7 +388,7 @@ export function normalizeStoryTicket(ticket) {
 
 /**
  * Fold optional shared Tech Spec prose into a Story body when the Story has
- * no inline Spec. Specs stay inline; over-budget Specs throw.
+ * no inline Spec. Specs stay inline, verbatim, at any length.
  *
  * Precedence: per-Story `body.spec` wins; otherwise `sharedSpec` is used
  * (N===1 convenience only — callers must not share one Spec across N>1).
@@ -430,8 +420,7 @@ export function foldSpecIntoStoryBody(bodyObject, slug, opts = {}) {
     return { bodyObject: next };
   }
 
-  const { content } = assertSpecWithinBudget({ storyId: slug, spec: inline });
-  next.spec = content;
+  next.spec = inline;
   return { bodyObject: next };
 }
 
@@ -854,16 +843,14 @@ async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
 }
 
 /**
- * Ensure a runtime-derived persist label (`plan-run::<id>` cohort grouping,
- * `route::lite` route marker) exists before it is applied — GitHub's
- * create-issue path does not auto-create unknown labels on every provider
- * route, and an opaque derived label never exists yet.
+ * Ensure the runtime-derived `plan-run::<id>` cohort label exists before it
+ * is applied — GitHub's create-issue path does not auto-create unknown
+ * labels on every provider route, and an opaque derived label never exists
+ * yet.
  *
  * **Non-fatal by design**, matching the native-blocked_by mirroring posture:
- * neither label is load-bearing for correctness (grouping is cosmetic, and
- * the route label is a human-visible hint only — `/mandrel-deliver` re-derives the
- * route from the Story body's shape, Story #4722), so it is never a reason
- * to fail persist. On an ensure
+ * the label is not load-bearing for correctness (grouping is cosmetic), so
+ * it is never a reason to fail persist. On an ensure
  * failure (throw, or the label reported `missing` by the post-loop
  * reconcile) the create loop proceeds **without** the label — applying an
  * unensured label could fail the issue create itself, and the Stories matter
@@ -957,30 +944,16 @@ async function ensurePersistLabel({
  * every id is known (Story #4544), so plan-created order stops depending on
  * prose. That pass is non-fatal — see `mirrorNativeDependencyEdges`.
  *
- * **A lite-routed cohort carries the `route::lite` hint** (Story #4707,
- * hint-only since Story #4722). When the caller resolves the plan's
- * effective complexity route to `lite` (the planner's recorded verdict,
- * upheld by the shape backstop), it passes the label via `opts.routeLabel`
- * and every created Story carries it — a **human-visible hint only**, never
- * the control signal: `/mandrel-deliver` re-derives the route from each Story body's
- * own shape (`resolveStoryDispatchMode`), so a lost or failed label write
- * cannot misroute delivery. A full-routed plan passes nothing and its
- * Stories carry **no** route label. Like the cohort label, the ensure is
- * non-fatal — the label is cosmetic either way.
- *
  * @param {object} args
  * @param {object} args.provider
  * @param {ReturnType<typeof assemblePlanStories>['stories']} args.stories
  * @param {object} [args.opts]
  * @param {boolean} [args.opts.dryRun=false]
- * @param {string|null} [args.opts.routeLabel=null] Route marker label to
- *   apply to every created Story (`route::lite`), or null for none.
  * @returns {Promise<{
  *   created: Array<{ slug: string, id: number, url?: string, title: string, adopted: boolean }>,
  *   dependencyEdges: { edgesAdded: number, edgesSkipped: number, edgesFailed: number, storiesProcessed: number }|null,
  *   planRunLabel: string,
  *   planRunLabelApplied: boolean,
- *   routeLabel: string|null,
  * }>}
  */
 export async function createStoryIssues({ provider, stories, opts = {} }) {
@@ -991,10 +964,6 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
   }
 
   const list = Array.isArray(stories) ? stories : [];
-  const routeLabel =
-    typeof opts.routeLabel === 'string' && opts.routeLabel.trim() !== ''
-      ? opts.routeLabel.trim()
-      : null;
 
   // Derived once for the whole cohort, before any write — a pure function of
   // the authored artifacts, so dry-run can report it write-free and a resume
@@ -1018,7 +987,6 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       // the label — the derived id is still reported, the application is not
       // claimed.
       planRunLabelApplied: false,
-      routeLabel,
     };
   }
 
@@ -1031,18 +999,6 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       'metadata only, never a deliver input.',
     role: 'cohort',
   });
-  const applyRouteLabel =
-    routeLabel !== null &&
-    (await ensurePersistLabel({
-      provider,
-      label: routeLabel,
-      color: LITE_ROUTE_LABEL_COLOR,
-      description:
-        'Ceremony-lite hint only: /mandrel-deliver re-derives the route; ' +
-        'every close gate still runs.',
-      role: 'route-marker',
-    }));
-
   const { byFingerprint, idsByTitle } = await indexExistingStories(provider);
   const created = [];
   const idBySlug = new Map();
@@ -1073,11 +1029,7 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
     const result = await provider.createIssue({
       title: story.title,
       body: renderStoryBodyForCreate(story, idBySlug),
-      labels: [
-        ...story.labels,
-        ...(applyCohortLabel ? [cohortLabel] : []),
-        ...(applyRouteLabel ? [routeLabel] : []),
-      ],
+      labels: [...story.labels, ...(applyCohortLabel ? [cohortLabel] : [])],
       // Story #5112 — hand the provider the same content-keyed lookup this
       // loop's resume path uses, so a retry after a lost response adopts the
       // issue attempt 1 already filed instead of creating a twin.
@@ -1128,7 +1080,6 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
     // consult before advertising a `label:` filter that may match nothing.
     planRunLabel: cohortLabel,
     planRunLabelApplied: applyCohortLabel,
-    routeLabel: applyRouteLabel ? routeLabel : null,
   };
 }
 

package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js

@@ -10,23 +10,19 @@
  * @module lib/orchestration/plan-persist/wave-serialisation
  */
 
-import {
-  detectCollision,
-  OVERLAP_SOURCES,
-  renderScrapeAttribution,
-} from '../../wave-runner/footprint.js';
+import { detectCollision } from '../../wave-runner/footprint.js';
 
 /**
  * Predict which same-wave pairs the dispatch guard will actually refuse to
  * co-dispatch (Story #5265).
  *
  * The wave table answers a `depends_on` question, and the runtime answers a
- * different one: `stories-wave-tick.js` withholds on {@link detectCollision},
- * whose footprint is the declared `changes[]` **plus** every path scraped out
- * of the Story's title, spec and serialized body — and that body carries
- * `## Verify`, so two Stories that merely run the same gate script share a
- * path neither will edit. The table therefore promised parallelism the very
- * next tick refused, with nothing anywhere reconciling the two.
+ * different one: `stories-wave-tick.js` withholds on {@link detectCollision}
+ * over the declared `changes[]` (Story #5313 retired the text scrape), so
+ * two same-wave Stories that both declare a path — a shared generated
+ * baseline, say — are shown in one order and dispatched one at a time. The
+ * table promised parallelism the next tick refused, with nothing anywhere
+ * reconciling the two.
  *
  * This runs the runtime's own exported predicate — not a reimplementation of
  * it — pairwise within each wave, so the prediction cannot drift from the
@@ -34,8 +30,8 @@ import {
  *
  * @param {ReturnType<typeof buildWaveTable>} waveTable
  * @param {Array<{ slug: string, title?: string, body?: string, spec?: string, changes?: Array }>} stories
- * @param {{ tempRoot?: string }} [options]
- * @returns {Array<{ wave: number, slugs: [string, string], paths: string[], source: string, attribution: object[] }>}
+ * @param {{ tempRoot?: string }} [options] Accepted for compatibility; unread.
+ * @returns {Array<{ wave: number, slugs: [string, string], paths: string[], source: string }>}
  */
 export function predictWaveSerialisation(waveTable, stories, options = {}) {
   const bySlug = new Map(
@@ -71,8 +67,7 @@ export function predictWaveSerialisation(waveTable, stories, options = {}) {
  * against the same promise, and an operator should read them the same way.
  * The difference is what they know — the shared-editor pass names paths two
  * Stories both *write*, this one names every pair the dispatcher will refuse
- * to run together whatever the reason, including the pairs whose only shared
- * path was scraped out of a `## Verify` line.
+ * to run together, glob declarations included.
  *
  * @param {ReturnType<typeof predictWaveSerialisation>} collisions
  * @returns {string[]}
@@ -80,31 +75,23 @@ export function predictWaveSerialisation(waveTable, stories, options = {}) {
 export function renderPredictedSerialisationLines(collisions) {
   const list = Array.isArray(collisions) ? collisions : [];
   if (list.length === 0) return [];
-  const rows = list.map((c) => {
-    const scraped = renderScrapeAttribution(c.attribution);
-    return `| \`${c.slugs[0]}\` + \`${c.slugs[1]}\` | ${c.paths
-      .map((p) => `\`${p}\``)
-      .join(', ')} | ${c.source} | ${scraped ? `\`${scraped}\`` : '—'} |`;
-  });
-  const scrapedOnly = list.filter(
-    (c) => c.source === OVERLAP_SOURCES.SCRAPED,
-  ).length;
+  const rows = list.map(
+    (c) =>
+      `| \`${c.slugs[0]}\` + \`${c.slugs[1]}\` | ${c.paths
+        .map((p) => `\`${p}\``)
+        .join(', ')} | ${c.source} |`,
+  );
   return [
     '',
     `#### ⚠️ Predicted serialisation (${list.length} same-order pair(s))`,
     '',
-    '| Stories | Colliding paths | Overlap source | Scraped from |',
-    '| --- | --- | --- | --- |',
+    '| Stories | Colliding paths | Overlap source |',
+    '| --- | --- | --- |',
     ...rows,
     '',
-    '_The dispatcher compares the **evidence-widened** footprint — declared ' +
-      '`changes[]` plus every path named in the title, `## Spec` and the rest ' +
-      'of the body — so these pairs are shown in one order above but will be ' +
-      `dispatched one at a time. ${scrapedOnly} pair(s) collide only on ` +
-      'scraped paths; the "Scraped from" column names the field each such ' +
-      'path was read out of, so a shared `## Verify` command is ' +
-      'distinguishable from a genuine unpredicted edit target. The guard is ' +
-      'deliberately not narrowed to `changes[]`: the declaration is a lower ' +
-      'bound (Story #4875) and under-serialising is the worse failure._',
+    '_The dispatcher compares the **declared** `changes[]` footprints ' +
+      '(Story #5313 retired the text scrape), so these pairs are shown in ' +
+      'one order above but will be dispatched one at a time: both Stories ' +
+      'declare a colliding path, or one declares a glob._',
   ];
 }

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

@@ -1,33 +1,19 @@
 /**
- * plan-text-hygiene.js — deterministic text-hygiene lints over draft Story
- * bodies (Story #4599).
+ * plan-text-hygiene.js — the `open-question` lint over draft Story bodies
+ * (Story #4599; narrowed to one lint by Story #5312).
  *
- * The text analysis of Stories #4592–#4594 (and domio#1684) surfaced three
- * body-defect classes no gate checks: dangling prose citations whose carrier
- * document is unlocatable, operator-directed open questions persisted into
- * tickets executed by non-interactive sub-agents, and `## Slicing` sections
- * carrying more mass than the `## Spec` they are supposed to checkpoint.
- * This module makes those classes checkable at the one point a re-author
- * loop exists — the pre-persist critic gate (`plan-critics.js`).
+ * 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.
  *
- * Advisory by contract: findings are deterministic text for the workflow's
- * re-author round. They never gate persist, never flip a dispatch verdict,
- * and spawn nothing.
+ * 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.
  *
- * Heuristics are deliberately narrow (few false positives over recall):
- *
- *   - **dangling-citation** — a sentence referencing a document section
- *     (`§`, "design note", "review doc") with no repo-relative path and no
- *     `#<digits>` issue anchor in the same sentence. An anchor written
- *     inside a code span counts — the conventional markdown form (Story
- *     #4906).
- *   - **open-question** — interrogative-to-operator phrasing ("Flag if",
- *     "TBD", "confirm with the operator", a trailing `?`) in Goal/Spec
- *     prose outside code spans. Bodies record decisions; unresolved
- *     unknowns belong in declarative Key Assumptions.
- *   - **slicing-mass** — `## Slicing` character mass exceeding `## Spec`
- *     character mass when both are present: checkpoints carrying
- *     Spec-grade detail the Spec then re-covers.
+ * 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.
@@ -42,19 +28,6 @@ import { parse } from '../story-body/story-body.js';
 /** Truncation length for the `evidence` excerpt on each finding. */
 const EVIDENCE_MAX_CHARS = 160;
 
-/**
- * Phrases the citation heuristic treats as a reference to an external
- * carrier document. Matched case-insensitively within one sentence.
- */
-const CITATION_MARKERS = [/§/, /\bdesign note\b/i, /\breview doc\b/i];
-
-/**
- * Anchors that locate a citation: a `#<digits>` issue reference or a
- * repo-relative path (a slash-joined token carrying a file-ish segment).
- */
-const ISSUE_ANCHOR = /#\d+/;
-const REPO_PATH_ANCHOR = /[\w.-]+\/[\w./-]+/;
-
 /**
  * Operator-directed open-question phrasings. Each match is an instruction
  * or question aimed at a human, which a non-interactive delivery sub-agent
@@ -68,62 +41,43 @@ const OPEN_QUESTION_MARKERS = [
 
 /**
  * @typedef {Object} TextHygieneFinding
- * @property {'dangling-citation'|'open-question'|'slicing-mass'} kind
+ * @property {'open-question'} kind
  * @property {string} slug - The draft Story's slug ('' when absent).
  * @property {string} evidence - Excerpt of the offending text.
  * @property {string} message - Human-readable, re-author-actionable text.
  */
 
 /**
- * Private-use sentinel standing in for one extracted inline code span.
- * It carries no citation marker, no anchor and no sentence boundary, so it
- * is inert for every marker heuristic while recording where the span sat.
+ * 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.
  */
-const CODE_SLOT_PATTERN = /\uE000(\d+)\uE001/g;
+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 yet stays recoverable for the anchor check.
+ * never trips a prose heuristic.
  *
  * @param {string} text
- * @returns {{ slotted: string, spans: string[] }}
+ * @returns {string}
  */
-function slotCodeSpans(text) {
-  const spans = [];
-  const slotted = text
-    .replace(/```[\s\S]*?```/g, ' ')
-    .replace(/`[^`\n]*`/g, (span) => {
-      spans.push(span.slice(1, -1));
-      return `\uE000${spans.length - 1}\uE001`;
-    });
-  return { slotted, spans };
+function stripCodeSpans(text) {
+  return text.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`\n]*`/g, CODE_SLOT);
 }
 
 /**
- * Split prose into sentence-ish units. Newlines are boundaries too, so a
- * bullet list yields one unit per bullet. Each unit carries two views of
- * the same sentence: `prose`, with code content removed, which every
- * marker heuristic reads; and `anchorText`, with inline code content
- * restored, so a citation anchored inside a code span is still visible to
- * the anchor check. Restoring only ever adds anchors — markers are matched
- * against `prose` alone, exactly as before.
+ * Split prose into sentence-ish units with code content removed. Newlines
+ * are boundaries too, so a bullet list yields one unit per bullet.
  *
  * @param {string} text
- * @returns {Array<{ prose: string, anchorText: string }>}
+ * @returns {string[]}
  */
 function splitSentences(text) {
-  const { slotted, spans } = slotCodeSpans(text);
-  return slotted
+  return stripCodeSpans(text)
     .split(/(?<=[.!?])\s+|\n+/)
-    .map((unit) => ({
-      prose: unit.replace(CODE_SLOT_PATTERN, ' ').trim(),
-      anchorText: unit.replace(
-        CODE_SLOT_PATTERN,
-        (_slot, index) => ` ${spans[Number(index)]} `,
-      ),
-    }))
-    .filter((unit) => unit.prose.length > 0);
+    .map((unit) => unit.replaceAll(CODE_SLOT, ' ').trim())
+    .filter((unit) => unit.length > 0);
 }
 
 /**
@@ -139,37 +93,6 @@ function excerpt(text) {
     : flat;
 }
 
-/**
- * dangling-citation: a citation-marker sentence with no locating anchor.
- * The marker is matched against the sentence's code-stripped prose; the
- * anchor against its code-restored text, so a path or issue reference
- * written in a code span — the conventional markdown form — counts.
- *
- * @param {string} prose - Raw body prose.
- * @param {string} slug
- * @returns {TextHygieneFinding[]}
- */
-function findDanglingCitations(prose, slug) {
-  const findings = [];
-  for (const { prose: sentence, anchorText } of splitSentences(prose)) {
-    const cites = CITATION_MARKERS.some((m) => m.test(sentence));
-    if (!cites) continue;
-    const anchored =
-      ISSUE_ANCHOR.test(anchorText) || REPO_PATH_ANCHOR.test(anchorText);
-    if (anchored) continue;
-    findings.push({
-      kind: 'dangling-citation',
-      slug,
-      evidence: excerpt(sentence),
-      message:
-        'Citation names a document section but no repo-relative path or ' +
-        '#<issue> anchor locates it in the same sentence — the executing ' +
-        'agent cannot follow it. Anchor the citation or inline the claim.',
-    });
-  }
-  return findings;
-}
-
 /**
  * open-question: operator-directed phrasing (or a trailing `?`) in prose a
  * non-interactive sub-agent executes.
@@ -180,7 +103,7 @@ function findDanglingCitations(prose, slug) {
  */
 function findOpenQuestions(prose, slug) {
   const findings = [];
-  for (const { prose: sentence } of splitSentences(prose)) {
+  for (const sentence of splitSentences(prose)) {
     const marked =
       OPEN_QUESTION_MARKERS.some((m) => m.test(sentence)) ||
       sentence.endsWith('?');
@@ -200,33 +123,7 @@ function findOpenQuestions(prose, slug) {
 }
 
 /**
- * slicing-mass: `## Slicing` outweighing `## Spec` when both are present.
- *
- * @param {{ slicing?: string, spec?: string }} body - Parsed Story body.
- * @param {string} slug
- * @returns {TextHygieneFinding[]}
- */
-function findSlicingMass(body, slug) {
-  const slicing = typeof body.slicing === 'string' ? body.slicing : '';
-  const spec = typeof body.spec === 'string' ? body.spec : '';
-  if (slicing.length === 0 || spec.length === 0) return [];
-  if (slicing.length <= spec.length) return [];
-  return [
-    {
-      kind: 'slicing-mass',
-      slug,
-      evidence: excerpt(slicing),
-      message:
-        `## Slicing (${slicing.length} chars) outweighs ## Spec ` +
-        `(${spec.length} chars) — checkpoints are carrying Spec-grade ` +
-        'detail. Keep each Slicing checkpoint to one line and move the ' +
-        'detail into ## Spec.',
-    },
-  ];
-}
-
-/**
- * Evaluate the three text-hygiene lints over a draft Story array.
+ * Evaluate the open-question lint over a draft Story array.
  *
  * @param {{ draftStories?: Array<object>|null }} args - The draft
  *   `stories.json` array (raw Story objects with top-level `slug` /
@@ -249,13 +146,7 @@ export function evaluateTextHygiene({ draftStories = null } = {}) {
     }
     const goal = typeof body.goal === 'string' ? body.goal : '';
     const spec = typeof body.spec === 'string' ? body.spec : '';
-    const bodyProse =
-      typeof story.body === 'string' ? story.body : [goal, spec].join('\n');
-    findings.push(
-      ...findDanglingCitations(bodyProse, slug),
-      ...findOpenQuestions([goal, spec].join('\n'), slug),
-      ...findSlicingMass(body, slug),
-    );
+    findings.push(...findOpenQuestions([goal, spec].join('\n'), slug));
   }
   return { findings };
 }