mandrel 1.65.0 → 1.67.0

package/.agents/docs/configuration.md

@@ -117,6 +117,9 @@ top-level keys are validation errors.
 | `failOnLargeFanOut` | No | `boolean` | — | — |
 | `largeFanOutThreshold` | No | `integer` | — | — |
 | `crossCuttingRegistries` | No | `string[]` or `{ append?, prepend? }` | — | — |
+| `navigation` | No | `object` | — | Navigability-reachability config consumed by the epic-plan-healthcheck --paranoid reachability check. Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
+| `navigation.routeGlobs` | No | `array<string>` | — | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route. |
+| `navigation.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference. |
 
 ### `delivery` (optional)
 
@@ -259,6 +262,10 @@ top-level keys are validation errors.
 | `quality.baselineEpsilon.lighthouse` | No | `number` | — | — |
 | `quality.baselineEpsilon.bundle-size` | No | `number` | — | — |
 | `quality.baselineEpsilon.duplication` | No | `number` | — | — |
+| `quality.navigability` | No | `object` | — | Navigability lens + post-wave integration gate config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and the deliver-epic.md Phase 6.5 gate (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op. |
+| `quality.navigability.routeGlobs` | No | `array<string>` | — | Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against. |
+| `quality.navigability.navRegistry` | No | `array<string>` | — | Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against. |
+| `quality.navigability.journeySuite` | No | `string` | — | Path or command for the per-persona journey suite the deliver-epic.md Phase 6.5 post-wave integration gate runs. |
 | `lifecycle` | No | `object` | — | Knobs consumed by the lifecycle event bus (Epic #2172). `timeouts` is a per-event budget map (eventName → seconds) used by `TimeoutWatchdog`; missing entries fall back to in-listener defaults. `heartbeatWarnSeconds` is the no-progress threshold consumed by `HeartbeatMonitor`. Story #2227 lays down the keys; consumers land in later stories. |
 | `lifecycle.timeouts` | No | `object<map>` | — | — |
 | `lifecycle.heartbeatWarnSeconds` | No | `integer` | — | — |

package/.agents/docs/workflows.md

@@ -25,7 +25,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (26)
+## Commands (27)
 
 | Command | Description |
 | --- | --- |
@@ -36,6 +36,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
 | `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
 | `/audit-lighthouse` | Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report |
+| `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens (Epic #4131, F2/F3) exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
 | `/audit-performance` | Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations. |
 | `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |
 | `/audit-quality` | Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch. |
@@ -52,6 +53,6 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/git-pr-all` | Stage all outstanding changes, commit, push to a feature branch, and open a pull request with native auto-merge enabled. |
 | `/git-push` | Commit all outstanding changes then push to the remote repository. |
 | `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
-| `/qa-assist` | Human-led QA assist loop — ingest one operator observation, enrich it with repro + root-cause (file:line) + a coverage verdict, ask clarifying questions when it is ambiguous, and append a redacted ledger item to a persistent, resumable rolling session under temp/qa/ |
+| `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run-harness` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |

package/.agents/personas/engineer.md

@@ -51,6 +51,33 @@ plan, stop and ask. Do not invent business logic.
 - **Early Returns:** Use guard clauses to handle errors early and reduce
   nesting.
 
