mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -1,10 +1,6 @@
 /**
- * phases/authoring-context.js — emit-context phase.
- *
- * Builds the authoring context the host LLM (or the
- * `/mandrel-plan` author step) needs to write the Tech Spec.
- * Returns a plain JSON-serialisable object; never hits the network beyond
- * the provider call needed to load the Epic.
+ * phases/authoring-context.js — builds the JSON-serialisable authoring
+ * context the `/mandrel-plan` author step needs.
  */
 
 import path from 'node:path';
@@ -26,23 +22,9 @@ import { ensureDocsDigest } from '../docs-digest.js';
 import { buildMemoryPoolAdvisory } from './memory-pool-advisory.js';
 
 /**
- * Build the digest-first `docsContext` envelope field (Story #4433 — hard
- * cutover of the § 3.1 planning read contract to digest-first with
- * pull-on-demand, mirroring the Story #4324 delivery-children cutover).
- *
- * Ensures a docs digest exists at the **same** per-Epic temp path the
- * `/mandrel-deliver` story sub-agents already consume
- * (`<tempRoot>/epic-<seedIssueId>/docs-digest.md`) via the shared
- * `ensureDocsDigest` export in `docs-digest.js` — one generator, one file,
- * reused across the planning and delivery surfaces for the same Epic. The
- * envelope carries only the digest path, not embedded doc content; the
- * planner (host LLM driving the `/mandrel-plan` author step) reads the digest
- * and pulls a full file/section on demand when it bears on the decision.
- *
- * Returns `null` — a silent no-op — when `project.docsContextFiles` is not
- * configured. There is no scrape-every-markdown-under-docsRoot fallback for
- * planning; that fallback remains a `doc-reader.js` primitive used
- * elsewhere, not part of this envelope.
+ * Digest-first `docsContext`: ensure the docs digest at the same per-Epic
+ * temp path delivery consumes, and carry only its path. `null` when
+ * `project.docsContextFiles` is unset — there is no scrape-all fallback.
  *
  * @param {{ seedIssueId: number, settings: object, cwd: string }} args
  * @returns {Promise<{ mode: 'digest', digestPath: string } | null>}
@@ -72,16 +54,8 @@ async function buildPlanningDocsContext({ seedIssueId, settings, cwd }) {
 }
 
 /**
- * Story #2637 — index existing BDD scenarios so the Acceptance Engineer step
- * can annotate planned ACs with matches from the project's `.feature` files.
- * Empty (capped-shape) result when the project has not adopted BDD; the
- * scanner is best-effort and never throws on filesystem errors.
- *
- * Story #4977 — the scan itself stays uncapped (a faithful `.feature`
- * index), but the envelope-bound result is truncated to
- * `BDD_SCENARIOS_BYTE_BUDGET` via `capBddScenarios` so a mature Gherkin
- * corpus cannot alone consume the `/mandrel-plan` context-envelope ceiling. Callers
- * needing the raw count read `totalScenarios` vs `includedScenarios`.
+ * Best-effort `.feature` scenario index, capped to the byte budget so a large
+ * Gherkin corpus cannot consume the context-envelope ceiling.
  *
  * @returns {ReturnType<typeof capBddScenarios>}
  */
