mandrel 1.65.0 → 1.67.0

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -12,6 +12,16 @@
  * Tests inject a `spawnImpl` (or shape-compatible `execImpl`) to exercise
  * the gh-exec surface deterministically; production code defaults to
  * `child_process.spawn`.
+ *
+ * Story #4135 (Epic #4131, F11) — the envelope additionally carries a
+ * `recurringDefectClasses[]` array derived from the `friction::<class>`
+ * labels the retro routed-proposals composer stamps onto the meta issues it
+ * proposes. That closes the retro→planner loop: a recurring defect class
+ * caught by review/deliver is filed as a `meta::*` + `friction::<class>`
+ * issue, and the next `/plan` Phase 0 surfaces the class (with a recurrence
+ * count across the open feedback issues) to the decompose-author guidance so
+ * the planning floor ratchets up. The derivation is no-op-safe: issues with
+ * no `friction::*` label contribute nothing and the array is empty.
  */
 
 import { META_LABELS } from '../label-constants.js';
@@ -19,6 +29,66 @@ import { runChild } from './graduator-core.js';
 
 const DEFAULT_LIMIT = 50;
 
+/** Prefix stamped on routed-proposal issue labels by the retro composer. */
+const FRICTION_LABEL_PREFIX = 'friction::';
+
+/**
+ * Pure: derive recurring-defect-class signals from a list of normalized
+ * issues by counting `friction::<class>` labels across them (Story #4135).
+ *
+ * Each fetched meta issue may carry one `friction::<class>` label (stamped by
+ * the retro routed-proposals composer when it proposed the issue). A class
+ * that appears across **multiple** open feedback issues is recurring across
+ * Epics — exactly the signal F11 surfaces to the planner. The count is the
+ * number of distinct open issues carrying the class; the `issues[]` array
+ * lists their numbers so the planner can cross-reference.
+ *
+ * Determinism: classes are sorted by descending recurrence count, ties
+ * broken by class name ASC, so a given input always yields a stable order.
+ *
+ * No-op-safe: issues without a `friction::*` label contribute nothing; an
+ * empty / non-array input yields `[]`.
+ *
+ * @param {Array<{ number: number, labels?: string[] }>} issues
+ * @returns {Array<{ class: string, count: number, issues: number[] }>}
+ */
+export function extractRecurringDefectClasses(issues) {
+  if (!Array.isArray(issues)) return [];
+  /** @type {Map<string, Set<number>>} */
+  const byClass = new Map();
+  for (const issue of issues) {
+    if (!issue || typeof issue !== 'object') continue;
+    const number = typeof issue.number === 'number' ? issue.number : null;
+    const labels = Array.isArray(issue.labels) ? issue.labels : [];
+    for (const label of labels) {
+      if (
+        typeof label !== 'string' ||
+        !label.startsWith(FRICTION_LABEL_PREFIX)
+      ) {
+        continue;
+      }
+      const cls = label.slice(FRICTION_LABEL_PREFIX.length).trim();
+      if (cls.length === 0) continue;
+      let set = byClass.get(cls);
+      if (!set) {
+        set = new Set();
+        byClass.set(cls, set);
+      }
+      if (number !== null) set.add(number);
+    }
+  }
+  const out = [];
+  for (const [cls, set] of byClass) {
+    out.push({
+      class: cls,
+      count: set.size,
+      issues: [...set].sort((a, b) => a - b),
+    });
+  }
+  out.sort((a, b) => b.count - a.count || a.class.localeCompare(b.class));
+  return out;
+}
+
 /**
  * Spawn the given gh CLI with the supplied args and resolve to
  * `{ code, stdout, stderr, spawnError }`. Delegates to the shared
@@ -157,6 +227,7 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
  * @returns {Promise<{
  *   frameworkGaps: object[],
  *   consumerImprovements: object[],
+ *   recurringDefectClasses: Array<{ class: string, count: number, issues: number[] }>,
  *   fetchedAt: string,
  *   errors: string[],
  * }>}
@@ -180,6 +251,7 @@ export async function fetchPriorFeedback({
   const envelope = {
     frameworkGaps: [],
     consumerImprovements: [],
+    recurringDefectClasses: [],
     fetchedAt: new Date().toISOString(),
     errors,
   };
@@ -223,6 +295,16 @@ export async function fetchPriorFeedback({
     envelope.consumerImprovements.push(issue);
   }
 
+  // Story #4135 (Epic #4131, F11) — close the retro→planner loop: derive the
+  // recurring defect classes from the `friction::<class>` labels carried by
+  // the deduped feedback issues, so the next /plan Phase 0 surfaces them to
+  // the decompose-author guidance. No-op-safe when no issue carries a
+  // `friction::*` label (empty array, no behavioural change).
+  envelope.recurringDefectClasses = extractRecurringDefectClasses([
+    ...envelope.frameworkGaps,
+    ...envelope.consumerImprovements,
+  ]);
+
   return envelope;
 }
 

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/authoring-context.js

@@ -21,11 +21,13 @@ import { fetchPriorFeedback } from '../../../feedback-loop/prior-feedback-fetche
 import { Logger } from '../../../Logger.js';
 import { buildDocsContext } from '../../doc-reader.js';
 import { applyBudget } from '../../planning-context-budget.js';
+import { collectReferences, hasNewFileCue } from '../../spec-freshness.js';
 import {
   ACCEPTANCE_SPEC_SYSTEM_PROMPT,
   PRD_SYSTEM_PROMPT,
   TECH_SPEC_SYSTEM_PROMPT,
 } from './prompts.js';
+import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
  * Resolve the per-project memory directory used by the memory-freshness
@@ -146,24 +148,47 @@ export async function buildAuthoringContext(
       recentCommitWindow:
         settings?.planning?.codebaseSnapshot?.recentCommitWindow,
     });
-    // Story #3959 — when the skinny-tier cap drops files, the degradation
-    // used to be silent (only `truncated: true` on the envelope). Surface
-    // an operator-visible warning naming the dropped count and the two
-    // remedies so the spec author knows the snapshot is partial and can
-    // either opt into the richer `medium` tier or narrow `include`.
-    if (codebaseSnapshot?.truncated) {
-      const dropped = Math.max(
-        0,
-        (codebaseSnapshot.fileCount ?? 0) -
-          (codebaseSnapshot.files?.length ?? 0),
-      );
-      Logger.warn(
-        `[epic-plan-spec] codebase snapshot truncated: ${dropped} of ` +
-          `${codebaseSnapshot.fileCount} matched file(s) dropped from the ` +
-          `skinny-tier view. The spec-author context is partial. To restore ` +
-          `full grounding, set planning.codebaseSnapshot.tier: "medium" ` +
-          `and/or narrow planning.codebaseSnapshot.include in .agentrc.json.`,
-      );
+    // Story #4139 (F10) — ground the spec author in the files it will cite.
+    // Two signals are attached to the snapshot envelope so the author (which
+    // consumes the JSON, not stderr) cannot miss them:
+    //   1. `grounding.truncation` — the structured, in-envelope form of the
+    //      Story #3959 dropped-file warning. The skinny-tier cap used to drop
+    //      the majority of matched files with only a stderr `Logger.warn` and
+    //      a bare `truncated: true` flag; the author never learned the
+    //      snapshot was partial (a real run dropped "377 of 627 files").
+    //   2. `grounding.citedButAbsent` — path-shaped references in the Epic
+    //      body (the prose the author grounds *from*) that are absent from
+    //      the snapshot's file set and not phrased as net-new, so cited-but-
+    //      absent surfaces are visible *during* authoring rather than only
+    //      after the post-author freshness gate (Story #2635).
+    // The grounding consults only the snapshot's file set and the Epic body —
+    // no new filesystem or git probes — so the context stays bounded for cost.
+    if (codebaseSnapshot) {
+      const grounding = buildAuthoringGrounding({
+        snapshot: codebaseSnapshot,
+        prose: epic.body ?? '',
+        collectReferences,
+        hasNewFileCue,
+      });
+      codebaseSnapshot.grounding = grounding;
+      if (grounding.truncation) {
+        const { dropped, matched, tier } = grounding.truncation;
+        Logger.warn(
+          `[epic-plan-spec] 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, ` +
+            `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.`,
+        );
+      }
     }
   } catch (err) {
     Logger.warn(`[epic-plan-spec] codebase snapshot skipped: ${err.message}`);

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/spec-authoring-grounding.js

@@ -0,0 +1,147 @@
+/**
+ * phases/spec-authoring-grounding.js — F10 spec-authoring code-grounding.
+ *
+ * Story #4139 (Epic #4131). `/plan` Phase 7 authors the PRD + Tech Spec
+ * from the Epic body, the scraped project docs, and the
+ * `codebaseSnapshot` structural view of the consumer repo. Two failure
+ * modes made that grounding silently partial:
+ *
+ *   1. The skinny-tier snapshot caps its file list at `MAX_FILES_SKINNY`
+ *      and sets `truncated: true` — but the only operator-visible signal
+ *      was a stderr `Logger.warn` (Story #3959). The spec author consumes
+ *      the JSON envelope, not stderr, so it never learned the snapshot
+ *      was partial. A run that dropped "377 of 627 files" looked complete
+ *      to the author.
+ *
+ *   2. When the Epic body cites a code path that is **absent** from the
+ *      snapshot's file set, nothing surfaced the gap *during* authoring.
+ *      The post-author spec-freshness gate (Story #2635) catches stale
+ *      citations only after the Tech Spec is written — one phase too late
+ *      to ground the author's choices.
+ *
+ * `buildAuthoringGrounding` derives a small, bounded `grounding` block that
+ * is attached to the `codebaseSnapshot` envelope so the author (and the
+ * operator inspecting the run) see both signals before the spec is written:
+ *
+ *   - `truncation` — non-null when the snapshot dropped files. Carries the
+ *     dropped count, the matched/shown totals, and the two remedies. This
+ *     is the structured, in-envelope form of the Story #3959 stderr warning.
+ *   - `citedButAbsent` — path-shaped references pulled from the authoring
+ *     prose (the Epic body) that are **not** present in the snapshot's file
+ *     set and are not phrased as net-new. Bounded to `MAX_CITED_ABSENT`
+ *     entries so a pathological Epic body cannot blow the envelope budget.
+ *
+ * The grounding is targeted (the prose the author is grounding *from* and
+ * the files the snapshot already carries), not a whole-repo dump — the
+ * snapshot file set is the only source consulted, so this adds no new
+ * filesystem or git probes.
+ */
+
+/**
+ * Hard cap on the `citedButAbsent` list so an Epic body that mentions a
+ * very large number of paths cannot inflate the authoring envelope. The
+ * cap is generous relative to a realistic Epic citation count; when it is
+ * hit, `citedButAbsentTruncated: true` flags the elision so the signal is
+ * not silently dropped (the very failure mode this Story fixes).
+ */
+export const MAX_CITED_ABSENT = 40;
+
+/**
+ * Build the operator-visible truncation signal from a snapshot envelope.
+ * Returns `null` when the snapshot is absent or was not truncated.
+ *
+ * @param {object|null} snapshot - The `codebaseSnapshot` envelope.
+ * @returns {{ dropped: number, matched: number, shown: number, tier: string, remedies: string[] } | null}
+ */
+export function buildTruncationSignal(snapshot) {
+  if (!snapshot || snapshot.truncated !== true) return null;
+  const matched = Number.isInteger(snapshot.fileCount) ? snapshot.fileCount : 0;
+  const shown = Array.isArray(snapshot.files) ? snapshot.files.length : 0;
+  const dropped = Math.max(0, matched - shown);
+  return {
+    dropped,
+    matched,
+    shown,
+    tier: typeof snapshot.tier === 'string' ? snapshot.tier : 'skinny',
+    remedies: [
+      'Set planning.codebaseSnapshot.tier: "medium" in .agentrc.json to restore full grounding.',
+      'Narrow planning.codebaseSnapshot.include in .agentrc.json so the cited surfaces survive the cap.',
+    ],
+  };
+}
+
+/**
+ * Surface path-shaped references from the authoring prose that are absent
+ * from the snapshot's file set. Reuses the spec-freshness path extractor so
+ * the citation shapes recognised here match the post-author freshness gate
+ * exactly — a path the author cites in prose is detected the same way before
+ * and after authoring.
+ *
+ * A reference is reported only when it is **not** present in `snapshotFiles`
+ * **and** the surrounding prose does not phrase it as net-new (the same
+ * cue heuristic the freshness gate uses to demote intentional new-file
+ * mentions). Results are deduped by path, sorted, and bounded to
+ * `MAX_CITED_ABSENT`.
+ *
+ * @param {string} prose - The authoring prose (typically the Epic body).
+ * @param {string[]} snapshotFiles - The snapshot's `files` array.
+ * @param {object} deps
+ * @param {Function} deps.collectReferences - (body) => Array<{ path, index, matchLength }>.
+ * @param {Function} deps.hasNewFileCue - (body, index, matchLength) => boolean.
+ * @returns {{ paths: string[], truncated: boolean }}
+ */
+export function findCitedButAbsent(prose, snapshotFiles, deps) {
+  const { collectReferences, hasNewFileCue } = deps;
+  if (typeof prose !== 'string' || prose.length === 0) {
+    return { paths: [], truncated: false };
+  }
+  const present = new Set(
+    (Array.isArray(snapshotFiles) ? snapshotFiles : []).map((f) =>
+      String(f).replace(/\\/g, '/'),
+    ),
+  );
+  const absent = new Set();
+  for (const { path, index, matchLength } of collectReferences(prose)) {
+    const normalised = path.replace(/\\/g, '/');
+    if (present.has(normalised)) continue;
+    if (hasNewFileCue(prose, index, matchLength)) continue;
+    absent.add(normalised);
+  }
+  const sorted = [...absent].sort();
+  return {
+    paths: sorted.slice(0, MAX_CITED_ABSENT),
+    truncated: sorted.length > MAX_CITED_ABSENT,
+  };
+}
+
+/**
+ * Build the full `grounding` block attached to the `codebaseSnapshot`
+ * envelope. Pure with respect to its inputs (no filesystem or git probes):
+ * the snapshot file set is the sole grounding source, keeping the context
+ * bounded for cost.
+ *
+ * @param {object} opts
+ * @param {object|null} opts.snapshot - The `codebaseSnapshot` envelope.
+ * @param {string} opts.prose - The authoring prose (Epic body) to scan.
+ * @param {Function} opts.collectReferences - spec-freshness path extractor.
+ * @param {Function} opts.hasNewFileCue - spec-freshness net-new cue check.
+ * @returns {{ truncation: object|null, citedButAbsent: string[], citedButAbsentTruncated: boolean }}
+ */
+export function buildAuthoringGrounding({
+  snapshot,
+  prose,
+  collectReferences,
+  hasNewFileCue,
+}) {
+  const truncation = buildTruncationSignal(snapshot);
+  const { paths, truncated } = findCitedButAbsent(
+    prose,
+    snapshot?.files ?? [],
+    { collectReferences, hasNewFileCue },
+  );
+  return {
+    truncation,
+    citedButAbsent: paths,
+    citedButAbsentTruncated: truncated,
+  };
+}

