@event4u/agent-config 9.35.0 → 9.36.0

package/docs/contracts/settings-classes.md

@@ -180,8 +180,8 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 27 |
 | B — consent | 3 |
-| C — guarded | 112 |
-| **Total** | **142** |
+| C — guarded | 114 |
+| **Total** | **144** |
 
 The total is every leaf in the template, where *leaf* means anything that is not
 a **non-empty** map. An empty map (like the former `subagents.host_capabilities: {}`) is a real
@@ -236,6 +236,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `project.pr_template` | C | `.github/pull_request_template.md` | filesystem path whose contents reach an outbound PR |
 | `project.upstream_repo` | C | `""` | destination of outbound improvement PRs |
 | `project.improvement_pr_branch_prefix` | A | `improve/agent-` | branch-name cosmetics |
+| `project.audience` | C | `public` | C-test 4 — it governs the agent's own reasoning discipline: `self` makes the § 8-pre demand gate inert. Who a project is built for is a fact only its maintainer knows, so the agent never infers it and never asks; hand-edit or the GUI write route. The default is today's behaviour, so an install that never sets it is unchanged |
 | `github.pr_reply_method` | A | `create_review_comment` | picks between two endpoints of one operation |
 | `augment.rules_use_symlinks` | A | `false` | reversible install mechanics |
 | `eloquent.access_style` | A | `getters_setters` | code convention |
@@ -324,6 +325,7 @@ Rows follow template order, so a diff against the template reads straight down.
 | `hooks.injection_scan.enabled` | C | `false` | the prompt-injection scanner |
 | `hooks.rtk_wrap.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.design_slop.enabled` | C | `false` | configures code that runs on every tool call |