+### C. Implementation Latitude (Logged Deviation)
+
+A Story's `changes[]` and `references[]` are an **advisory implementation
+sketch** — the author's best prediction of the file footprint, not a binding
+instruction. Its `acceptance[]` and `verify[]` arrays are the **binding
+contract** and the only definition of "done."
+
+- **You MAY deviate from the suggested approach** when the real codebase
+  diverges from the sketch — touch a different file, choose a different
+  internal seam, fold or split the predicted edits — **provided you record
+  the rationale**. Note the deviation and the reason in your commit body (or
+  the Story's progress comment), e.g. `the sketched helper already exists in
+  lib/x.js, so I extended it rather than creating lib/y.js`. This converts
+  silent drift into a logged signal a reviewer can audit.
+- **The latitude is bounded and never overrides the inviolable layer.** It
+  applies to the **implementation approach only**. It does **not** license
+  deviating from `acceptance[]` / `verify[]` (you MUST still satisfy every
+  acceptance item and run every verify command to green), and it does **not**
+  license relaxing any `rules/security-baseline.md` MUST or any other
+  inviolable rule. When in doubt, the binding contract and the security
+  baseline win — per the precedence ordering in
+  [`.agents/instructions.md` § 1.K](../instructions.md).
+- **Unlogged deviation is the anti-pattern.** Reshaping the footprint without
+  recording why is the silent drift this latitude exists to surface. If you
+  cannot state the reason in a sentence, re-examine whether the deviation is
+  warranted.
+
 ## 4. Testing & Verification
 
 1. **Test-Driven:** Write tests for utilities, logic helpers, and API routes

package/.agents/schemas/agentrc.schema.json

@@ -389,6 +389,23 @@
         },
         "crossCuttingRegistries": {
           "$ref": "#/$defs/listOrExtenderOfStrings"
+        },
+        "navigation": {
+          "type": "object",
+          "description": "Navigability-reachability config consumed by the epic-plan-healthcheck --paranoid reachability check. Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
+          "properties": {
+            "routeGlobs": {
+              "type": "array",
+              "description": "Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route.",
+              "items": { "type": "string" }
+            },
+            "navRegistry": {
+              "type": "array",
+              "description": "Tokens identifying the nav-registry SSOT a route-adding Story is expected to reference.",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -1294,6 +1311,27 @@
         },
         "baselineEpsilon": {
           "$ref": "#/$defs/baselineEpsilon"
+        },
+        "navigability": {
+          "type": "object",
+          "description": "Navigability lens + post-wave integration gate config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and the deliver-epic.md Phase 6.5 gate (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
+          "properties": {
+            "routeGlobs": {
+              "type": "array",
+              "description": "Glob patterns (pages/**, app/**/route.ts) marking paths that add a user-facing route — the route-tree SSOT the navigability lens enumerates and the route-added routing predicate matches against.",
+              "items": { "type": "string" }
+            },
+            "navRegistry": {
+              "type": "array",
+              "description": "Tokens identifying the nav-registry SSOT the navigability lens checks every route resolves a nav door against.",
+              "items": { "type": "string" }
+            },
+            "journeySuite": {
+              "type": "string",
+              "description": "Path or command for the per-persona journey suite the deliver-epic.md Phase 6.5 post-wave integration gate runs."
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/.agents/schemas/audit-rules.json

@@ -149,6 +149,18 @@
         ]
       },
       "substitutionKeys": []
+    },
+    "audit-navigability": {
+      "triggers": {
+        "gates": ["gate2", "gate3"],
+        "keywords": [
+          "navigability",
+          "reachability",
+          "nav registry",
+          "route tree"
+        ]
+      },
+      "substitutionKeys": []
     }
   }
 }

package/.agents/scripts/epic-audit-prepare.js

@@ -55,6 +55,7 @@
  *     "selectedAudits": ["audit-security", "audit-privacy"],
  *     "changeSetAudits": ["audit-privacy"],
  *     "riskRoutedAudits": ["audit-security"],
+ *     "globalLenses": [],
  *     "changedFiles": ["src/api/admin/users.ts", "..."],
  *     "changedFilesCount": 47,
  *     "substitutionsPayload": "src/api/admin/users.ts\n..."
@@ -67,6 +68,17 @@
  * `depth` (`light` / `standard` / `deep`) is the orthogonal "how deep each
  * selected lens runs" signal (Story #3939).
  *
+ * Epic #4131 (F2/F3) — `globalLenses` is the subset of `selectedAudits` on the
+ * global-lens allowlist (`GLOBAL_LENS_ALLOWLIST`, e.g. `audit-navigability`):
+ * lenses the helper runs against the WHOLE route tree, exempt from the
+ * cross-epic-leak guard's change-set narrowing (`#3362`). The exemption is
+ * scoped to these lenses only — every other selected lens stays scoped to
+ * `changedFiles`, and the guard is not weakened for them. The navigability lens
+ * is also auto-selected here when a changed file matches a consumer-configured
+ * route glob (`delivery.quality.navigability.routeGlobs`), routed through the
+ * SAME risk-routed-lens union; with no route globs configured it routes
+ * nothing (silent no-op).
+ *
  * Usage:
  *   node .agents/scripts/epic-audit-prepare.js --epic <epicId> [--base-branch main]
  *
@@ -76,7 +88,12 @@
  *   1 — provider / git failure
  */
 
-import { selectAudits } from './lib/audit-suite/index.js';
+import {
+  GLOBAL_LENS_ALLOWLIST,
+  isGlobalLens,
+  routesNavigabilityLens,
+  selectAudits,
+} from './lib/audit-suite/index.js';
 import { defineFlags } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
@@ -105,7 +122,13 @@ Output (JSON envelope on stdout):
                      fire, the severity taxonomy, or the Phase 4 halting rule.
   selectedAudits     De-duplicated union of changeSetAudits + riskRoutedAudits.
   changeSetAudits    Lenses the change-set selector chose.
-  riskRoutedAudits   Lenses routed from the model-judged high-risk axes.
+  riskRoutedAudits   Lenses routed from the model-judged high-risk axes plus the
+                     navigability lens when a changed file matches a configured
+                     route glob (Epic #4131, F3).
+  globalLenses       Subset of selectedAudits on the global-lens allowlist
+                     (e.g. audit-navigability) — run against the WHOLE route
+                     tree, exempt from the cross-epic-leak guard (Epic #4131,
+                     F2). Empty unless a global lens was selected.
   changedFiles, changedFilesCount, substitutionsPayload
 `;
 
@@ -359,14 +382,40 @@ export async function runEpicAuditPrepare(values, deps = {}) {
   // (best-effort; a read failure yields no extra lenses). A high-risk
   // `security` axis therefore fires `audit-security` even when the change
   // set alone did not select it; a low-risk Epic adds nothing.
-  const riskRoutedAudits = await resolveRiskRoutedLenses({
+  const riskRoutedFromVerdict = await resolveRiskRoutedLenses({
     epicId,
     provider,
     readPlanState: deps.readPlanState,
     resolveAuditLenses: deps.resolveAuditLenses,
   });
+
+  // Epic #4131 (F3) — route the navigability lens onto route-adding change
+  // sets through the SAME risk-routed-lens union: when a changed file matches a
+  // consumer-configured route glob (`delivery.quality.navigability.routeGlobs`)
+  // the lens joins `riskRoutedAudits`, exactly like a verdict-routed lens. No
+  // new routing function is introduced — the predicate feeds the existing
+  // `unionAudits` seam. Unconfigured consumers route nothing (silent no-op), so
+  // the change-set-scoped selection is unchanged. `cfg` may be `{}` in tests;
+  // the predicate tolerates an absent config and returns `false`.
+  const navigabilityRouted = routesNavigabilityLens({
+    changedFiles,
+    config: cfg,
+  })
+    ? GLOBAL_LENS_ALLOWLIST.slice()
+    : [];
+  const riskRoutedAudits = unionAudits(
+    riskRoutedFromVerdict,
+    navigabilityRouted,
+  );
   const selectedAudits = unionAudits(changeSetAudits, riskRoutedAudits);
 
+  // Epic #4131 (F2) — surface which selected lenses are on the global-lens
+  // allowlist so the helper runs them against the WHOLE route tree, exempt from
+  // the cross-epic-leak guard's change-set narrowing (`#3362`). The exemption
+  // is scoped to these lenses only; every other selected lens stays scoped to
+  // `changedFiles`. Order follows `selectedAudits` for a deterministic list.
+  const globalLenses = selectedAudits.filter(isGlobalLens);
+
   // Story #3939 — resolve the run's audit depth from the SAME model-judged
   // risk envelope the lenses route from, folded with the changed-file count
   // the change set just produced. Best-effort: an absent checkpoint degrades
@@ -392,6 +441,7 @@ export async function runEpicAuditPrepare(values, deps = {}) {
         selectedAudits,
         changeSetAudits,
         riskRoutedAudits,
+        globalLenses,
         changedFiles,
         changedFilesCount: changedFiles.length,
         substitutionsPayload: changedFiles.join('\n'),

package/.agents/scripts/epic-plan-healthcheck.js

@@ -12,7 +12,10 @@
  * Modes (additive — the fast checks below always run):
  *   (default)         — config validation + git remote check only.
  *                       Targets <2s.
- *   --paranoid        — adds ticket-hierarchy revalidation.
+ *   --paranoid        — adds ticket-hierarchy revalidation plus a
+ *                       navigability-reachability semantic check (silent
+ *                       no-op unless `planning.navigation.routeGlobs` is
+ *                       configured).
  *   --prime-install   — adds the pnpm content-addressable-store priming
  *                       path (up to 300s).
  *
@@ -214,6 +217,182 @@ async function checkTickets(provider, epicId) {
   };
 }
 
+/**
+ * Resolve the navigation config that drives the reachability check.
+ *
+ * The check is opt-in: a consumer that has not configured
+ * `planning.navigation.routeGlobs` gets a silent no-op (F7 / AC-13). The
+ * nav-registry token list is what a route-adding Story is expected to
+ * reference somewhere in its body or `## Acceptance` section.
+ *
+ * @param {object} config Resolved `.agentrc.json`.
+ * @returns {{ routeGlobs: string[], navRegistry: string[] }}
+ */
+function resolveNavConfig(config) {
+  const nav = config?.planning?.navigation ?? {};
+  const toList = (v) =>
+    (Array.isArray(v) ? v : v == null ? [] : [v])
+      .filter((s) => typeof s === 'string' && s.trim().length > 0)
+      .map((s) => s.trim());
+  return {
+    routeGlobs: toList(nav.routeGlobs),
+    navRegistry: toList(nav.navRegistry),
+  };
+}
+
+/**
+ * Translate a route glob (`pages/**`, `app/**\/route.ts`) into a RegExp that
+ * matches a path string. Supports `**` (any depth, including `/`), `*` (any
+ * run of non-separator chars), and `?` (single non-separator char). All other
+ * characters are matched literally.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegExp(glob) {
+  // Collapse adjacent `**` segments before compiling. `**/**` and `***` both
+  // mean "any depth", but compiling them literally emits adjacent `.*` runs
+  // (`.*/.*` / `.*.*`) that backtrack catastrophically on a long non-matching
+  // path. Collapsing to a single `**` preserves semantics and keeps the
+  // matcher linear (ReDoS hardening — Epic #4131 audit follow-up).
+  const normalized = glob
+    .replace(/\*\*(?:\/\*\*)+/g, '**')
+    .replace(/\*{3,}/g, '**');
+  let re = '';
+  for (let i = 0; i < normalized.length; i++) {
+    const ch = normalized[i];
+    if (ch === '*') {
+      if (normalized[i + 1] === '*') {
+        re += '.*';
+        i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Extract the candidate route-touching paths a Story declares. Reads the
+ * `## Changes` block (the decompose-author emits one `{"path":...}` JSON
+ * object per bullet) and falls back to any bare ```` `path/like/this` ````
+ * inline-code spans in the body.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+function extractStoryPaths(body) {
+  if (typeof body !== 'string' || body.length === 0) return [];
+  const paths = new Set();
+  // `{"path":"pages/foo.tsx", ...}` change descriptors.
+  for (const m of body.matchAll(/"path"\s*:\s*"([^"]+)"/g)) {
+    paths.add(m[1]);
+  }
+  // Inline-code spans that look like a path (contain a slash or a dotted ext).
+  for (const m of body.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (/[/.]/.test(token) && !token.includes(' ')) paths.add(token);
+  }
+  return [...paths];
+}
+
+/**
+ * Return the `## Acceptance` + full-body text a Story is expected to reference
+ * the nav registry from. The whole body is searched (the registry can be cited
+ * in the Goal, Changes, or Acceptance), so this just lower-cases the body once.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+function referenceableText(body) {
+  return typeof body === 'string' ? body.toLowerCase() : '';
+}
+
+/**
+ * Navigability-reachability semantic check (F7 / AC-8).
+ *
+ * Flags every Story that adds a route (touches a path matching a configured
+ * `planning.navigation.routeGlobs` entry) but whose body / acceptance never
+ * references the configured nav registry. Silent no-op (returns ok with an
+ * explicit detail) when no route-glob config is present.
+ *
+ * @param {object} provider
+ * @param {number|null} epicId
+ * @param {object} config
+ */
+async function checkReachability(provider, epicId, config) {
+  const { routeGlobs, navRegistry } = resolveNavConfig(config);
+
+  // Opt-in: unconfigured consumers degrade to a silent no-op.
+  if (routeGlobs.length === 0) {
+    return {
+      ok: true,
+      detail: 'No planning.navigation.routeGlobs configured — skipped.',
+    };
+  }
+
+  if (!epicId) {
+    return {
+      ok: false,
+      detail:
+        'reachability check requires --epic <ID> to fetch the ticket hierarchy.',
+    };
+  }
+
+  let tickets;
+  try {
+    tickets = await provider.getSubTickets(epicId);
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `Could not fetch Epic #${epicId} tickets: ${err.message}`,
+    };
+  }
+
+  const stories = tickets.filter((t) => t.labels.includes(TYPE_LABELS.STORY));
+  const matchers = routeGlobs.map(globToRegExp);
+  const registryTokens = navRegistry.map((t) => t.toLowerCase());
+
+  const flagged = [];
+  for (const story of stories) {
+    const body = story.body ?? '';
+    const addsRoute = extractStoryPaths(body).some((p) =>
+      matchers.some((rx) => rx.test(p)),
+    );
+    if (!addsRoute) continue;
+
+    const text = referenceableText(body);
+    // When no explicit registry token is configured, fall back to the
+    // generic "nav registry" phrase so a route-adding Story is still
+    // expected to mention the navigation surface.
+    const tokens =
+      registryTokens.length > 0
+        ? registryTokens
+        : ['nav registry', 'navigation'];
+    const referencesRegistry = tokens.some((tok) => text.includes(tok));
+    if (!referencesRegistry) flagged.push(`#${story.id}`);
+  }
+
+  if (flagged.length > 0) {
+    const registryHint =
+      navRegistry.length > 0 ? navRegistry.join(', ') : 'the nav registry';
+    return {
+      ok: false,
+      detail: `${flagged.length} route-adding story/stories never reference ${registryHint}: ${flagged.join(', ')}`,
+    };
+  }
+
+  return {
+    ok: true,
+    detail: `${stories.length} stories scanned — every route-adding story references the nav registry.`,
+  };
+}
+
 /** Prime the pnpm content-addressable store via `pnpm install --frozen-lockfile`. */
 function primePnpmStore(cwd, dryRun) {
   const lockFile = path.join(cwd, 'pnpm-lock.yaml');
@@ -274,6 +453,9 @@ async function timed(name, fn) {
  * @returns {Promise<{ok: boolean, degraded: boolean, reason: string|null,
  *   checks: Array<{name: string, ok: boolean, durationMs: number, detail: string}>}>}
  */
+// exported for tests — direct-unit coverage of the reachability semantics.
+export { checkReachability, extractStoryPaths, globToRegExp };
+
 // exported for tests — Story-level reuse runner reserved for future test coverage
 export async function runPlanHealthcheck(opts = {}) {
   const ARG_KEYS = ['epicId', 'paranoid', 'primeInstall', 'dryRun'];
@@ -309,13 +491,20 @@ export async function runPlanHealthcheck(opts = {}) {
     await timed('git-remote', async () => checkGitRemote(baseBranch, cwd)),
   );
 
-  // Paranoid lane: ticket-hierarchy revalidation (2-tier only).
+  // Paranoid lane: ticket-hierarchy revalidation (2-tier only) plus the
+  // navigability-reachability semantic check (silent no-op when unconfigured).
   if (paranoid) {
     const provider = opts.injectedProvider || createProvider(config);
     progress('CHECK', 'Validating ticket hierarchy...');
     checks.push(
       await timed('ticket-hierarchy', () => checkTickets(provider, epicId)),
     );
+    progress('CHECK', 'Checking route-reachability (nav registry)...');
+    checks.push(
+      await timed('reachability', () =>
+        checkReachability(provider, epicId, config),
+      ),
+    );
   }
 
   // Optional pnpm-store priming.

package/.agents/scripts/lib/audit-suite/index.js

@@ -16,7 +16,12 @@
 
 export { runAuditSuite } from './runner.js';
 export {
+  GLOBAL_LENS_ALLOWLIST,
+  isGlobalLens,
   matchesAnyFilePattern,
   matchesFilePattern,
+  NAVIGABILITY_LENS,
+  resolveNavigabilityRouteGlobs,
+  routesNavigabilityLens,
   selectAudits,
 } from './selector.js';

package/.agents/scripts/lib/audit-suite/selector.js

@@ -26,6 +26,79 @@ import { withTimeout } from '../util/with-timeout.js';
 
 const DEFAULT_GIT_TIMEOUT_MS = 30000;
 
+/**
+ * The audit-lens identifier for the navigability lens (Epic #4131, F2/F3).
+ * Authored as `.agents/workflows/audit-navigability.md`; registered here so the
+ * roster, the global-lens allowlist, and the route-added routing seam all
+ * reference one symbol rather than a hard-coded string.
+ */
+export const NAVIGABILITY_LENS = 'audit-navigability';
+
+/**
+ * The **global-lens allowlist** — lenses that evaluate a property of the
+ * **whole** product (not just the Epic's change set) and are therefore exempt
+ * from the cross-epic-leak guard (`#3362`) that narrows every other lens's
+ * evidence to the Epic's `changedFiles`. A lens in this set still runs through
+ * the SAME `runAuditSuite` / `selectAuditStrategy` engine; only the
+ * change-set narrowing is bypassed, and only for the listed lenses. The guard
+ * is **not** weakened for any lens absent from this set.
+ *
+ * Navigability is the founding member: reachability is a global property — a
+ * change can orphan a route it never touched — so the lens must read the whole
+ * route tree + nav registry regardless of which file triggered it.
+ */
+export const GLOBAL_LENS_ALLOWLIST = Object.freeze([NAVIGABILITY_LENS]);
+
+/**
+ * True when `lens` is on the global-lens allowlist and is therefore exempt
+ * from the cross-epic-leak guard's change-set narrowing. Pure; the single
+ * read-side of {@link GLOBAL_LENS_ALLOWLIST} so callers never hard-code the
+ * membership test.
+ *
+ * @param {string} lens
+ * @returns {boolean}
+ */
+export function isGlobalLens(lens) {
+  return GLOBAL_LENS_ALLOWLIST.includes(lens);
+}
+
+/**
+ * Resolve the consumer's navigability route globs from the resolved config.
+ * Reads `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the
+ * navigability lens enumerates and the route-added routing predicate matches
+ * against. Returns an empty array when the block (or any ancestor) is absent,
+ * so an unconfigured consumer routes nothing and the lens degrades to a silent
+ * no-op (Epic #4131 — "no-op when unconfigured").
+ *
+ * @param {object|null|undefined} config Resolved `.agentrc.json` wrapper.
+ * @returns {string[]} Route globs, or `[]` when unconfigured.
+ */
+export function resolveNavigabilityRouteGlobs(config) {
+  const globs = config?.delivery?.quality?.navigability?.routeGlobs;
+  return Array.isArray(globs) ? globs.filter((g) => typeof g === 'string') : [];
+}
+
+/**
+ * Decide whether a change set routes the navigability lens. The lens is routed
+ * when any `changedFiles` entry matches a consumer-configured route glob
+ * (`delivery.quality.navigability.routeGlobs`) — i.e. the change set adds or
+ * touches a route file. When no route globs are configured, this returns
+ * `false` (the unconfigured no-op), so the existing change-set-scoped lens
+ * selection is unchanged.
+ *
+ * This is a pure predicate over the SAME inputs the existing risk-routed-lens
+ * union already consumes; the caller folds its result into `riskRoutedAudits`
+ * via the existing `unionAudits` — no new routing machinery is added.
+ *
+ * @param {{ changedFiles?: string[], config?: object|null }} params
+ * @returns {boolean}
+ */
+export function routesNavigabilityLens({ changedFiles, config } = {}) {
+  const globs = resolveNavigabilityRouteGlobs(config);
+  if (globs.length === 0) return false;
+  return matchesAnyFilePattern(globs, changedFiles ?? []);
+}
+
 /**
  * Test a single filename against a single glob pattern using the project's
  * configured matcher semantics (`picomatch` with `dot: true`). Exported so

package/.agents/scripts/lib/config-settings-schema-quality.js

@@ -96,6 +96,19 @@ export const QUALITY_SCHEMA = {
     codingGuardrails: CODING_GUARDRAILS_SCHEMA,
     autoRefresh: AUTO_REFRESH_SCHEMA,
     baselineEpsilon: BASELINE_EPSILON_SCHEMA,
+    // Navigability lens + post-wave integration gate config (Epic #4131,
+    // F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and the
+    // deliver-epic.md Phase 6.5 gate (journey suite). Opt-in: absent or empty
+    // routeGlobs degrades to a silent no-op.
+    navigability: {
+      type: 'object',
+      properties: {
+        routeGlobs: { type: 'array', items: { type: 'string' } },
+        navRegistry: { type: 'array', items: { type: 'string' } },
+        journeySuite: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config-settings-schema.js

@@ -282,6 +282,17 @@ const PLANNING_SCHEMA = {
     // decompose loop's re-prompt gate.
     failOnSharedEditors: { type: 'boolean' },
     requireExplicitCrossStoryDeps: { type: 'boolean' },
+    // Navigability-reachability config consumed by the epic-plan-healthcheck
+    // --paranoid reachability check (Epic #4131, F7). Opt-in: absent or empty
+    // routeGlobs degrades to a silent no-op.
+    navigation: {
+      type: 'object',
+      properties: {
+        routeGlobs: { type: 'array', items: { type: 'string' } },
+        navRegistry: { type: 'array', items: { type: 'string' } },
+      },
+      additionalProperties: false,
+    },
   },
   additionalProperties: false,
 };