package/.agents/scripts/lib/orchestration/retro/phases/compose-body.js

@@ -26,6 +26,69 @@ export function normalizeInterventionCount(value) {
   return Math.trunc(value);
 }
 
+/**
+ * Pure: derive the recurring-defect-class signal from the routed-proposal
+ * sections (Story #4135 / Epic #4131, F11).
+ *
+ * The routed-proposals composer (`retro-proposals.js`) already split the
+ * Epic's source-tagged friction into `framework` / `consumer` actionable
+ * items — a category lands there only when it recurred ≥2 times across the
+ * Epic OR was force-flagged by an unresolved `agent::blocked` event. Those
+ * are exactly the **recurring classes** of review/deliver-caught issues F11
+ * tracks, so we lift them verbatim rather than re-deriving a parallel
+ * threshold. Each entry carries the `friction::<category>` label the
+ * composer stamps onto its `gh issue create` command — that label is the
+ * join key the `/plan` Phase 0 prior-feedback fetcher reads back to surface
+ * recurring classes to the planner.
+ *
+ * Determinism: the two actionable arrays are already sorted by `category`
+ * ASC by the composer; we concatenate framework-then-consumer and re-sort by
+ * `category` so the merged signal is stable regardless of which source
+ * contributed a class.
+ *
+ * No-op-safe: a null / non-object / shapeless `routedProposals` (or one with
+ * empty actionable arrays) yields `[]` — the common clean-sprint case.
+ *
+ * @param {{ framework?: object[], consumer?: object[] } | null | undefined} routedProposals
+ * @returns {Array<{ category: string, occurrences: number, source: 'framework'|'consumer', label: string }>}
+ */
+export function deriveDefectClasses(routedProposals) {
+  if (
+    !routedProposals ||
+    typeof routedProposals !== 'object' ||
+    Array.isArray(routedProposals)
+  ) {
+    return [];
+  }
+  const framework = Array.isArray(routedProposals.framework)
+    ? routedProposals.framework
+    : [];
+  const consumer = Array.isArray(routedProposals.consumer)
+    ? routedProposals.consumer
+    : [];
+
+  const out = [];
+  for (const item of [...framework, ...consumer]) {
+    if (!item || typeof item !== 'object') continue;
+    const category =
+      typeof item.category === 'string' ? item.category.trim() : '';
+    if (category.length === 0) continue;
+    const occurrences =
+      typeof item.occurrences === 'number' && Number.isFinite(item.occurrences)
+        ? item.occurrences
+        : 0;
+    const source = item.source === 'framework' ? 'framework' : 'consumer';
+    out.push({
+      category,
+      occurrences,
+      source,
+      label: `friction::${category}`,
+    });
+  }
+  out.sort((a, b) => a.category.localeCompare(b.category));
+  return out;
+}
+
 /**
  * Pure: compose the retro markdown body. Exported for tests so they can
  * verify the body shape without round-tripping through a stub provider.

package/.agents/scripts/lib/orchestration/retro/phases/post-and-mirror.js

@@ -18,6 +18,7 @@ import { upsertStructuredComment } from '../../ticketing.js';
 import { appendChecksSection, collectRetroFindings } from './checks.js';
 import {
   composeRetroBody as defaultComposeRetroBody,
+  deriveDefectClasses,
   normalizeInterventionCount,
 } from './compose-body.js';
 import { gatherRetroSignals as defaultGatherRetroSignals } from './gather-signals.js';
@@ -74,6 +75,15 @@ export async function composeAndPostRetro({
     perfThresholds,
   });
 
+  // Story #4135 (Epic #4131, F11) — derive the recurring-defect-class signal
+  // from the same routed proposals the body composer consumed. The signal is
+  // surfaced on the runRetro envelope (`defectClasses`) so callers/tests can
+  // observe the recurring classes the routed-proposal `gh issue create`
+  // commands stamp with `friction::<class>` labels — the join key the
+  // `/plan` Phase 0 fetcher reads back. No-op-safe: a clean sprint (no
+  // routed proposals) yields `[]`.
+  const defectClasses = deriveDefectClasses(signals.routedProposals);
+
   const findings = await collectRetroFindings({
     runChecksFn,
     assembleStateFn,
@@ -128,6 +138,7 @@ export async function composeAndPostRetro({
     scorecard,
     body: bodyWithChecks,
     findings,
+    defectClasses,
     commentId: result?.commentId,
   };
 }

package/.agents/scripts/lib/orchestration/retro-runner.js

@@ -18,10 +18,23 @@
  * existing import sites stay unchanged.
  *
  * Public API:
- *   - `runRetro({ epicId, provider, logger })` → `{ posted, compact, scorecard, body }`.
+ *   - `runRetro({ epicId, provider, logger })` → `{ posted, compact, scorecard, body, defectClasses }`.
  *   - `composeRetroBody(input)` (pure, exported for tests).
  *   - `gatherRetroSignals({ epicId, provider })` (exported for tests).
  *   - `appendChecksSection(body, findings)` (pure, exported for tests).
+ *   - `deriveDefectClasses(routedProposals)` (pure, exported for tests).
+ *
+ * Story #4135 (Epic #4131, F11) — the runner now derives a
+ * **recurring-defect-class signal** from the routed-proposal actionable
+ * items (categories that recurred ≥2 times across review/deliver-caught
+ * friction, or a force-flagged `agent::blocked` category). The derived
+ * classes ride on the `runRetro` envelope as `defectClasses[]` and are
+ * stamped onto the proposed `gh issue create` commands as `friction::<class>`
+ * labels (the routed-proposals composer already emits that label), which is
+ * the durable substrate the `/plan` Phase 0 prior-feedback fetcher reads
+ * back to surface recurring classes to the planner. The derivation is
+ * **no-op-safe**: absent or empty routed proposals yield an empty array and
+ * no behavioural change to the existing retro/post path.
  *
  * Behaviour:
  *   - Reads child Stories' `story-perf-summary` comments to aggregate
@@ -50,7 +63,10 @@ import { upsertStructuredComment } from './ticketing.js';
 
 // Re-export phase-level helpers so existing import sites stay unchanged.
 export { appendChecksSection } from './retro/phases/checks.js';
-export { composeRetroBody } from './retro/phases/compose-body.js';
+export {
+  composeRetroBody,
+  deriveDefectClasses,
+} from './retro/phases/compose-body.js';
 export { gatherRetroSignals } from './retro/phases/gather-signals.js';
 
 /**
@@ -92,6 +108,7 @@ export { gatherRetroSignals } from './retro/phases/gather-signals.js';
  *   scorecard: object,
  *   body: string,
  *   findings: object[],
+ *   defectClasses: Array<{ category: string, occurrences: number, source: 'framework'|'consumer', label: string }>,
  *   commentId?: number,
  * }>}
  */

