mandrel 2.55.0 → 2.57.0

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -6,20 +6,11 @@ import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
 import { isExternalDependencyRef } from './plan-persist/external-deps.js';
-import { computeSpecBudgetFindings } from './spec-budget.js';
 import {
   assertStoryBodiesParse,
   parseStoryBodyOrThrow,
 } from './story-body-gate.js';
-import {
-  CONFLICT_KINDS,
-  computeConflictFindings,
-  renderHardConflictError,
-} from './ticket-validator-conflicts.js';
-import {
-  computeSizingFindings,
-  renderHardFindingError,
-} from './ticket-validator-sizing.js';
+import { computeConflictFindings } from './ticket-validator-conflicts.js';
 
 /**
  * Regex matching code-asset paths the freshness gate cares about. The three
@@ -230,10 +221,13 @@ function makeMemoizedGitRunner(runner) {
 }
 
 /**
- * Verify that every code-asset path referenced by a Task body or AC exists at
- * `baseBranchRef`. A missing path means the planner LLM hallucinated (or the
- * path was deleted between planning and decomposition) — refuse to decompose
- * because the resulting Task would be unimplementable as written.
+ * Check that every code-asset path referenced by a Story body or AC exists at
+ * `baseBranchRef`, and report the ones that do not. A missing path usually
+ * means the planner named a file it is about to create without declaring it,
+ * or a stale reference — worth saying, not worth refusing on: Story #5312
+ * demoted this gate from a throw to the **warning list** the dry-run prints,
+ * because the paths a goal or acceptance line names are prose the deliverer
+ * reads against the real tree, never a contract the validator can hold it to.
  *
  * Only Stories are scanned — they are the implementation unit; the Epic
  * carries narrative copy, not implementation paths.
@@ -243,7 +237,7 @@ function makeMemoizedGitRunner(runner) {
  * @param {string}   opts.baseBranchRef   - Ref to probe (e.g. 'main' or 'origin/main').
  * @param {Function} [opts.gitRunner]     - Probe override (testing seam).
  * @param {string}   [opts.cwd]           - Repo cwd (forwarded to default runner).
- * @throws {ValidationError} when one or more Story references are stale.
+ * @returns {string[]} One warning line per missing reference, empty when clean.
  */
 export function validateAcFreshness({
   tickets,
@@ -286,12 +280,7 @@ export function validateAcFreshness({
       }
     }
   }
-  if (misses.length === 0) return;
-  const lines = misses.map((m) => renderMissLine(m)).join('\n');
-  throw new ValidationError(
-    `Cross-Validation Failed: ${misses.length} Story reference(s) name files that do not exist at ${baseBranchRef}:\n${lines}\n\nEither declare the path in body.changes (signals net-new) or correct the reference.`,
-    { misses, baseBranchRef },
-  );
+  return misses.map((m) => renderMissLine(m, baseBranchRef));
 }
 
 /**
@@ -406,40 +395,35 @@ export function validateAcceptanceSubjectPrefix({ tickets }) {
 }
 
 /**
- * Render one missing-path line with a remediation hint pointing at the
- * task's `body.changes`. For `tests/**` paths we suggest the explicit
+ * Render one missing-path warning with a remediation hint pointing at the
+ * Story's `changes[]`. For `tests/**` paths we suggest the explicit
  * "add the test file" verb; for everything else we emit a generic hint
  * since the planner knows whether the path is net-new or a typo.
  */