+| `hooks.ui_route_nudge.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call |
 | `hooks.turn_end_gate.enabled` | C | `false` | arms the only concern that can REFUSE a turn-end; an agent must never be able to switch its own delivery gate on |
 | `hooks.turn_end_gate.promissory` | C | `true` | which refusal the turn-end gate may raise; inert while the master switch is off |

package/docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md

@@ -108,6 +108,22 @@ feature" ask, before checks 8a–8c. It is a three-question advisor, NOT a
 product-management framework — surface it in one short block, then proceed on
 the user's answer (never block; `improve-before-implement`'s golden rule holds).
 
+**Read the addressee before the questions.** The ladder below measures **market
+demand**, and market demand is a meaningful quantity only where a market is
+intended. Who the project is built for is `project.audience` — resolve it with
+`agent-config settings:get project.audience`, which reports the value and the
+file it came from, rather than opening one file. An absent value resolves to
+`public`: this package has no defaults layer that supplies one at read time, so
+absent means *nobody said*, and the conservative reading of that is the shipped
+default.
+
+| `project.audience` | What 8-pre does |
+|---|---|
+| `self` | **Inert.** One line — "demand gate skipped (audience: self)" — then straight to 8a. No deferral, no demand question. |
+| `internal` | Question 2 only ("what breaks without it?"). Questions 1 and 3 are already answered — the requester is the team. |
+| `client` | The requester is the client, not a segment. Question 2 survives; 1 and 3 are answered by the engagement. |
+| `public` | **Today's behaviour, unchanged** — all three questions and the full ladder. |
+
 Three questions:
 
 1. **Who requested this?** (a real user / segment, or an internal hunch?)
@@ -118,16 +134,42 @@ Map the answers to a compressed feature-demand hierarchy and recommend:
 
 | Level | Signal | Recommendation |
 |---|---|---|
+| L-self | The maintainer needs it for their own work — no user population is intended | **Build** |
 | L0 | Founder/agent anxiety — "it feels missing" | **Defer** — validate demand first |
 | L1 | One anecdotal request, no pattern | **Defer** — watch for repetition |
 | L2 | Repeated requests, no measured impact | **Validate** — instrument before building |
 | L3 | Blocks activation/retention for a real segment | **Build** |
 | L4 | Users are churning / deals lost without it | **Build now** |
 
-Build only at **L3–L4**; L0–L2 get a defer/validate recommendation with the
-one missing evidence named. This is advisory — the user decides; a "just build
-it" answer proceeds immediately to 8a. No network, no case-memory API (the
-source's remote lookup is dropped — a lethal-trifecta egress concern).
+Build at **L-self**, **L3**, or **L4**; L0–L2 get a defer/validate
+recommendation with the one missing evidence named.
+
+`L-self` is not a weaker L3. L3 and L4 are defined exclusively over third-party
+users — "a real segment", "users are churning" — so a project with no intended
+user population cannot reach either, not because it is bad but because the scale
+has no value for it. Its ceiling on the L0–L4 ladder is L0, whose recommendation
+is *defer*, which would defer a single-user tool forever. `L-self` is the level
+that ladder is missing, not a discount on the ones it has.
+
+**The artefact consequence.** At `L-self`, or at `audience: self` / `internal`,
+never write a roadmap gate, exit criterion, or opening condition that names an
+external user population, a market, or an external measurement. A gate whose
+condition depends on a quantity the project cannot produce is not a gate — it is
+a permanent no in the shape of an answer. This is where the advisory reading
+actually breaks: in conversation "never block" holds, but when a roadmap needs a
+falsifiable opening condition the agent reaches for the only vocabulary it has
+for *should this exist*, and an advisory ladder becomes a number, then a gate.
+
+This is advisory — the user decides; a "just build it" answer proceeds
+immediately to 8a. No network, no case-memory API (the source's remote lookup is
+dropped — a lethal-trifecta egress concern).
+
+**Enforcement, honestly.** Nothing reads `project.audience` to change what this
+section does. § 8-pre is prose and the branch table above is model-carried —
+the same honesty boundary `security-sensitive-stop` and `untrusted-input-defense`
+state for their own obligations. The one deterministic backstop sits downstream,
+where the damage actually lands: `lint_roadmap_complexity` warns when a roadmap
+gate rests on an external population.
 
 ### 8a. Is the request clear?
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.35.0",
+    "version": "9.36.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,
@@ -68,7 +68,7 @@
         "build:install-bundle": "esbuild src/scripts/install.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/install/install.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "build:mcp-bundle": "esbuild src/scripts/mcp_server/__main__.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/mcp/server.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_MCP_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
-        "build:cli-delegate": "esbuild src/scripts/_cli/cmd_*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
+        "build:cli-delegate": "esbuild src/scripts/_cli/cmd_*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --define:__AGENT_CONFIG_CLI_DELEGATE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:ui": "vite build",
         "tokens:build": "node tokens/build-ac.mjs && node tokens/build-as.mjs",
         "tokens:check": "node tokens/build-ac.mjs --check && node tokens/build-as.mjs --check && node tokens/check-contrast.mjs",

package/src/agent-src/templates/AGENTS.md

@@ -14,7 +14,7 @@
 ## Pointers
 
 - **Filling out this AGENTS.md** — section templates, capability bullets, multi-agent entry flow, monorepo layout: [`consumer-agents-md-guide`](.augment/contexts/contracts/consumer-agents-md-guide.md).
-- **Behavior rules (always active)** — [`.augment/rules/`](.augment/rules/). Kernel rules are **immutable**; tighten only via the override registry.
+- **Behavior rules** (9 always-on; rest routed) — [`.augment/rules/`](.augment/rules/). Kernel rules are **immutable**; tighten only via the override registry.
 - **Skills (on-demand expertise)** — domain skills surfaced by description, invoked on trigger match: [`.augment/skills/`](.augment/skills/).
 - **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).
 - **Project-specific docs** — your own architecture notes, roadmaps, sessions, contexts: [`agents/`](agents/).

package/src/config/agent-settings.template.yml

@@ -355,6 +355,24 @@ project:
   # Branch prefix for improvement PRs
   improvement_pr_branch_prefix: "improve/agent-"
 
+  # Who this project is built for. Read by the demand gate
+  # (docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md
+  # § 8-pre), whose L0-L4 ladder measures MARKET demand and is therefore
+  # meaningless where no market is intended.
+  #   self     -> a tool its maintainer builds for themselves. The demand gate
+  #               is inert; work is classified L-self (build), never deferred
+  #               for lack of a user population that is not wanted.
+  #   internal -> a team / company internal tool. Only "what breaks without
+  #               it?" survives; the requester is known.
+  #   client   -> built for a named client. The client is the requester, not a
+  #               market segment.
+  #   public   -> a product with an intended market. Full three-question gate
+  #               and the full ladder.
+  # Default `public` = the behaviour every install had before this key existed.
+  # Absent resolves to `public` for the same reason: this package has no
+  # defaults layer, so absent means nobody said.
+  audience: public
+
 # --- GitHub integration ---
 github:
   # API method for replying to PR review comments
@@ -1248,6 +1266,20 @@ hooks:
   design_slop:
     enabled: false
 
+  # PreToolUse UI-route nudge (road-to-frontend-skill-application Phase 4).
+  # Default-OFF. When enabled, a Write/Edit to a UI surface with no design
+  # consultation latched this session WARNS (exit 2, never blocks) naming the
+  # route: run existing-ui-audit, then the fe-design loop. A read or search
+  # touching fe-design / existing-ui-audit / design-review / design-intelligence
+  # latches consultation and silences it for the rest of the session, so the
+  # agent that did the right thing is never nagged. Anti-loop: at most 2 nudges
+  # per session. It does NOT read the two UI rules: the UI-surface decision
+  # comes from _lib/ui_surface.ts, so this runs parallel to them rather than
+  # consuming their triggers. Host-limited (pre_tool_use fires on ~2-3 hosts) —
+  # elsewhere the obligation stays model-carried, as the two UI rules declare.
+  ui_route_nudge:
+    enabled: false
+
   # PreToolUse code-graph nudge (ADR-124 Phase 4). Default-OFF. When enabled
   # AND a native code-graph engine has built a cache (or the repo ships a
   # graph.json / SCIP index), WARNS once per session (exit 2, never blocks) as

package/src/config/gate-coverage.yml

@@ -168,6 +168,18 @@ gates:
     corpus: "src/rules/*.md frontmatters (111 at baseline)"
     status: enforced
 
+  - id: lint_rule_skill_pack_reach
+    argv: ["--quiet"]
+    min_scanned: 90
+    corpus: "src/rules/*.md frontmatters joined against src/skills packs and the pack registry (116 rules at baseline)"
+    status: enforced
+    note: >
+      Advisory on findings, enforced on COVERAGE: the gate exits 0 while its
+      unreachable-route set is non-empty (12 at introduction), so only this
+      floor can catch it going blind. A collapse below 90 would mean it stopped
+      reading src/rules, which is exactly the shape that would make "0 findings"
+      read as clean.
+
   - id: check_condensation
     argv: []
     min_scanned: 380

package/src/scripts/_cli/cmd_doctor.ts

@@ -3591,10 +3591,42 @@ function main(argv: string[] | null = null): number {
 
 // --- CLI entry ---
 
+/**
+ * Defined by `build:cli-delegate` only — see `cmd_session_recycle.ts` for why a
+ * single "am I inside a bundle" flag cannot answer "may I run".
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
 function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    // Inlined into the installer / hook / MCP bundle: never auto-run. This
+    // file previously carried no such guard while its comment described the
+    // pairing, so the four siblings documented one mechanism and implemented
+    // two.
+    if (bundled && !cliDelegate) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (cliDelegate) {
+        // `--splitting` moves this module's body into a shared chunk, so the URL
+        // comparison below weighs the CHUNK against `argv[1]` and never matches.
+        // `agent-config doctor` shipped producing zero bytes and exit 0 for
+        // exactly that reason — a diagnostic reporting success while saying
+        // nothing. The invoked file name is the reliable signal inside this
+        // bundle; the delegate smoke test keeps the literal honest.
+        if (path.basename(process.argv[1], '.js') === 'cmd_doctor') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_cli/cmd_migrate.ts

@@ -932,14 +932,37 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // build's `--define`) disables the auto-run there; under tsx/node it is
 // undefined, so `typeof` short-circuits and the standalone CLI guard fires
 // normally.
+// The sentinel above is true in EVERY esbuild target, `build:cli-delegate`
+// included — and there this file is the entry, so refusing on it refused to run
+// the bundle built to run it: `dist/cli-delegate/cmd_migrate.js` produced zero
+// bytes and exit 0, and `agent-config migrate` reported success while doing
+// nothing. `__AGENT_CONFIG_CLI_DELEGATE__` is defined by that one build only, so
+// the pair distinguishes "inlined into the installer" (never run) from "this
+// bundle's own target" (run, subject to the entry check below).
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
-const _bundled =
-    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+const _inForeignBundle =
+    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' &&
+    __AGENT_CONFIG_BUNDLE__ &&
+    !(typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__);
 const _HERE = fileURLToPath(import.meta.url);
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__) {
+        // `--splitting` moves this module's body into a shared chunk, so the URL
+        // comparison below weighs the CHUNK against `argv[1]` and never matches —
+        // `agent-config migrate` shipped producing zero bytes and exit 0. The
+        // invoked file name is the reliable signal inside this bundle.
+        if (path.basename(process.argv[1], '.js') === 'cmd_migrate') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;
@@ -958,7 +981,7 @@ function _isCliEntry(): boolean {
     }
 }
 
-if (!_bundled && (_isCliEntry() || process.argv[1] === _HERE)) {
+if (!_inForeignBundle && (_isCliEntry() || process.argv[1] === _HERE)) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_refresh.ts

@@ -449,10 +449,39 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 
 // --- CLI entry ---
 
+/**
+ * Defined by `build:cli-delegate` only — see `cmd_session_recycle.ts` for why the
+ * URL comparison below cannot decide this inside that bundle.
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
 function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    // Inlined into the installer / hook / MCP bundle: never auto-run. This
+    // file previously carried no such guard while its comment described the
+    // pairing, so the four siblings documented one mechanism and implemented
+    // two.
+    if (bundled && !cliDelegate) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (cliDelegate) {
+        // Found by running every delegate bundle, not by reading: `--splitting`
+        // had moved this body into a shared chunk too, so `agent-config refresh`
+        // was a silent exit 0 like doctor, migrate and session:recycle.
+        if (path.basename(process.argv[1], '.js') === 'cmd_refresh') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -252,11 +252,49 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return result.code;
 }
 
-// Bundle-safety: never auto-run when inlined into an esbuild bundle.
+/**
+ * Bundle-safety: never auto-run when inlined into SOMEONE ELSE'S bundle.
+ *
+ * `__AGENT_CONFIG_BUNDLE__` alone cannot express that. All four esbuild targets
+ * define it, `build:cli-delegate` included — and that bundle's entry points ARE
+ * these files, so a guard refusing on the flag refuses to run the very bundle
+ * built to run it. That shipped: `dist/cli-delegate/cmd_session_recycle.js`
+ * produced zero bytes and exit 0 on every installed copy, so
+ * `agent-config session:recycle` reported success while writing no envelope.
+ * `cmd_doctor` and `cmd_migrate` carried the same guard and were dead the same
+ * way.
+ *
+ * `__AGENT_CONFIG_CLI_DELEGATE__` is defined by that one build only, so the pair
+ * says what a single flag could not: inlined elsewhere (install / hook / MCP
+ * bundle) → never run; this bundle's own target → run, and let the `argv[1]`
+ * comparison below decide whether THIS module is the entry or a shared chunk
+ * pulled in beside it.
+ */
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
 function _isCliEntry(): boolean {
-    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    if (bundled && !cliDelegate) return false;
     if (process.argv[1] === undefined) return false;
+    if (cliDelegate) {
+        // `--splitting` turns the entry file into a re-export shim and moves this
+        // module's body into a shared chunk, where `import.meta.url` is the
+        // CHUNK's url and can never equal `argv[1]`. The comparison below then
+        // silently never fires — which is why two sibling commands shipped dead
+        // while others worked by accident, purely by where esbuild happened to
+        // place their code. Inside this bundle the invoked file name is the only
+        // reliable signal; the smoke test over every delegate bundle is what
+        // keeps this literal honest if the file is ever renamed.
+        if (path.basename(process.argv[1], '.js') === 'cmd_session_recycle') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
     try {
         return (

package/src/scripts/_lib/hook_settings.ts

@@ -0,0 +1,79 @@
+/**
+ * hook_settings — read a `hooks.<section>.enabled` flag out of
+ * `.agent-settings.yml` without dragging a YAML parser into a hook.
+ *
+ * Every default-OFF hook needs the same two-level lookup, and the tree already
+ * carries two hand-rolled copies of it (`code_graph_nudge_hook.enabled` and the
+ * equivalent inside `design_slop_hook`). Adding a third copy for the route
+ * nudge is what this file prevents; the two existing copies are pre-existing
+ * duplication and are deliberately left alone — folding them in is a separate,
+ * behaviour-neutral change, not something to smuggle into a feature diff.
+ *
+ * Fail-closed on the flag, fail-open on the read: an unreadable or malformed
+ * settings file returns `false`, which keeps a default-OFF hook off. A hook
+ * that turned itself ON because it could not read a file would be the worst
+ * possible failure mode for an opt-in nudge.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const SETTINGS_FILE = '.agent-settings.yml';
+
+/**
+ * True when `.agent-settings.yml` under `root` carries
+ * `hooks:\n  <section>:\n    enabled: true`.
+ *
+ * Deliberately indentation-shaped rather than a real parse: the same shape the
+ * existing hooks rely on, and a hook must never fail a tool call because a
+ * dependency could not load.
+ */
+export function hookSectionEnabled(root: string, section: string): boolean {
+    const file = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(file).isFile()) return false;
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return false;
+    }
+
+    const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const sectionPattern = new RegExp(`^(\\s+)${escaped}\\s*:\\s*$`);
+    let inHooks = false;
+    /** Indent width of the matched section header; null while outside it. */
+    let sectionIndent: number | null = null;
+
+    const indentOf = (line: string): number => line.length - line.replace(/^\s+/, '').length;
+
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+
+        // A non-indented line closes both scopes and may open `hooks:`.
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inHooks = /^hooks\s*:\s*$/.test(line);
+            sectionIndent = null;
+            continue;
+        }
+
+        if (inHooks) {
+            const opened = sectionPattern.exec(line);
+            if (opened) {
+                // Remember the ACTUAL indent rather than assuming two spaces.
+                // The previous version closed the section on any line indented
+                // <= 3, so on a 4-space file a sibling section never closed and
+                // a default-OFF hook could read another section's enabled: true.
+                sectionIndent = opened[1]!.length;
+                continue;
+            }
+            // A key at or above the section header's own depth closes it.
+            if (sectionIndent !== null && indentOf(line) <= sectionIndent) {
+                sectionIndent = null;
+            }
+        }
+
+        if (sectionIndent !== null && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+    }
+
+    return false;
+}

package/src/scripts/_lib/ui_surface.ts

@@ -0,0 +1,97 @@
+/**
+ * ui_surface — the ONE definition of "this path is a UI surface".
+ *
+ * Three consumers need the same answer and were about to disagree about it:
+ * the anti-slop PreToolUse hook (which had the only copy), the UI-turn
+ * definition the catalogue analyzer counts against, and the route nudge.
+ * A UI-turn rate measured against one extension set and a nudge fired against
+ * another would produce a consultation rate that no fix could ever move,
+ * because the denominator and the trigger would be different populations.
+ *
+ * `.blade.php` is deliberately part of the set and was absent from the hook's
+ * original regex: a two-part extension does not match a `\.(…)$` alternation,
+ * so every Blade template — the single largest UI surface in a Laravel
+ * consumer — read as a non-UI file. That is why `isUiPath` matches on the
+ * path tail rather than on `path.extname`, which returns `.php` for
+ * `page.blade.php` and would silently reproduce the same hole.
+ */
+
+/** Single-segment UI extensions, without the leading dot. */
+export const UI_EXTENSIONS = [
+    'html',
+    'htm',
+    'css',
+    'scss',
+    'sass',
+    'less',
+    'vue',
+    'svelte',
+    'astro',
+    'jsx',
+    'tsx',
+] as const;
+
+/**
+ * Multi-segment UI suffixes. These cannot be expressed as an extension
+ * alternation — `path.extname('x.blade.php')` is `.php`.
+ */
+export const UI_COMPOUND_SUFFIXES = ['.blade.php'] as const;
+
+/** Equivalent to the historical hook regex, plus the compound suffixes. */
+export const UI_EXT = new RegExp(
+    `(\\.(${UI_EXTENSIONS.join('|')})|${UI_COMPOUND_SUFFIXES.map((s) => s.replace(/\./g, '\\.')).join('|')})$`,
+    'i',
+);
+
+/** True when `p` names a file on a UI surface. Case-insensitive. */
+export function isUiPath(p: string): boolean {
+    return UI_EXT.test(p);
+}
+
+/**
+ * Directory fragments that mark a UI tree across frameworks. The two UI rules
+ * carried only the Laravel pair (`resources/views/`, `resources/js/`), so a
+ * React, Vue, Next or Svelte consumer writing to `src/components/` matched no
+ * path trigger at all. Kept as fragments, not anchored prefixes: a consumer's
+ * UI tree is rarely at the repo root.
+ *
+ * `app/` is deliberately NOT in this list although it is the Next.js router
+ * directory. In a Laravel consumer `app/` is the entire backend, so the
+ * fragment would fire on every controller, model and job — a trigger that
+ * over-fires on the largest directory of a whole ecosystem is worse than the
+ * gap it closes. Next.js route files are caught by extension instead
+ * (`page.tsx`, `layout.tsx` match `isUiPath`), which is the precise signal.
+ */
+export const UI_PATH_FRAGMENTS = [
+    'resources/views/',
+    'resources/js/',
+    // `components/` already subsumes `src/components/` under substring
+    // matching — listing both here would be dead weight. The rules' own
+    // `path_prefix` list keeps both because matching there is anchored.
+    'components/',
+    'pages/',
+] as const;
+
+/**
+ * Fragments that sit INSIDE a UI tree and are not UI. Checked first, because a
+ * substring fragment cannot express "pages/ but not pages/api/" on its own —
+ * and `pages/api/` is server-only Next.js code, the exact over-fire the `app/`
+ * exclusion above exists to avoid. Leaving it in would have put backend files
+ * in the pre-registered UI-turn denominator, which is worse than the nudge
+ * firing on them: a rate is harder to un-break than a warning.
+ */
+export const UI_TREE_EXCLUSIONS = ['pages/api/'] as const;
+
+/**
+ * True when `p` sits inside a conventional UI tree.
+ *
+ * Note this does NOT require a UI extension — that is the point: a `.js` file
+ * under `resources/js/` is UI. The cost is that a non-code file in a UI tree
+ * (a README, a fixture) also matches; callers that need the narrower answer
+ * combine this with `isUiPath`.
+ */
+export function isUiTreePath(p: string): boolean {
+    const normalized = p.replace(/\\/g, '/').toLowerCase();
+    if (UI_TREE_EXCLUSIONS.some((fragment) => normalized.includes(fragment))) return false;
+    return UI_PATH_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+}