mandrel 2.0.0 → 2.2.0

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

@@ -0,0 +1,230 @@
+/**
+ * plan-text-hygiene.js — deterministic text-hygiene lints over draft Story
+ * bodies (Story #4599).
+ *
+ * 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`).
+ *
+ * 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.
+ *
+ * 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.
+ *   - **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.
+ *
+ * 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.
+ *
+ * @module lib/orchestration/plan-text-hygiene
+ */
+
+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
+ * can never answer.
+ */
+const OPEN_QUESTION_MARKERS = [
+  /\bflag if\b/i,
+  /\bTBD\b/,
+  /\bconfirm with the operator\b/i,
+];
+
+/**
+ * @typedef {Object} TextHygieneFinding
+ * @property {'dangling-citation'|'open-question'|'slicing-mass'} 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.
+ */
+
+/**
+ * Strip fenced code blocks and inline code spans so code content (shell
+ * snippets, grep patterns, JSON) never trips a prose heuristic.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function stripCodeSpans(text) {
+  return text.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`\n]*`/g, ' ');
+}
+
+/**
+ * Split prose into sentence-ish units. Newlines are boundaries too, so a
+ * bullet list yields one unit per bullet.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitSentences(text) {
+  return text
+    .split(/(?<=[.!?])\s+|\n+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Truncate an excerpt for the finding's `evidence` field.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function excerpt(text) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > EVIDENCE_MAX_CHARS
+    ? `${flat.slice(0, EVIDENCE_MAX_CHARS - 1)}…`
+    : flat;
+}
+
+/**
+ * dangling-citation: a citation-marker sentence with no locating anchor.
+ *
+ * @param {string} prose - Code-stripped body prose.
+ * @param {string} slug
+ * @returns {TextHygieneFinding[]}
+ */
+function findDanglingCitations(prose, slug) {
+  const findings = [];
+  for (const sentence of splitSentences(prose)) {
+    const cites = CITATION_MARKERS.some((m) => m.test(sentence));
+    if (!cites) continue;
+    const anchored =
+      ISSUE_ANCHOR.test(sentence) || REPO_PATH_ANCHOR.test(sentence);
+    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.
+ *
+ * @param {string} prose - Code-stripped Goal/Spec prose.
+ * @param {string} slug
+ * @returns {TextHygieneFinding[]}
+ */
+function findOpenQuestions(prose, slug) {
+  const findings = [];
+  for (const sentence of splitSentences(prose)) {
+    const marked =
+      OPEN_QUESTION_MARKERS.some((m) => m.test(sentence)) ||
+      sentence.endsWith('?');
+    if (!marked) continue;
+    findings.push({
+      kind: 'open-question',
+      slug,
+      evidence: excerpt(sentence),
+      message:
+        'Body text carries an operator-directed open question; the Story ' +
+        'is executed by a non-interactive sub-agent that cannot answer it. ' +
+        'Record the decision, or restate the unknown as a declarative Key ' +
+        'Assumption.',
+    });
+  }
+  return findings;
+}
+
+/**
+ * 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.
+ *
+ * @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).
+ * @returns {{ findings: TextHygieneFinding[] }}
+ */
+export function evaluateTextHygiene({ draftStories = null } = {}) {
+  const stories = Array.isArray(draftStories) ? draftStories : [];
+  const findings = [];
+  for (const story of stories) {
+    const slug = typeof story?.slug === 'string' ? story.slug : '';
+    let body;
+    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 : '';
+    const spec = typeof body.spec === 'string' ? body.spec : '';
+    const bodyProse = stripCodeSpans(
+      typeof story.body === 'string' ? story.body : [goal, spec].join('\n'),
+    );
+    findings.push(
+      ...findDanglingCitations(bodyProse, slug),
+      ...findOpenQuestions(stripCodeSpans([goal, spec].join('\n')), slug),
+      ...findSlicingMass(body, slug),
+    );
+  }
+  return { findings };
+}

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

@@ -2,7 +2,7 @@
  * phases/authoring-context.js — emit-context phase.
  *
  * Builds the authoring context the host LLM (or the
- * `epic-plan-spec-author` Skill) needs to write the Tech Spec.
+ * `/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.
  */
@@ -15,13 +15,12 @@ import {
 } from '../../bdd-runner-detect.js';
 import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
 import { buildCodebaseSnapshot } from '../../codebase-snapshot.js';
-import { getLimits, getPaths, PROJECT_ROOT } from '../../config-resolver.js';
+import { getPaths, PROJECT_ROOT } from '../../config-resolver.js';
 import { scanMemoryFreshness } from '../../feedback-loop/memory-freshness.js';
 import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
 import { Logger } from '../../Logger.js';
 import { hasTicketSection } from '../../ticket-body-sections.js';
 import { ensureDocsDigest } from '../docs-digest.js';
-import { applyBudget } from '../planning-context-budget.js';
 import { collectReferences, hasNewFileCue } from '../spec-freshness.js';
 import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
@@ -60,11 +59,11 @@ function resolveMemoryDir({ github } = {}) {
  *
  * Ensures a docs digest exists at the **same** per-Epic temp path the
  * `/deliver` story sub-agents already consume
- * (`<tempRoot>/epic-<epicId>/docs-digest.md`) via the shared
+ * (`<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 or the `epic-plan-spec-author` Skill) reads the digest
+ * planner (host LLM driving the `/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
@@ -72,10 +71,10 @@ function resolveMemoryDir({ github } = {}) {
  * planning; that fallback remains a `doc-reader.js` primitive used
  * elsewhere, not part of this envelope.
  *
- * @param {{ epicId: number, settings: object, cwd: string }} args
+ * @param {{ seedIssueId: number, settings: object, cwd: string }} args
  * @returns {Promise<{ mode: 'digest', digestPath: string } | null>}
  */
-async function buildPlanningDocsContext({ epicId, settings, cwd }) {
+async function buildPlanningDocsContext({ seedIssueId, settings, cwd }) {
   const docsContextFiles = Array.isArray(settings?.docsContextFiles)
     ? settings.docsContextFiles
     : [];
@@ -83,7 +82,11 @@ async function buildPlanningDocsContext({ epicId, settings, cwd }) {
 
   const paths = getPaths({ project: { paths: settings?.paths } });
   const docsRoot = path.resolve(cwd, paths.docsRoot);
-  const relPath = path.join(paths.tempRoot, `epic-${epicId}`, 'docs-digest.md');
+  const relPath = path.join(
+    paths.tempRoot,
+    `epic-${seedIssueId}`,
+    'docs-digest.md',
+  );
   const absPath = path.resolve(cwd, relPath);
 
   const result = await ensureDocsDigest({
@@ -97,18 +100,23 @@ async function buildPlanningDocsContext({ epicId, settings, cwd }) {
 
 /**
  * Build the authoring context the host LLM (or the
- * `epic-plan-spec-author` Skill) needs to write the Tech Spec.
+ * `/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 Epic body itself stays bounded by
- * the planning-context budget (Epic #817 Story 9) — over-budget bodies
- * downgrade to a summary representation with headings + bounded excerpts.
- * Pass `{ fullContext: true }` (CLI: `--full-context`) to restore the
- * unbounded full Epic body.
+ * `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`.
  */
 export async function buildAuthoringContext(
-  epicId,
+  seedIssueId,
   provider,
   settings = {},
   opts = {},
@@ -118,26 +126,19 @@ export async function buildAuthoringContext(
   // 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.
-  const epic = opts.epic ?? (await provider.getEpic(epicId));
+  const epic = opts.epic ?? (await provider.getEpic(seedIssueId));
   if (!epic) {
-    throw new Error(`Epic #${epicId} not found.`);
+    throw new Error(`Epic #${seedIssueId} not found.`);
   }
 
-  const planningLimits = getLimits(settings).planningContext;
-  const { fullContext = false, cwd = PROJECT_ROOT } = opts;
+  const { cwd = PROJECT_ROOT } = opts;
 
   const docsContext = await buildPlanningDocsContext({
-    epicId: epic.id,
+    seedIssueId: epic.id,
     settings,
     cwd,
   });
 
-  const epicBody = applyBudget(
-    [{ path: `epic-${epic.id}.md`, content: epic.body ?? '' }],
-    planningLimits,
-    { fullContext },
-  );
-
   // Story #2094 Task #2103 — verify the project's BDD runner pending-tag
   // support so the acceptance-spec body can record either the verified tag
   // (features-first ordering) or "fallback: dependencies-first ordering"
@@ -153,7 +154,7 @@ export async function buildAuthoringContext(
     const featureRoots = resolveFeatureRoots({ cwd: PROJECT_ROOT });
     bddScenarios = scanBddScenarios({ featureRoots });
   } catch (err) {
-    Logger.warn(`[epic-plan-spec] BDD scenario scan skipped: ${err.message}`);
+    Logger.warn(`[plan-context] BDD scenario scan skipped: ${err.message}`);
   }
 
   // Story #2557 — memory-freshness pre-flight runs BEFORE the prior-feedback
@@ -220,37 +221,37 @@ export async function buildAuthoringContext(
       if (grounding.truncation) {
         const { dropped, matched, tier } = grounding.truncation;
         Logger.warn(
-          `[epic-plan-spec] codebase snapshot truncated: ${dropped} of ` +
+          `[plan-context] codebase snapshot truncated: ${dropped} of ` +
             `${matched} matched file(s) dropped from the ${tier}-tier view. ` +
-            `The spec-author context is partial. To restore full grounding, ` +
+            `The /plan authoring context is partial. To restore full ` +
+            `grounding, ` +
             `set planning.codebaseSnapshot.tier: "medium" and/or narrow ` +
             `planning.codebaseSnapshot.include in .agentrc.json.`,
         );
       }
       if (grounding.citedButAbsent.length > 0) {
         Logger.warn(
-          `[epic-plan-spec] ${grounding.citedButAbsent.length} path(s) cited ` +
-            `in the Epic body are absent from the codebase snapshot: ` +
-            `${grounding.citedButAbsent.join(', ')}. The spec author will ` +
-            `flag these as drift unless they are net-new.`,
+          `[plan-context] ${grounding.citedButAbsent.length} path(s) cited ` +
+            `in the authored Spec are absent from the codebase snapshot: ` +
+            `${grounding.citedButAbsent.join(', ')}. /plan will flag these ` +
+            `as drift unless they are net-new.`,
         );
       }
     }
   } catch (err) {
-    Logger.warn(`[epic-plan-spec] codebase snapshot skipped: ${err.message}`);
+    Logger.warn(`[plan-context] codebase snapshot skipped: ${err.message}`);
   }
 
-  // Epic #3865 — planning risk is no longer classified at emit-context
-  // time. The `epic-plan-spec-author` Skill authors the risk verdict
-  // (`risk-verdict.json`) as the fourth planning artifact, and the persist
-  // half derives the planningRisk envelope from it via deriveRiskEnvelope.
+  // 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: epicBody.mode === 'full' ? epic.body : null,
-      bodySummary: epicBody.mode === 'summary' ? epicBody.items[0] : null,
+      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

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

@@ -13,11 +13,10 @@ import { renderDecomposerSystemPrompt } from '../../templates/decomposer-prompts
 
 export function buildDecomposerSystemPrompt(
   heuristics = [],
-  { maxTickets, epicId } = {},
+  { maxTickets } = {},
 ) {
   const base = renderDecomposerSystemPrompt({
     maxTickets,
-    epicId,
   });
   const heuristicsStr =
     heuristics.length > 0

package/.agents/scripts/lib/orchestration/planning/spec-authoring-grounding.js

@@ -1,5 +1,5 @@
 /**
- * phases/spec-authoring-grounding.js — F10 spec-authoring code-grounding.
+ * planning/spec-authoring-grounding.js — F10 Spec code-grounding.
  *
  * Story #4139 (Epic #4131). `/plan` Phase 7 authors the Tech Spec
  * from the Epic body, the scraped project docs, and the