-function renderMissLine({ slug, path }) {
+function renderMissLine({ slug, path }, baseBranchRef) {
   const verb = path.startsWith('tests/') ? 'add test file' : 'create';
-  return `  - "${slug}" → ${path}\n      hint: if net-new, add '${path}: ${verb}' to body.changes; otherwise fix the typo or stale reference against current main.`;
+  return `Story "${slug}" references ${path}, which does not exist at ${baseBranchRef} — if net-new, declare {"path":"${path}","assumption":"creates"} in changes[] (${verb}); otherwise fix the typo or stale reference.`;
 }
 
 /**
  * Validates the generated ticket hierarchy and handles lifting cross-story dependencies.
  *
- * The returned tickets array carries two extra non-array properties:
- *   - `findings` — structured sizing findings (hard + soft) keyed by the
- *     three-layer sizing model. The bounded re-decomposition loop in
- *     `/mandrel-plan` reads `findings.filter(f => f.severity === 'hard')` to decide
- *     whether to re-prompt.
- *   - `errors`   — human-readable strings, one per hard finding. Non-empty
- *     `errors[]` is the AC-visible "block normalization" signal; the legacy
- *     hierarchy/cycle/freshness checks continue to throw, so callers that
- *     only inspect the array shape are unaffected when no sizing
- *     violations occur.
+ * The returned tickets array carries extra non-array properties:
+ *   - `findings` — the advisory cross-Story conflict findings.
+ *   - `errors`   — human-readable strings, one per hard refusal: a `deletes`
+ *     naming a path absent at base (prefixed `File assumption mismatch:`).
+ *     The hierarchy/cycle/parse checks continue to throw.
+ *   - `warnings` — the demoted footprint probes (Story #5312): a `creates`
+ *     or `refactors-existing` mismatch, a goal/acceptance/verify path absent
+ *     at base. Listed by the dry-run; the persist proceeds.
+ *   - `normalizations` — the `refactors-existing`→`creates` rewrites applied.
  *
  * @param {object[]}                   tickets             - Array of ticket objects parsed from LLM output.
  * @param {object}                     [opts]
- * @param {string}                     [opts.baseBranchRef] - When set, runs `validateAcFreshness` against this ref.
+ * @param {string}                     [opts.baseBranchRef] - When set, runs the base-branch probes against this ref.
  * @param {Function}                   [opts.gitRunner]     - Optional git probe override.
- * @param {string}                     [opts.cwd]           - Repo cwd (forwarded to the freshness gate).
- * @param {object}                     [opts.modelCapacity] - Programmatic override of `DEFAULT_MODEL_CAPACITY` (tests only — not read from `.agentrc.json`).
- * @param {object}                     [opts.conflictPolicy] - Severity controls for cross-Story conflict findings.
- * @param {boolean}                    [opts.conflictPolicy.failOnSharedEditors=false]          - Upgrade `shared-editor` findings to `hard`.
- * @param {boolean}                    [opts.conflictPolicy.requireExplicitCrossStoryDeps=false] - Upgrade `implicit-cross-story-dep` findings to `hard`.
- * @returns {object[] & { findings: object[], errors: string[] }} Validated tickets with normalized dependencies and attached sizing + conflict findings.
+ * @param {string}                     [opts.cwd]           - Repo cwd (forwarded to the probes).
+ * @returns {object[] & { findings: object[], errors: string[], warnings: string[], normalizations: object[] }}
  */
 /**
  * Internal helpers extracted from `validateAndNormalizeTickets` so each
@@ -603,13 +587,12 @@ function assertAcyclic(slugAdjacency) {
 
 function attachFindingsAndErrors(
   tickets,
-  findings,
-  errors,
-  normalizations = [],
+  { findings, errors, warnings, normalizations },
 ) {
   for (const [key, value] of [
     ['findings', findings],
     ['errors', errors],
+    ['warnings', warnings],
     // Story #5265: the auto-normalizations the assumption gate applied. They
     // used to end at a `Logger.warn` and die with the process, so persist's
     // emitted result reported a plan whose declarations it had silently
@@ -660,25 +643,26 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
     ? makeMemoizedGitRunner(opts.gitRunner ?? defaultGitRunner)
     : null;
 
-  // Refuse to decompose when any Task body or AC names a code-asset path
-  // missing from the Epic's base branch tree. Skipped when the caller
-  // omits `baseBranchRef` so legacy unit tests keep their existing
-  // semantics; production call-sites always pass it.
+  const warnings = [];
+  // Story #5312: a goal / acceptance / verify path absent at base is a
+  // warning the dry-run lists, not a refusal. Skipped when the caller omits
+  // `baseBranchRef` so unit tests keep their semantics; production
+  // call-sites always pass it.
   if (opts.baseBranchRef) {
-    validateAcFreshness({
-      tickets,
-      baseBranchRef: opts.baseBranchRef,
-      gitRunner: sharedGitRunner,
-      cwd: opts.cwd,
-    });
+    warnings.push(
+      ...validateAcFreshness({
+        tickets,
+        baseBranchRef: opts.baseBranchRef,
+        gitRunner: sharedGitRunner,
+        cwd: opts.cwd,
+      }),
+    );
   }
 
   // Story #2636 — Phase 8 path-assumption gate. Cross-check every Story's
   // declared `{ path, assumption }` against the actual state of the base
-  // branch and batch the mismatches per-Story into the validator's errors
-  // envelope. Skipped when the caller omits `baseBranchRef` so legacy
-  // unit tests keep their semantics; production call-sites always pass
-  // it.
+  // branch. A `deletes` on an absent path batches into the validator's
+  // errors envelope; every other mismatch is a warning (Story #5312).
   let assumptionErrors = [];
   let assumptionNormalizations = [];
   if (opts.baseBranchRef) {
@@ -688,71 +672,23 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
       gitRunner: sharedGitRunner,
       cwd: opts.cwd,
     });
-    // Auto-normalizations (#4496 fix 5) get their own prefix so the logged
-    // warning is self-explanatory; everything else on the warnings channel
-    // is a legacy-shape deprecation nudge.
-    const normalizationWarnings = new Set(
-      (assumptionReport.normalizations ?? []).map((n) => n.path),
-    );
-    for (const warning of assumptionReport.warnings) {
-      const isNormalization = warning.includes('auto-normalized to "creates"');
-      Logger.warn(
-        `[ticket-validator] ${isNormalization ? 'assumption-normalized' : 'assumption-deprecation'}: ${warning}`,
-      );
-    }
-    if (normalizationWarnings.size > 0) {
-      Logger.warn(
-        `[ticket-validator] ${normalizationWarnings.size} refactors-existing ` +
-          'declaration(s) on base-untracked path(s) auto-normalized to ' +
-          '"creates" — the gate proceeds; update the plan declarations at ' +
-          'the next amend.',
-      );
-    }
+    warnings.push(...assumptionReport.warnings);
     assumptionErrors = assumptionReport.errors;
     assumptionNormalizations = assumptionReport.normalizations ?? [];
   }
 
-  const sizingFindings = computeSizingFindings({
-    stories,
-    capacity: opts.modelCapacity,
-  });
   // Cross-Story path-conflict pass observes the story-level depends_on
-  // graph. Findings are appended to the same `findings` array consumed by
-  // the decompose-loop's hard-finding gate; severity is controlled by
-  // `opts.conflictPolicy`.
-  const conflictFindings = computeConflictFindings({
-    stories,
-    policy: opts.conflictPolicy,
+  // graph. Every finding is advisory; the persist surfaces them and the
+  // plan summary renders the shared-editor class beside the wave table.
+  const findings = computeConflictFindings({ stories });
+  const errors = assumptionErrors.map((e) => `File assumption mismatch: ${e}`);
+
+  attachFindingsAndErrors(tickets, {
+    findings,
+    errors,
+    warnings,
+    normalizations: assumptionNormalizations,
   });
-  // Advisory `## Spec` word-budget pass (Story #4723) — soft findings only,
-  // never promoted to `errors[]`, so an over-budget Spec cannot fail the
-  // persist. Runs after `assertStoryBodiesParse`, so string bodies parse.
-  // This pass computes but does not report: the sole production caller always
-  // runs the persist soft-finding surface, which reports every soft kind
-  // uniformly. Warning here too made `spec-word-budget` the only kind logged
-  // twice per run (Story #4907).
-  const specBudgetFindings = computeSpecBudgetFindings({ stories });
-  const findings = [
-    ...sizingFindings,
-    ...conflictFindings,
-    ...specBudgetFindings,
-  ];
-  const errors = findings
-    .filter((f) => f.severity === 'hard')
-    .map((f) =>
-      CONFLICT_KINDS.has(f.kind)
-        ? renderHardConflictError(f)
-        : renderHardFindingError(f),
-    );
-  // Append per-Story path-assumption mismatches (Story #2636) to the
-  // hard-error list. The decompose loop already gates on
-  // `errors.length > 0` to trigger a re-prompt, so the new check
-  // participates in the same loop without bespoke wiring.
-  for (const e of assumptionErrors) {
-    errors.push(`File assumption mismatch: ${e}`);
-  }
-
-  attachFindingsAndErrors(tickets, findings, errors, assumptionNormalizations);
   return tickets;
 }
 

package/.agents/scripts/lib/orchestration/verify-credit.js

@@ -12,8 +12,10 @@
  * the entry as credited instead of telling the caller to spawn it.
  *
  * It only ever *reads*. Nothing here writes a capture stamp or an evidence
- * record — an entry that is not covered by a fresh stamp is reported
- * `spawn: true` and runs for real, so the credit can never manufacture a pass.
+ * record — an entry that is not covered by a fresh stamp or a credited
+ * `test` evidence record (Story #5313: a green bare `npm test` deposits one)
+ * is reported `spawn: true` and runs for real, so the credit can never
+ * manufacture a pass.
  *
  * @see .agents/scripts/lib/coverage-capture.js (`isCoverageFresh`)
  * @see .agents/scripts/lib/validation-evidence.js (`shouldSkip`)
@@ -23,7 +25,11 @@ import { getQuality, resolveConfig } from '../config-resolver.js';
 import { isCoverageFresh } from '../coverage-capture.js';
 import { gitSpawn } from '../git-utils.js';
 import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
-import { hashCommandConfig, shouldSkip } from '../validation-evidence.js';
+import {
+  hashCommandConfig,
+  shouldSkip,
+  treeFingerprint,
+} from '../validation-evidence.js';
 
 /**
  * The shape a `verify[]` array is supposed to have, stated once so the
@@ -169,6 +175,7 @@ export function resolveVerifyCredit(
     isCoverageFreshImpl = isCoverageFresh,
     shouldSkipImpl = shouldSkip,
     hashCommandConfigImpl = hashCommandConfig,
+    treeFingerprintImpl = treeFingerprint,
     gitSpawnFn = gitSpawn,
   } = deps;
 
@@ -189,43 +196,81 @@ export function resolveVerifyCredit(
       ? 'capture'
       : 'evidence';
 
+  let stampReason = null;
   if (mode === 'capture') {
     const freshness = isCoverageFreshImpl({
       coveragePath: crap.coveragePath,
       targetDirs: crap.targetDirs,
       cwd: worktree,
     });
-    const fresh = freshness?.fresh === true;
-    return {
-      ...scoped,
-      mode,
-      credited: fresh,
-      spawn: !fresh,
-      reason: fresh ? 'capture-stamp-fresh' : (freshness?.reason ?? 'unknown'),
-    };
+    if (freshness?.fresh === true) {
+      return {
+        ...scoped,
+        mode,
+        credited: true,
+        spawn: false,
+        reason: 'capture-stamp-fresh',
+      };
+    }
+    stampReason = freshness?.reason ?? 'unknown';
   }
 
+  // Story #5313 — a green bare `npm test` deposits the `test` evidence record
+  // close reads, so a stale (or absent) capture stamp is not the last word:
+  // the evidence keyspace is consulted in both modes before spawning. When it
+  // credits nothing either, capture mode reports the stamp's own reason.
+  const verdict = readTestEvidence({
+    storyId,
+    worktree,
+    cwd,
+    gitSpawnFn,
+    shouldSkipImpl,
+    hashCommandConfigImpl,
+    treeFingerprintImpl,
+  });
+  const credited = verdict.skip === true;
+  return {
+    ...scoped,
+    mode,
+    credited,
+    spawn: !credited,
+    reason: credited ? verdict.reason : (stampReason ?? verdict.reason),
+  };
+}
+
+/**
+ * Consult the `test` evidence record for the worktree's HEAD — the record a
+ * green bare `npm test` deposits (Story #5313) and `evidence-gate.js` wrote
+ * before it. Total: an unreadable HEAD is `no-head`, never a credit.
+ *
+ * @param {{ storyId: number|string, worktree: string, cwd: string, gitSpawnFn: Function, shouldSkipImpl: Function, hashCommandConfigImpl: Function, treeFingerprintImpl: Function }} args
+ * @returns {{ skip: boolean, reason: string }}
+ */
+function readTestEvidence({
+  storyId,
+  worktree,
+  cwd,
+  gitSpawnFn,
+  shouldSkipImpl,
+  hashCommandConfigImpl,
+  treeFingerprintImpl,
+}) {
   const headSha = readHeadSha(worktree, gitSpawnFn);
-  if (!headSha) {
-    return { ...scoped, mode, credited: false, spawn: true, reason: 'no-head' };
-  }
-  const [cmd, ...args] = command.split(/\s+/).filter(Boolean);
-  const verdict = shouldSkipImpl(
+  if (!headSha) return { skip: false, reason: 'no-head' };
+  return shouldSkipImpl(
     {
       storyId,
       gateName: 'test',
       currentSha: headSha,
-      configHash: hashCommandConfigImpl({ cmd, args, cwd: worktree }),
+      configHash: hashCommandConfigImpl({
+        cmd: 'npm',
+        args: ['test'],
+        cwd: worktree,
+      }),
+      inputFingerprint: treeFingerprintImpl(worktree, gitSpawnFn),
     },
     { cwd, standalone: true },
   );
-  return {
-    ...scoped,
-    mode,
-    credited: verdict.skip === true,
-    spawn: verdict.skip !== true,
-    reason: verdict.reason,
-  };
 }
 
 /**

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

@@ -4,7 +4,7 @@
  * inference a failing dry-run surfaces (Story #4684).
  *
  * The problem this closes: deterministic format rules (structured `## Changes`
- * bullet shape, verify-tier suffixes) used to be discovered only as persist
+ * bullet shape, non-empty sections) used to be discovered only as persist
  * dry-run failures — every miss cost a full re-author round-trip at
  * resident-context prices. This module is the single home for two remedies:
  *
@@ -13,11 +13,16 @@
  *      them into the story-author system prompt so the first draft is
  *      lint-clean by construction; a test enumerates the registry against the
  *      rendered prompt (Story #4684 AC-1).
- *   2. `suggestPathEntryFix` / `suggestVerifyFix` — the mechanical rewrites.
- *      `story-body.js` (`parsePathEntry`) and `task-body-validator.js`
- *      (`collectChangesErrors` / `collectVerifyErrors`) call them so a failing
- *      lint emits the corrected form ready to paste rather than a bare reject
- *      (AC-2).
+ *   2. `suggestPathEntryFix` — the mechanical rewrite. `story-body.js`
+ *      (`parsePathEntry`) and `task-body-validator.js`
+ *      (`collectChangesErrors`) call it so a failing lint emits the corrected
+ *      form ready to paste rather than a bare reject (AC-2), and the persist
+ *      dry-run applies the same salvage for real (Story #5312,
+ *      `plan-persist/changes-repair.js`).
+ *
+ * Story #5312 deleted the `verify-tier-suffix` / `verify-manual-reason` lints
+ * with the tier suffix itself: a `verify[]` entry is any command, and the
+ * `manual:<reason>` escape is gone with the rule it escaped.
  *
  * Import hygiene: this module imports only the cycle-free
  * `file-assumption-enum.js` leaf. It must NOT import `story-body.js` or
@@ -27,20 +32,6 @@
 
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
 
-/**
- * Canonical testing-tier vocabulary an inferred verify suffix may name. Kept in
- * sync with `task-body-validator.js`'s `VERIFY_TIER_VALUES` by a test rather
- * than an import (importing that module here would create a cycle).
- *
- * @type {readonly ['unit','contract','e2e','validate']}
- */
-const INFERABLE_VERIFY_TIERS = Object.freeze([
-  'unit',
-  'contract',
-  'e2e',
-  'validate',
-]);
-
 /**
  * The default assumption a mechanical `## Changes` auto-fix proposes. Most
  * bare-path bullets an author drops are in-place edits, so `refactors-existing`
@@ -54,48 +45,6 @@ const DEFAULT_SUGGESTED_ASSUMPTION = 'refactors-existing';
 // a false positive only produces an unhelpful (still-valid) fix-it string.
 const PATH_LIKE_RE = /[\w@*-]*[/.][\w@./*-]+/;
 
-/**
- * Infer the testing tier a bare `verify[]` command implies, when it is
- * unambiguous. Returns `null` when no confident inference is possible (the
- * author must then choose the tier themselves — the lint still fires, just
- * without a fix-it).
- *
- * @param {unknown} command
- * @returns {'unit'|'contract'|'e2e'|'validate'|null}
- */
-function inferVerifyTier(command) {
-  if (typeof command !== 'string') return null;
-  const c = command.toLowerCase();
-  if (/\bvalidate\b/.test(c)) return 'validate';
-  if (/playwright|\.spec\.|\be2e\b/.test(c)) return 'e2e';
-  if (/\.test\.|node --test|node:test|\bvitest\b|\bjest\b/.test(c)) {
-    return 'unit';
-  }
-  if (/\bcontract\b/.test(c)) return 'contract';
-  return null;
-}
-
-/**
- * Propose the corrected form of a `verify[]` entry that is missing its tier
- * suffix, when the tier is inferable from the command. Returns `null` when the
- * entry is a `manual:` escape, is empty, or the tier cannot be inferred.
- *
- * @param {unknown} entry
- * @returns {string|null} e.g. `"npm run validate (validate)"`.
- */
-export function suggestVerifyFix(entry) {
-  if (typeof entry !== 'string') return null;
-  const trimmed = entry.trim();
-  if (trimmed === '' || trimmed.startsWith('manual:')) return null;
-  const tier = inferVerifyTier(trimmed);
-  if (tier === null) return null;
-  // Drop any trailing (…) — a wrong/partial tier suffix — before appending the
-  // inferred one, so `npm test (smoke)` becomes `npm test (unit)` not a double.
-  const base = trimmed.replace(/\s*\([^)]*\)\s*$/, '').trim();
-  if (base === '') return null;
-  return `${base} (${tier})`;
-}
-
 /**
  * Propose the canonical `{ path, assumption }` object form for a `## Changes` /
  * `## References` bullet an author wrote as a bare path string (or a humanized
@@ -140,9 +89,8 @@ export function suggestPathEntryFix(raw) {
 /**
  * The enumerated deterministic lints that can reject an authored Story body at
  * persist time. Each carries a concrete example so the story-author prompt can
- * state the requirement example-first (Story #4684 AC-1). The two `autoFixable`
- * lints are the mechanical rewrites whose dry-run failure carries the corrected
- * form (AC-2).
+ * state the requirement example-first (Story #4684 AC-1). The one `autoFixable`
+ * lint is the mechanical rewrite the dry-run applies (Story #5312).
  *
  * @type {ReadonlyArray<BodyFormatLint>}
  */
@@ -179,29 +127,11 @@ export const BODY_FORMAT_LINTS = Object.freeze([
     goodExample: '- {"path": "src/app.js", "assumption": "creates"}',
     autoFixable: false,
   },
-  {
-    id: 'verify-tier-suffix',
-    summary:
-      'Every `verify[]` entry MUST end with a tier in parentheses — one of ' +
-      `(${INFERABLE_VERIFY_TIERS.join(' | ')}) — or be a \`manual:<reason>\` escape.`,
-    badExample: 'npm test -- src/app.test.js',
-    goodExample: 'npm test -- src/app.test.js (unit)',
-    autoFixable: true,
-  },
   {
     id: 'verify-non-empty',
-    summary:
-      'A Story MUST list at least one `verify[]` entry (use `manual:<reason>` only when truly unverifiable in isolation).',
+    summary: 'A Story MUST list at least one `verify[]` entry.',
     badExample: '"verify": []',
-    goodExample: '"verify": ["npm run validate (validate)"]',
-    autoFixable: false,
-  },
-  {
-    id: 'verify-manual-reason',
-    summary:
-      'A `manual:` verify entry MUST carry a reason after the colon; a bare `manual:` is rejected.',
-    badExample: 'manual:',
-    goodExample: 'manual: copy-only edit an auditor eyeballs',
+    goodExample: '"verify": ["npm run validate"]',
     autoFixable: false,
   },
   {