@@ -96,21 +70,8 @@ function scanBddScenariosBestEffort() {
 }
 
 /**
- * Build the authoring context the host LLM (or the
- * `/mandrel-plan` author step) needs to write the Tech Spec.
- *
- * `docsContext` is digest-first (Story #4433): a pointer at the per-Epic
- * docs digest rather than embedded doc content, `null` when
- * `project.docsContextFiles` is unset.
- *
- * The body carried here is **unbounded**. Story #4541 removed the
- * `applyBudget` pass (and the `--full-context` flag that toggled it): both
- * `plan-context.js` envelope builders discard this `epic` field entirely and
- * ship the raw seed on `seed.content` instead, so the budget bounded nothing
- * that shipped and the flag was a no-op. The raw-seed passthrough is
- * deliberate and test-pinned; the budget pass was the orphan. Envelope size
- * is guarded where it is actually decided — `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`
- * in `lib/orchestration/plan-context.js`.
+ * The `epic.body` carried here is unbounded; envelope size is guarded by
+ * `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` in `plan-context.js`.
  */
 export async function buildAuthoringContext(
   seedIssueId,
@@ -118,11 +79,7 @@ export async function buildAuthoringContext(
   settings = {},
   opts = {},
 ) {
-  // Epic #4474 (M3 PR2): `opts.epic` is an optional prefetched Epic object
-  // so a caller that already holds the issue (the folded `plan-context.js`
-  // envelope build, which also needs the raw body for clarity scoring and
-  // re-plan detection) does not pay a second provider fetch. Absent, the
-  // fetch behaviour is unchanged.
+  // A prefetched `opts.epic` saves a second provider fetch.
   const epic = opts.epic ?? (await provider.getEpic(seedIssueId));
   if (!epic) {
     throw new Error(`Epic #${seedIssueId} not found.`);
@@ -132,28 +89,8 @@ export async function buildAuthoringContext(
 
   const githubCfg = opts.github ?? null;
 
-  // Story #4952 — these five gathers share no data, so they run under bounded
-  // concurrency instead of five sequential awaits on the interactive `/mandrel-plan`
-  // path. `concurrentMap` preserves input order, so the destructuring is
-  // positional and the produced context is identical to the serial build:
-  //
-  //   1. the digest-first `docsContext` pointer (Story #4433);
-  //   2. Story #2094 Task #2103 — the project's BDD runner pending-tag
-  //      support, so the acceptance-spec body records either the verified tag
-  //      (features-first ordering) or "fallback: dependencies-first ordering"
-  //      when no supported runner is present;
-  //   3. the best-effort `.feature` scenario index;
-  //   4. Story #4919 — the memory-pool advisory that replaced the retired
-  //      memory-freshness pre-flight (#2557 / #4414) in the same slot. The
-  //      scanner marked an entry stale when a cited issue was closed, but the
-  //      memory corpus is delivery retrospectives whose subject IS a delivered
-  //      Story — and its directory (`~/.claude/projects/<repo>/memory/`) never
-  //      resolved, because harness project dirs are cwd-slugs. This renders no
-  //      per-entry verdict at all: it stats and counts, and the `/mandrel-plan` spine
-  //      surfaces `recommend` at Gate #1. Filesystem-only and total;
-  //   5. Story #2554 — open meta feedback issues, so retro signals are routed
-  //      into durable substrates rather than lost in chat. Best-effort:
-  //      missing owner/repo or gh-CLI failures land in `errors[]`, never throw.
+  // Independent gathers under bounded concurrency; `concurrentMap` preserves
+  // input order, so the destructuring is positional.
   const [
     docsContext,
     bddRunner,
@@ -165,15 +102,7 @@ export async function buildAuthoringContext(
       () => buildPlanningDocsContext({ seedIssueId: epic.id, settings, cwd }),
       () => verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT }),
       () => scanBddScenariosBestEffort(),
-      () =>
-        buildMemoryPoolAdvisory({
-          cwd: PROJECT_ROOT,
-          // Story #5182 — `planning.memoryPool` thresholds. Spread so an
-          // unset block, or a block setting only one key, leaves the other
-          // on its framework default rather than passing `undefined` in as
-          // a value the builder would have to re-defaults itself.
-          ...(opts.memoryPool ?? {}),
-        }),
+      () => buildMemoryPoolAdvisory({ cwd: PROJECT_ROOT }),
       () =>
         fetchPriorFeedback({
           owner: githubCfg?.owner,
@@ -181,39 +110,15 @@ export async function buildAuthoringContext(
         }),
     ],
     (gather) => gather(),
-    // The independent context gathers (Story #4952): a handful of local
-    // probes plus one `gh` read, so this rides the shared fan-out bound
-    // rather than declaring its own.
     { concurrency: FANOUT_CONCURRENCY },
   );
 
-  // Story #4811 — the codebase snapshot (#2634), its authoring grounding
-  // (#4139 F10) and the spec-freshness helpers behind it are retired. The
-  // pre-computed structural view grounded nothing it promised: the default
-  // include globs missed the standard monorepo layout outright, its remedies
-  // pointed at knobs that re-filtered the same set, and its cited-but-absent
-  // signal inverted into noise whenever the snapshot was the thing that was
-  // wrong. Grounding now rests on the two mechanisms that read the real tree:
-  // the authoring model's own targeted retrieval (the digest-first precedent
-  // of Story #4433) and the Phase 8 `validateStoryFileAssumptions` gate, which
-  // probes every authored `{path, assumption}` against the working tree as a
-  // hard error. Nothing pre-computed replaces it — a stale inventory is the
-  // failure mode, not the fix.
-
-  // Story #4542 — planning authors no risk artifact at all. Review depth and
-  // the acceptance-critic mode are derived from the diff at close time
-  // (`review-depth.js#deriveChangeLevel`), so there is nothing to classify
-  // here and nothing for the author step to judge about itself.
-
   return {
     epic: {
       id: epic.id,
       title: epic.title,
       body: epic.body ?? null,
-      // Story #4324: the context-ticket classes are retired. A re-planned
-      // Epic's previous Tech Spec / Acceptance Table content rides along
-      // inside `body` (managed sections), which is how the author keeps
-      // AC IDs stable across re-plans.
+      // A re-plan's prior managed sections ride in `body`, keeping AC IDs stable.
       planningSections: {
         techSpec: hasTicketSection(epic.body ?? '', 'techSpec'),
         acceptanceTable: hasTicketSection(epic.body ?? '', 'acceptanceTable'),

package/.agents/scripts/lib/orchestration/planning/memory-pool-advisory.js

@@ -1,72 +1,23 @@
 /**
- * memory-pool-advisory.js — the `/mandrel-plan` Phase 0 memory-hygiene advisory.
+ * memory-pool-advisory.js — the `/mandrel-plan` memory-hygiene advisory.
  *
- * Replaces the retired memory-freshness pre-flight (Story #2557 / #4414) in
- * the same slot, fixing both of that design's defects:
- *
- *   1. **Correct pool resolution.** The retired `resolveMemoryDir` built
- *      `~/.claude/projects/<github.repo>/memory/`, but harness project
- *      directories are **cwd-slugs** — the absolute cwd with every `/` and `.`
- *      replaced by `-` — so the old path never resolved in any consumer and
- *      the scan was a silent no-op everywhere.
- *   2. **A named consumer.** The retired scanner emitted a per-entry staleness
- *      verdict nothing read. This emits one advisory the `/mandrel-plan` spine
- *      surfaces at Gate #1, recommending `/memory-consolidate`.
- *
- * It renders **no per-entry verdict at all**. A memory citing a closed issue
- * is a delivery retrospective whose subject is that issue — not a stale entry
- * — and only the attended `/memory-consolidate` pass, reading content, can
- * tell the difference. This module measures one thing; it never judges an
- * entry.
- *
- * **One arm: the index byte ceiling (Story #5285, sole survivor after Story
- * #5312).** The harness reads `MEMORY.md` into every session under a hard
- * byte cap and **truncates** past it, so an index over that cap loses its
- * tail entries silently — the pointers are on disk, indexed, and unreachable.
- * That is a loss in progress, not a hygiene forecast, and it is the only
- * signal that measures the artifact a session actually loads. The stamp-age
- * and growth-delta arms that used to sit beside it measured the *pool*, fired
- * on every plan once a pool was mature, and were learned-ignored by exactly
- * the operators they nagged; Story #5312 deleted them with their
- * `planning.memoryPool.{staleAfterDays, growthDelta}` knobs. A pass that
- * rewrites long index lines short clears this arm without pruning a single
- * entry.
- *
- * Detection is filesystem-only — no child processes, no `gh` probes, no
- * network. Every failure path fails soft to "no pool, no recommendation": the
- * advisory can degrade the nudge, never a plan.
- *
- * Test seams: `cwd`, `env`, `fsImpl` (node:fs-compatible `statSync` /
- * `readdirSync`), and the `indexByteCeiling` threshold.
- *
- * `buildMemoryPoolAdvisory` is the **only** export: the helpers below have no
- * caller outside this module, and exporting one solely for a test would add a
- * row to the `dead-exports-production` ratchet. Tests reach every branch
- * through the seams above — do not "fix" the missing exports.
+ * Recommends `/memory-consolidate` when `MEMORY.md` exceeds the harness's
+ * index cap (past it, later entries are truncated away). Never judges an
+ * entry; filesystem-only and fail-soft.
  */
 
 import * as defaultFs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
-/**
- * Recommend a pass once `MEMORY.md` exceeds this many bytes.
- *
- * 24576 (24 KiB) is the harness's own index cap — the point past which it
- * truncates the file it loads into a session, making every entry after the
- * cut unreachable. The default is the cap itself rather than a margin under
- * it: the arm reports a loss that has already started, not one approaching.
- */
+/** The harness's own index cap (24 KiB): past it, the loss has already started. */
 const INDEX_BYTE_CEILING = 24_576;
 
 /** The index file is not itself a memory entry. */
 const INDEX_FILENAME = 'MEMORY.md';
 
 /**
- * Slugify an absolute path the way the harness names its per-project
- * directories: every `/` and `.` becomes `-`. Verified against real
- * directories in `~/.claude/projects/` — a plain checkout and a worktree both
- * round-trip exactly.
+ * Harness per-project dir naming: every `/` and `.` becomes `-`.
  *
  * @param {string} absPath
  * @returns {string}
@@ -76,10 +27,7 @@ function slugifyProjectPath(absPath) {
 }
 
 /**
- * Resolve the memory pool directory for a working directory.
- *
- * `MANDREL_MEMORY_DIR` wins outright (operator override and test seam);
- * otherwise `~/.claude/projects/<cwd-slug>/memory/`.
+ * `MANDREL_MEMORY_DIR` wins; else `~/.claude/projects/<cwd-slug>/memory/`.
  *
  * @param {{ cwd?: string, env?: Record<string,string|undefined>, homedir?: string }} [opts]
  * @returns {string|null} absolute pool path, or `null` when unresolvable
@@ -107,10 +55,6 @@ function resolveMemoryPoolDir({ cwd, env = process.env, homedir } = {}) {
 /**
  * Run one filesystem probe, falling back on any failure.
  *
- * Every read here is fail-soft by design — the advisory may degrade its nudge
- * but never a plan — so every probe has the same try/catch shape wrapped
- * around one expression. One helper states the rule once.
- *
  * @template T
  * @param {() => T} read
  * @param {T|null} [fallback]
@@ -125,13 +69,7 @@ function probe(read, fallback = null) {
 }
 
 /**
- * The index file's size in bytes.
- *
- * `null` when it cannot be stat'd — an absent or unreadable `MEMORY.md`
- * leaves the arm silent rather than guessing a size, on the same fail-soft
- * rule every other probe here follows. Stat'd rather than read: the arm needs
- * the length, never the content, and this module deliberately never reads a
- * memory's text.
+ * Stat'd, never read: this module never reads a memory's text.
  *
  * @returns {number|null}
  */
@@ -143,8 +81,6 @@ function readIndexBytes({ poolDir, fsImpl }) {
 }
 
 /**
- * Count memory entries — `.md` files other than the index.
- *
  * @returns {number|null} `null` when the directory cannot be listed
  */
 function countEntries({ poolDir, fsImpl }) {
@@ -158,10 +94,7 @@ function countEntries({ poolDir, fsImpl }) {
 }
 
 /**
- * The advisory's field set, defaulted to the fail-soft "no usable pool"
- * reading. Every return path spreads its own findings over this, so the
- * envelope's shape is declared once — a new field cannot reach some callers
- * and not others, which is the failure mode a per-branch object literal has.
+ * The envelope shape, declared once and defaulted to "no usable pool".
  *
  * @param {object} fields
  * @returns {{ present: boolean, entryCount: number, indexBytes: number|null,
@@ -179,11 +112,7 @@ function envelope(fields) {
 }
 
 /**
- * Build the `memoryPoolAdvisory` envelope field.
- *
- * Advisory only — it carries **no routing authority**. The `/mandrel-plan`
- * spine surfaces `recommend` at Gate #1 on one advisory line; nothing
- * auto-runs, and nothing here mutates the operator's memory store.
+ * Advisory only: no routing authority, and nothing here mutates the store.
  *
  * @param {object} [opts]
  * @param {string} [opts.cwd] — defaults to `process.cwd()`
@@ -236,8 +165,7 @@ export function buildMemoryPoolAdvisory({
 }
 
 /**
- * The index byte arm's verdict. `indexBytes === null` is an unreadable index,
- * not a small one, so it stays quiet and says why.
+ * `null` is an unreadable index, not a small one: stay quiet and say why.
  *
  * @param {number|null} indexBytes
  * @param {number} indexByteCeiling