package/.agents/scripts/lib/orchestration/spec-freshness.js

@@ -141,7 +141,7 @@ function lineNumberFor(body, index) {
  * so future cue variants don't silently slip the gate. False positives
  * downgrade staleness to ambiguity, which is the safe direction.
  */
-function hasNewFileCue(body, index, matchLength) {
+export function hasNewFileCue(body, index, matchLength) {
   const start = Math.max(0, index - AMBIGUITY_WINDOW);
   const end = Math.min(body.length, index + matchLength + AMBIGUITY_WINDOW);
   const window = body.slice(start, end).toLowerCase();
@@ -160,7 +160,7 @@ function hasNewFileCue(body, index, matchLength) {
  * @param {string} body
  * @returns {Array<{ path: string, index: number, matchLength: number }>}
  */
-function collectReferences(body) {
+export function collectReferences(body) {
   const refs = [];
   for (const re of [BACKTICK_PATH_RE, COMMENT_HEADER_PATH_RE, BARE_PATH_RE]) {
     re.lastIndex = 0;

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -27,6 +27,8 @@ allowed_tools:
 - Acceptance MUST NOT prescribe a commit subject starting with a non-Conventional-Commits prefix; the literal `baseline-refresh:` leading token is forbidden (use a body trailer instead — see Epic #2501).
 - A legitimately broad Story (files > `hardFiles`) MUST declare `wide` with a one-line reason (encoded in the serialized body string via the `<!-- meta -->` comment) to lift the `hardFiles` rejection; lead the sizing decision with cohesion, not count. UI-touching Stories MUST end `changes` with a `data-testid invariance:` or `data-testid changes: <old> -> <new>` declaration.
 - A Story's `depends_on` references only **sibling Stories within the same Epic**. Apply the cross-cutting-config-file rule (sequential `depends_on` or a late-wave wiring Story) whenever multiple Stories edit a shared root config file.
+- **Authoring-contract altitude (Epic #4131 F8).** `acceptance[]` and `verify[]` are the Story's **binding contract** — the executor MUST satisfy them exactly, and they are the only definition of "done." `changes[]` and `references[]` are an **advisory implementation sketch**: a best-effort prediction of which files the work touches that the executor MAY revise when the codebase tells a different story. Author `acceptance[]`/`verify[]` so they capture the outcome independently of any particular file layout — never bake an incidental implementation detail into them that the advisory sketch is free to change. This does **not** weaken the file-assumption gate: `changes[]` paths are still validated structurally against the base branch (a `creates` against an existing path still fails), the New-File Contract still holds, and the executor's revised approach stays bounded by the inviolable `acceptance[]`/`verify[]` contract and `rules/security-baseline.md`.
+- **Navigate-don't-deep-link acceptance standard (Epic #4131 F5).** For any Story whose acceptance describes a **signed-in** (authenticated) scenario reaching a feature surface, author the acceptance so the persona starts from their authenticated home and **reaches the feature through navigation** (clicking a nav door, menu item, or link the UI exposes) — never by asserting against a hardcoded deep-link URL. A scenario that drops the user straight onto `/some/feature/path` proves the page renders but not that the feature is reachable, masking orphaned surfaces with no nav owner. Phrase signed-in acceptance as "from the signed-in home, the persona navigates to … and sees …", not "loading `/feature/path` shows the feature."
 
 ## Role
 
@@ -253,6 +255,21 @@ Declaring `wide` with a non-empty reason **lifts the `hardFiles` rejection** —
 
 - Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of `docs/style-guide.md` in `acceptance` (e.g. `"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]`). If `docs/style-guide.md` does not exist or has no relevant section, state that explicitly: `"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in PRD §2"]`. Silence on style sourcing is a smell.
 
+#### BINDING ACCEPTANCE vs ADVISORY CHANGES (authoring altitude):
+
+`acceptance[]` and `verify[]` are the **binding contract** the executor MUST satisfy — they are the sole definition of "done." `changes[]` and `references[]` are an **advisory implementation sketch**: your best prediction of the file footprint, which the executor is permitted to revise when the real codebase diverges from the sketch. Author at that altitude:
+
+- Write `acceptance[]`/`verify[]` to capture the **outcome**, independent of any one file layout. Do NOT pin an incidental implementation detail (an internal helper name, a private file path) into an acceptance item that the advisory `changes[]` is free to reshape — assert the observable behaviour instead.
+- Keep `changes[]`/`references[]` as the honest predicted footprint. They still pass through the structural file-assumption gate (the `creates`/`refactors-existing`/`deletes` probes against the base branch) and the New-File Contract unchanged — advisory does NOT mean unvalidated. The executor's latitude to revise the approach never licenses skipping `acceptance[]`/`verify[]` or any `rules/security-baseline.md` MUST.
+
+#### NAVIGATE-DON'T-DEEP-LINK (signed-in acceptance scenarios):
+
+When a Story's acceptance describes a **signed-in / authenticated** persona reaching a feature surface, author it so the persona starts from their authenticated home and **reaches the feature through navigation** — clicking a nav door, menu entry, or link the UI actually exposes — **never** via a hardcoded deep-link URL.
+
+- A deep-link scenario (`load /reports/export and assert the export button`) proves the page renders but NOT that it is reachable; it masks an orphaned surface that no navigation door points to.
+- Phrase it as: `"From the signed-in home, the persona navigates to Reports → Export and sees the export button"` — not `"GET /reports/export returns the export view"`.
+- This applies to signed-in journeys only; an unauthenticated landing page or a deliberately deep-linkable share URL is exempt — say so in the acceptance item when you take that exemption.
+
 ### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has `new`-disposition rows):
 
 The Acceptance Spec's AC table (columns `AC ID | Outcome | Feature File | Scenario | Disposition`) tags each row's `Disposition` with one of `new | updated | unchanged`. A `new` row names a `.feature` file + scenario that does NOT yet exist on `main`. The framework is features-first: implementation Stories reference those `.feature` paths in their `verify[]` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file (observed gap: Epic #18 in `dsj1984/athportal` had 9 `new` rows and no Story tasked with creating the feature files Stories #1457 / #1466 verified against).