mandrel 2.0.0 → 2.2.0

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

@@ -6,16 +6,19 @@
  * without importing upward from a top-level CLI file.
  *
  * Pure (modulo `gitSpawn`) — exposed helpers are:
- *   - matchesFilePattern    — single file × single glob (picomatch with `dot`)
- *   - matchesAnyFilePattern — file list × pattern list, short-circuiting
- *   - selectAudits          — main entry; reads audit-rules.json, runs `git
- *                             diff --name-only`, applies keyword + glob rules.
+ *   - matchesFilePattern         — single file × single glob (picomatch, `dot`)
+ *   - matchesAnyFilePattern      — file list × pattern list, short-circuiting
+ *   - selectSensitivePathClasses — change set × the manifest's `sensitivePaths`
+ *                                  block; the review-depth derivation's matcher
+ *   - selectAudits               — main entry; reads audit-rules.json, runs `git
+ *                                  diff --name-only`, applies keyword + glob
+ *                                  rules.
  *
  * All rule-matching lives here; the former `select-audits.js` CLI wrapper
  * was retired in #4482 (consumers call `selectAudits` via the barrel).
  */
 
-import { readFileSync } from 'node:fs';
+import { readdirSync, readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import picomatch from 'picomatch';
@@ -197,6 +200,50 @@ export function selectLocalLenses({
   return selected;
 }
 
+/**
+ * Select the sensitive-path classes a change set touches, from the
+ * `sensitivePaths` block of [`audit-rules.json`](../../../schemas/audit-rules.json).
+ *
+ * This is the matcher behind the close-time review-depth derivation
+ * (`review-depth.js#deriveChangeLevel`, Story #4542): a change set intersecting
+ * any registered class's globs is *observably* sensitive — auth, a migration, a
+ * billing path — and earns a deep pass however narrow the diff is. The classes
+ * and their globs live in the manifest next to the lens `triggers.filePatterns`
+ * precisely so an operator can extend them without a code change, and matching
+ * runs through the same {@link matchesAnyFilePattern} picomatch machinery rather
+ * than a second matcher with its own glob semantics.
+ *
+ * An empty change set, an absent `sensitivePaths` block, or a class whose globs
+ * match nothing all contribute no class — the caller then resolves depth from
+ * diff width alone.
+ *
+ * Pure over its injected seam: `injectedRules` skips the manifest disk read.
+ * Selection order follows the manifest's declaration order, which is
+ * deterministic.
+ *
+ * @param {{
+ *   changedFiles?: string[],
+ *   injectedRules?: { sensitivePaths?: Record<string, { filePatterns?: string[] }> },
+ * }} [params]
+ * @returns {string[]} The matched class names, in manifest order.
+ */
+export function selectSensitivePathClasses({
+  changedFiles,
+  injectedRules,
+} = {}) {
+  const files = Array.isArray(changedFiles) ? changedFiles : [];
+  if (files.length === 0) return [];
+
+  const rules = injectedRules ?? readAuditRulesSync();
+  const matched = [];
+  for (const [name, entry] of Object.entries(rules.sensitivePaths ?? {})) {
+    if (matchesAnyFilePattern(entry?.filePatterns ?? [], files)) {
+      matched.push(name);
+    }
+  }
+  return matched;
+}
+
 /**
  * Resolve the consumer's navigability route globs from the resolved config.
  * Reads `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the
@@ -221,9 +268,9 @@ export function resolveNavigabilityRouteGlobs(config) {
  * `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.
+ * A pure predicate over a change set — the same input {@link selectAudits} and
+ * {@link selectLocalLenses} already match against. The caller unions its result
+ * into the lens roster it is assembling; no new routing machinery is added.
  *
  * @param {{ changedFiles?: string[], config?: object|null }} params
  * @returns {boolean}
@@ -234,6 +281,206 @@ export function routesNavigabilityLens({ changedFiles, config } = {}) {
   return matchesAnyFilePattern(globs, changedFiles ?? []);
 }
 
+/**
+ * Package names (or scope/name segments of them) that declare a **web
+ * rendering surface**. Matched against the consumer's root `package.json`
+ * `dependencies` + `devDependencies` keys, segment-wise, so `@angular/core`
+ * matches via `angular` and `@remix-run/react` via `react`.
+ */
+const WEB_FRAMEWORK_PACKAGES = Object.freeze([
+  'react',
+  'next',
+  'vue',
+  'svelte',
+  'sveltekit',
+  'astro',
+  'nuxt',
+  'remix',
+  'remix-run',
+  'gatsby',
+  'angular',
+]);
+
+/** File extensions whose presence in the source tree implies a web surface. */
+const WEB_ASSET_EXTENSIONS = Object.freeze(['.html', '.css', '.jsx', '.tsx']);
+
+/**
+ * Directories the web-surface file scan never descends into. `node_modules` is
+ * the load-bearing one (a dependency's bundled `.css` says nothing about the
+ * consumer's own surface); the test directories are excluded because a fixture
+ * `.html` is a test artifact, not a shipped page.
+ */
+const WEB_SCAN_SKIP_DIRS = Object.freeze([
+  'node_modules',
+  '.git',
+  '.worktrees',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'temp',
+  'tmp',
+  'tests',
+  'test',
+  '__tests__',
+  '__mocks__',
+  'spec',
+  'e2e',
+  'fixtures',
+]);
+
+/** Scan bounds — the probe is a cheap heuristic, not an exhaustive crawl. */
+const WEB_SCAN_MAX_DEPTH = 6;
+const WEB_SCAN_MAX_ENTRIES = 4000;
+
+/**
+ * Process-lifetime memo for the filesystem half of the web-surface probe,
+ * keyed by project root. The config half ({@link resolveNavigabilityRouteGlobs})
+ * is a free object read and is deliberately NOT memoized, so a caller passing a
+ * different config never reads a stale answer.
+ *
+ * @type {Map<string, boolean>}
+ */
+const _webSurfaceFsCache = new Map();
+
+/** Test-only: drop the memo so a fixture root can be re-probed after edits. */
+export function _resetWebSurfaceCache() {
+  _webSurfaceFsCache.clear();
+}
+
+/**
+ * True when the root `package.json` declares a web-framework dependency.
+ * Returns `null` — *indeterminate* — when the manifest exists but cannot be
+ * read or parsed; the caller fails open on that (see {@link hasWebSurface}).
+ * A genuinely absent manifest (`ENOENT`) is determinate: there is no
+ * declaration, so there is no signal, and the file scan gets its turn.
+ *
+ * @param {string} root
+ * @returns {boolean|null}
+ */
+function declaresWebFramework(root) {
+  let raw;
+  try {
+    raw = readFileSync(path.join(root, 'package.json'), 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    return null;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const names = [
+    ...Object.keys(pkg?.dependencies ?? {}),
+    ...Object.keys(pkg?.devDependencies ?? {}),
+  ];
+  return names.some((name) =>
+    name
+      .replace(/^@/, '')
+      .split('/')
+      .some((segment) => WEB_FRAMEWORK_PACKAGES.includes(segment)),
+  );
+}
+
+/**
+ * True when a bounded scan of the source tree finds a web asset file
+ * (`.html` / `.css` / `.jsx` / `.tsx`) outside the skipped directories.
+ * Returns `null` — *indeterminate* — when the root itself is unreadable, or
+ * when the scan exhausted its entry budget without finding one: a truncated
+ * scan genuinely did not finish looking, and reporting "no web surface" from
+ * a half-walked tree would silently drop lens coverage.
+ *
+ * Uses `readdirSync(withFileTypes)` rather than `git ls-files` — a filesystem
+ * check suffices, and shelling out to git would make the probe cost a process
+ * spawn on every selection.
+ *
+ * @param {string} root
+ * @returns {boolean|null}
+ */
+function scanForWebAssets(root) {
+  let budget = WEB_SCAN_MAX_ENTRIES;
+  const queue = [{ dir: root, depth: 0 }];
+  let rootRead = false;
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // A single unreadable subdirectory is skipped: a permissions oddity is
+      // far likelier than an entire web surface hiding behind it. An
+      // unreadable ROOT is a different story — see below.
+      if (dir === root) return null;
+      continue;
+    }
+    if (dir === root) rootRead = true;
+
+    for (const entry of entries) {
+      if (budget-- <= 0) return null; // truncated ⇒ indeterminate
+      if (entry.isDirectory()) {
+        if (WEB_SCAN_SKIP_DIRS.includes(entry.name)) continue;
+        if (depth + 1 <= WEB_SCAN_MAX_DEPTH) {
+          queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+        continue;
+      }
+      if (WEB_ASSET_EXTENSIONS.includes(path.extname(entry.name))) return true;
+    }
+  }
+  return rootRead ? false : null;
+}
+
+/**
+ * Decide whether the project has a **web surface** — the applicability
+ * predicate behind the `target: "web"` gate in `audit-rules.json` (#4579).
+ *
+ * Mandrel is materialized into other projects, so this cannot be a property of
+ * *this* repository: a consumer with a real web surface MUST still get the web
+ * lenses. It is therefore derived from observables in the consumer's own
+ * checkout, and deliberately NOT from a new `.agentrc` key — a new key would
+ * have to be threaded through the runtime AJV (`lib/config-settings-schema*.js`)
+ * *and* the published mirror, and would make consumers hand-configure something
+ * already derivable.
+ *
+ * A project is web-capable when ANY of these hold:
+ *   1. `delivery.quality.navigability.routeGlobs` is configured — the existing
+ *      web signal the navigability lens already routes off.
+ *   2. The root `package.json` declares a web framework (react / next / vue /
+ *      svelte / astro / nuxt / remix / gatsby / angular).
+ *   3. A bounded source scan finds a `.html` / `.css` / `.jsx` / `.tsx` file
+ *      outside test directories.
+ *
+ * **Fail direction: OPEN.** When a signal is indeterminate — an unparseable
+ * `package.json`, an unreadable root, a scan that hit its entry budget — the
+ * project is treated as web-capable. A false positive costs one wasted lens
+ * run; a false negative silently drops audit coverage on a project that has a
+ * real web surface, and nothing downstream would ever report the omission.
+ * Wasted spend is recoverable; dropped coverage is not.
+ *
+ * @param {{ config?: object|null, projectRoot?: string }} [params]
+ * @returns {boolean}
+ */
+export function hasWebSurface({ config, projectRoot = PROJECT_ROOT } = {}) {
+  if (resolveNavigabilityRouteGlobs(config).length > 0) return true;
+
+  if (_webSurfaceFsCache.has(projectRoot)) {
+    return _webSurfaceFsCache.get(projectRoot);
+  }
+
+  const declared = declaresWebFramework(projectRoot);
+  // `null` is indeterminate, not false — fail open.
+  const result =
+    declared === null || declared === true
+      ? true
+      : scanForWebAssets(projectRoot) !== false;
+
+  _webSurfaceFsCache.set(projectRoot, result);
+  return result;
+}
+
 /**
  * Test a single filename against a single glob pattern using the project's
  * configured matcher semantics (`picomatch` with `dot: true`). Exported so
@@ -261,6 +508,16 @@ export function matchesAnyFilePattern(patterns, files) {
  * @param {number} params.ticketId
  * @param {string} params.gate
  * @param {import('../ITicketingProvider.js').ITicketingProvider} params.provider
+ * @param {string[]} [params.changedFiles]
+ *   The change set to select over, when the caller already knows it. Supplying
+ *   it skips the internal `git diff` entirely and `baseBranch` / `headRef` are
+ *   then unused. Callers whose change set is NOT the working tree's
+ *   `baseBranch...headRef` MUST pass this: the plan-run epilogue runs from the
+ *   main checkout *after* its Stories have merged, where any `main...HEAD`
+ *   range is empty by construction and selection would silently degrade to
+ *   keyword-only matching (Story #4571). An empty array is honoured as
+ *   "the set is known, and it is empty" — distinct from omitting the option,
+ *   which means "derive it from git".
  * @param {string} [params.baseBranch]
  * @param {string} [params.headRef]
  *   Git ref whose diff-against-`baseBranch` defines the change set. Defaults
@@ -284,6 +541,9 @@ export function matchesAnyFilePattern(patterns, files) {
  *   Test-only seam to drive the `--gate-mode` / `MANDREL_GATE_MODE=1`
  *   detection; production callers leave unset and `isGateMode` reads
  *   `process.argv` / `process.env`.
+ * @param {typeof hasWebSurface} [params.hasWebSurfaceFn]
+ *   Test-only seam overriding the web-surface probe behind the
+ *   `target: "web"` applicability gate. Production callers leave unset.
  *
  * Returns either the success envelope (`{ selectedAudits, ticketId, gate, context }`)
  * OR the degraded envelope (`{ ok: false, degraded: true, reason, detail }`)
@@ -294,11 +554,13 @@ export async function selectAudits({
   ticketId,
   gate,
   provider,
+  changedFiles: injectedChangedFiles,
   baseBranch = 'main',
   headRef = 'HEAD',
   injectedGitSpawn,
   gitTimeoutMsOverride,
   gateModeOpts,
+  hasWebSurfaceFn = hasWebSurface,
 }) {
   const config = resolveConfig();
   const timeoutMs = gitTimeoutMsOverride ?? DEFAULT_GIT_TIMEOUT_MS;
@@ -323,6 +585,14 @@ export async function selectAudits({
 
   const runGit = injectedGitSpawn ?? (async (...args) => gitSpawn(...args));
 
+  // A caller that already knows the change set supplies it, and no git ref is
+  // consulted at all — `baseBranch` / `headRef` describe a diff that is not
+  // being taken. The plan-run epilogue is the motivating caller (Story #4571):
+  // it resolves the run's landed diff from the Stories' squash-merges, and any
+  // `main...HEAD` range it could name from the main checkout post-land is
+  // empty by construction.
+  const hasInjectedChangedFiles = Array.isArray(injectedChangedFiles);
+
   // Resolve `headRef` to a commit before diffing. A non-default `headRef`
   // (Epic-mode callers pass `refs/heads/epic/<id>`) that the repo can't
   // resolve means the requested Epic's branch is not present in this
@@ -331,7 +601,7 @@ export async function selectAudits({
   // degraded signal instead of leaking the wrong scope. `HEAD` is always
   // resolvable in a valid repo, so the default-path callers skip the probe
   // cost on the common case.
-  if (headRef !== 'HEAD') {
+  if (!hasInjectedChangedFiles && headRef !== 'HEAD') {
     let resolved;
     try {
       resolved = await withTimeout(
@@ -358,18 +628,22 @@ export async function selectAudits({
     }
   }
 
-  let changedFiles = [];
+  let changedFiles = hasInjectedChangedFiles
+    ? injectedChangedFiles.map((f) => String(f).trim()).filter(Boolean)
+    : [];
   try {
-    const diff = await withTimeout(
-      runGit(
-        process.cwd(),
-        'diff',
-        '--name-only',
-        `${baseBranch}...${headRef}`,
-      ),
-      timeoutMs,
-      { label: 'select-audits git diff' },
-    );
+    const diff = hasInjectedChangedFiles
+      ? null
+      : await withTimeout(
+          runGit(
+            process.cwd(),
+            'diff',
+            '--name-only',
+            `${baseBranch}...${headRef}`,
+          ),
+          timeoutMs,
+          { label: 'select-audits git diff' },
+        );
     if (diff?.status === 0) {
       changedFiles = diff.stdout
         .split('\n')
@@ -393,16 +667,40 @@ export async function selectAudits({
 
   const selectedAudits = [];
 
+  // Resolved at most once per call, and only if a `target: "web"` lens
+  // actually clears its gate — a Node-only project must not pay a filesystem
+  // scan on a roster with no web lens in it.
+  let webSurfaceMemo = null;
+  const projectIsWebCapable = () => {
+    if (webSurfaceMemo === null) {
+      webSurfaceMemo = hasWebSurfaceFn({ config });
+    }
+    return webSurfaceMemo;
+  };
+
   for (const [auditName, ruleOpts] of Object.entries(rulesData.audits || {})) {
     const triggers = ruleOpts.triggers || {};
 
     const gateMatch = triggers.gates?.includes(gate);
     if (!gateMatch) continue;
 
+    // Target-applicability gate (#4579). A lens declaring `target: "web"`
+    // has nothing to read on a project with no web surface, yet still
+    // whole-word-matches ordinary prose — `audit-seo` fires on the `meta`
+    // inside every Story body's `<!-- meta: {...} -->` machine comment. The
+    // roster's own instruction is that the host MUST walk every listed lens,
+    // so an inapplicable entry is not just wasted spend: it teaches operators
+    // to ignore the MUST. An absent `target` means "always applicable", so no
+    // existing lens changes behaviour.
+    if (ruleOpts.target === 'web' && !projectIsWebCapable()) continue;
+
     const keywords = triggers.keywords || [];
     let keywordMatch = false;
     for (const kw of keywords) {
-      if (contentToSearch.includes(kw.toLowerCase())) {
+      // Whole-word match: a bare substring test selects lenses on accidental
+      // fragments ("ui" inside "requires", "auth" inside "author" — #4579).
+      const escaped = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      if (new RegExp(`\\b${escaped}\\b`).test(contentToSearch)) {
         keywordMatch = true;
         break;
       }
@@ -430,8 +728,10 @@ export async function selectAudits({
       changedFilesCount: changedFiles.length,
       // The ref the change set was actually diffed against. Epic-mode callers
       // assert this matches the requested Epic branch (Story #3362) so a
-      // mis-pinned diff never reaches the audit-lens selector silently.
-      resolvedRef: headRef,
+      // mis-pinned diff never reaches the audit-lens selector silently. `null`
+      // on the injected path: no ref was diffed, and naming one would invite
+      // exactly that assertion to pass against a diff nobody took.
+      resolvedRef: hasInjectedChangedFiles ? null : headRef,
       ticketTitle: ticket.title,
     },
   };

package/.agents/scripts/lib/baselines/kinds/maintainability.js

@@ -53,20 +53,9 @@ export const MAINTAINABILITY_EXCLUSIONS = Object.freeze(
     // escomplex: same "pattern" parse failure as acceptance-spec-reconciler;
     // both files share the lifecycle-lint regex-driven scan helpers.
     '.agents/scripts/check-lifecycle-lint.js',
-    // escomplex: "traveler[node.type] is not a function" — AST node type the
-    // upstream traveler table is missing (top-level await / private fields).
-    '.agents/scripts/lib/orchestration/epic-cleanup.js',
-    // escomplex: same "traveler[node.type] is not a function" — emitted by
-    // the spec-reconciler's `async` operator-comment IIFE.
-    '.agents/scripts/lib/orchestration/epic-spec-reconciler-ops.js',
     // escomplex: "this[node.callee.type] is not a function" — the cyclomatic
     // visitor lacks a handler for one of the quality-watch CLI's call shapes.
     '.agents/scripts/quality-watch.js',
-    // escomplex: parse-fails (MI=0) on the spec-freshness phase's optional-
-    // chained destructuring fallthrough. Same upstream family as the other
-    // "pattern" / destructuring failures; carve-out so the phase split of
-    // epic-plan-spec doesn't poison the global rollup.
-    '.agents/scripts/lib/orchestration/epic-plan-spec/phases/spec-freshness.js',
     // escomplex: "Cannot read properties of undefined (reading 'pattern')" —
     // the audit-to-stories parser reuses the same regex-property scan
     // patterns as acceptance-spec-reconciler.

package/.agents/scripts/lib/bootstrap/ci-workflow-template.js

@@ -13,14 +13,18 @@
  *      framework default at the next bump. The push-to-main job still passes
  *      `--full-scope` so a self-diff doesn't degrade to "no files in diff".
  *
- *   2. **Pass `--epic-ref` where the firing site is Epic-aware.** Inside
- *      `/deliver` the close-validation chain already threads
- *      `--epic-ref epic/<id>`; on CI the equivalent surface is the PR's
- *      base branch. The template wires `--epic-ref ${EPIC_REF}` through an
- *      env var the workflow computes from `github.head_ref` (story-N
- *      branches name their Epic in the PR title or via the dispatch
- *      manifest). When `EPIC_REF` is empty, both gates fall through to the
- *      `main`-tracked baseline — so the env-var expansion is always safe.
+ *   2. **Pin the baseline read to the PR's base branch via `BASELINE_REF`.**
+ *      Inside `/deliver` the close-validation chain sets the same env var
+ *      (`close-validation/gates.js` → `BASELINE_REF: origin/<baseBranch>`);
+ *      on CI the equivalent surface is the PR's base branch. This is an
+ *      ENV VAR, not a CLI flag: `check-baselines.js` resolves it through
+ *      `resolveDispatchScope`, and the `--epic-ref` flag this template used
+ *      to pass never existed on it — it was left over from the separate
+ *      `check-crap.js` / `check-maintainability.js` CLIs that were unified
+ *      away, and it named the ref `epic/<base>`, a branch the Story-only
+ *      model never creates. When `BASELINE_REF` is empty (push-to-base,
+ *      where there is no base to compare against) both gates fall through to
+ *      the working-tree baseline, so the expansion is always safe.
  *
  * The renderer is a pure string template so the integration test can assert
  * on its exact shape without instantiating a YAML parser.
@@ -61,19 +65,15 @@ export function renderCiWorkflow(opts = {}) {
         # Diff-scoped via the framework default (Story #1394 flipped
         # --changed-since to '${baseRef}'). On PRs we let the default win;
         # on push-to-main we pass --full-scope so a self-diff doesn't
-        # collapse to an empty file set. EPIC_REF is set when the head ref
-        # points at a story branch under an Epic — the gate then reads the
-        # per-Epic baseline snapshot via baseline-loader.readBaselineAtRef.
+        # collapse to an empty file set. BASELINE_REF makes the gate read
+        # the baseline at the base branch tip via
+        # baseline-loader.readBaselineAtRef.
         env:
-          EPIC_REF: \${{ env.EPIC_REF }}
+          BASELINE_REF: \${{ env.BASELINE_REF }}
         run: |
           mkdir -p temp
           if [[ "\${{ github.event_name }}" == "pull_request" ]]; then
-            if [[ -n "\${EPIC_REF}" ]]; then
-              npm run crap:check -- --epic-ref "\${EPIC_REF}" --json temp/crap-report.json
-            else
-              npm run crap:check -- --json temp/crap-report.json
-            fi
+            npm run crap:check -- --json temp/crap-report.json
           else
             npm run crap:check -- --full-scope --json temp/crap-report.json
           fi
@@ -112,15 +112,14 @@ jobs:
     permissions:
       contents: read
     env:
-      # Story #1120: when the PR head ref names an Epic story branch
-      # (story-N or story/epic-<id>/<n>), the gate CLIs read the canonical
-      # main baseline at the Epic branch HEAD via --epic-ref (git show).
-      # Empty when the head ref is not an Epic story branch — both gates
-      # fall through to the working-tree baseline, so the env-var
-      # expansion is always safe. Per-epic ratchet snapshots themselves
-      # live under temp/epic/<id>/baselines/ (Story #1467) — ephemeral
-      # scratch state, never read by this CI gate.
-      EPIC_REF: \${{ github.head_ref && contains(github.head_ref, 'story') && format('epic/{0}', github.event.pull_request.base.ref) || '' }}
+      # Story #1120: on a PR the gate CLIs read the canonical baseline at
+      # the BASE branch tip via --baseline-ref (git show), not from the
+      # PR head's working tree — a branch that edited its own baseline
+      # must not be allowed to grade itself against the edit.
+      # Empty on push-to-${baseRef} (there is no base to compare against),
+      # where both gates fall through to the working-tree baseline, so the
+      # env-var expansion is always safe.
+      BASELINE_REF: \${{ github.event_name == 'pull_request' && format('origin/{0}', github.event.pull_request.base.ref) || '' }}
       BASE_REF: ${baseRef}
     steps:
       - name: Checkout Code
@@ -147,16 +146,12 @@ jobs:
         # the project's BASE_REF, so PRs no longer pass --changed-since
         # explicitly. push-to-${baseRef} runs with --full-scope so the
         # diff-scoped default doesn't degrade to a self-diff (= empty file
-        # set). EPIC_REF carries the per-Epic snapshot when present.
+        # set). BASELINE_REF pins the baseline read to the base branch tip.
         env:
-          EPIC_REF: \${{ env.EPIC_REF }}
+          BASELINE_REF: \${{ env.BASELINE_REF }}
         run: |
           if [[ "\${{ github.event_name }}" == "pull_request" ]]; then
-            if [[ -n "\${EPIC_REF}" ]]; then
-              npm run maintainability:check -- --epic-ref "\${EPIC_REF}"
-            else
-              npm run maintainability:check
-            fi
+            npm run maintainability:check
           else
             npm run maintainability:check -- --full-scope
           fi

package/.agents/scripts/lib/bootstrap/manifest.js

@@ -110,9 +110,14 @@ export function buildMutationManifest(ctx = {}) {
   const entries = [];
 
   // --- ide-wiring -------------------------------------------------------
-  // Claude Code / IDE integration: the system-prompt import, the
-  // UserPromptSubmit sync hook, the generated flat command surface, and the
-  // .gitignore entry that keeps the generated tree out of git.
+  // Claude Code / IDE integration: the system-prompt import, the generated
+  // flat command surface, and the .gitignore entry that keeps the
+  // generated tree out of git. (Story #4527/#4530: the UserPromptSubmit
+  // per-prompt re-sync hook entry was removed alongside the hook itself —
+  // it raced the harness's own read of the same directory and reported
+  // "0 file(s) synced" on effectively every invocation; the real sync
+  // points — `prepare`, `mandrel sync`/`update`, doctor's
+  // `commands-in-sync` — already cover every case.)
   entries.push(
     {
       phaseGroup: PHASE_GROUPS.IDE_WIRING,
@@ -122,14 +127,6 @@ export function buildMutationManifest(ctx = {}) {
         'Wire the @.agents/instructions.md system-prompt import so Claude Code hydrates the framework on cold start.',
       reversible: true,
     },
-    {
-      phaseGroup: PHASE_GROUPS.IDE_WIRING,
-      target: rel('.claude', 'settings.json'),
-      action: 'merge',
-      detail:
-        'Add the UserPromptSubmit re-sync hook so the /<command> tree stays current.',
-      reversible: true,
-    },
     {
       phaseGroup: PHASE_GROUPS.IDE_WIRING,
       target: rel('.claude', 'commands'),