@event4u/agent-config 14.10.0 → 14.12.0

package/src/config/surface-matrix.yml

@@ -167,8 +167,27 @@ tools:
   opencode:
     surface: projection
     scope_path: "~/.opencode/"
-    hooks: none
-    notes: Plain projection (skill bundle); no plugin channel.
+    # CORRECTED 2026-08-24: this row read `hooks: none` and "no plugin channel",
+    # and that was wrong on a shipped host. @opencode-ai/plugin@1.18.21 exposes
+    # `permission.ask`, `tool.execute.before`, `shell.env` and
+    # `experimental.chat.system.transform`. Evidence, with the pin and the type
+    # signatures: agents/evidence/analysis/opencode-plugin-api-verification.md
+    #
+    # `plugin`, and the value is the HOST's channel type rather than a claim that
+    # this suite binds it. An `unbound` value was tried first and rejected by
+    # lint_surface_matrix's enum {managed-settings-block, settings-hooks-opt-in,
+    # plugin, none} — correctly: every other row here describes what the host
+    # offers, and whether this package binds it is hook_manifest.yaml's business,
+    # where opencode still has ZERO entries. The notes below carry the
+    # not-bound-here fact so the row cannot be read as a delivered capability.
+    hooks: plugin
+    notes: >-
+      Plain projection (skill bundle) today. Upstream DOES expose a plugin
+      channel with a real deny (`permission.ask` -> status "deny"), but the deny
+      is narrower than a pre-tool slot: `tool.execute.before` is mutate-only
+      (`{args}`, no refusal), so a concern can only refuse where opencode already
+      stops to ask, and the `Permission` input carries no tool name, arguments or
+      path as typed fields. Nothing in this package is bound to it.
 
   trae:
     surface: projection

package/src/config/web-launch-readiness.json

@@ -0,0 +1,188 @@
+{
+  "_comment": "Site-type axis for the web-launch-readiness skill (road-to-web-launch-readiness 0.2). The design directive this file exists to enforce is CONDITIONAL, NOT FLAT: a check that applies everywhere is a check that gets ignored somewhere. Every entry declares which site types it applies to, so a SaaS app is never asked for opening hours and a docs site is never asked for a cookie banner it does not set. REGISTERED BEFORE ANY SKILL CODE EXISTS, which is the point of Phase 0: the axis is a decision, and deciding it after writing the checks would let the checks pick their own scope. Nothing reads this file yet -- the skill is gated behind b-estate-decision-web-launch.",
+  "schema_version": 1,
+  "registered_at": "2026-08-25",
+  "owner": "maintainer",
+  "review_by": "2027-08-25",
+  "site_types": {
+    "_comment": "The closed enum. A check may not name a type outside it, and a type carries no checks until one lists it -- so adding a type is inert until a check opts in, and removing one is caught by the schema test rather than silently emptying a check's scope.",
+    "values": [
+      "local-business",
+      "marketing-site",
+      "saas-app",
+      "docs",
+      "internal-tool"
+    ]
+  },
+  "tiers": {
+    "_comment": "Report order, and it is the output contract rather than a label: critical first, situational last. A finding's tier is a property of the FINDING, not of the reader's patience -- a staging noindex on a production marketing site is critical whether or not the reader has time for it.",
+    "values": [
+      "critical",
+      "high",
+      "medium",
+      "situational"
+    ]
+  },
+  "checks": [
+    {
+      "id": "staging-noindex-leftover",
+      "title": "A staging `noindex` or `robots.txt` disallow survived into production",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs"
+      ],
+      "tier": "critical",
+      "why": "The defect class with ZERO coverage in the estate (G0: `robots` 0 files, `noindex` 0 files) and the highest cost: the site ships, works, looks correct, and is invisible to search. Nothing in the tree looks for it today.",
+      "remediation": "Remove the `noindex` meta tag and the blanket `Disallow: /` from the production build; keep them behind the staging environment's own config rather than in shared source.",
+      "verification": "`curl -sI <prod-url> | grep -i x-robots-tag` returns nothing, `curl -s <prod-url>/robots.txt` carries no blanket disallow, and the rendered HTML has no `noindex` meta."
+    },
+    {
+      "id": "https-enforcement",
+      "title": "HTTP is redirected to HTTPS and no asset is loaded over plain HTTP",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs"
+      ],
+      "tier": "critical",
+      "why": "A mixed-content asset silently breaks the padlock and, on a form page, ships a credential over plaintext. Browsers block some of it and load the rest, so the page LOOKS fine while the guarantee is gone -- which is why this is critical rather than high.",
+      "remediation": "Serve every asset over https:// or protocol-relative paths, and redirect http:// at the edge. Never hard-code an http:// origin you control.",
+      "verification": "`curl -sI http://<prod-host>/` returns a 301/308 to https, and the browser console shows no mixed-content warning on the heaviest page."
+    },
+    {
+      "id": "custom-error-route",
+      "title": "A custom 404 route exists and is reachable",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs"
+      ],
+      "tier": "high",
+      "why": "A framework default error page leaks stack shape and loses the visitor. `404` matches 19 files in the estate, all HTTP-status tables -- none is a launch check.",
+      "remediation": "Add the framework's custom 404 route and give it a link back into the site.",
+      "verification": "`curl -s -o /dev/null -w '%{http_code}' <prod-url>/<random-path>` returns 404 and the body is the custom page, not the framework default."
+    },
+    {
+      "id": "per-route-metadata",
+      "title": "Every indexable route carries a title and a meta description",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "docs"
+      ],
+      "tier": "high",
+      "why": "`meta description` matches 0 files. Excluded for `saas-app` and `internal-tool` on purpose: an authenticated app's routes are not indexed, so per-route descriptions are work with no consumer.",
+      "remediation": "Add title and description to each route's metadata export; a shared default is a fallback, not a per-route value.",
+      "verification": "Fetch each route in the sitemap and assert a non-empty, non-duplicated title and description."
+    },
+    {
+      "id": "image-alternative-text",
+      "title": "Content images carry alternative text",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs",
+        "internal-tool"
+      ],
+      "tier": "high",
+      "why": "The one check that applies to every type, including internal tools -- an internal user with a screen reader is still a user. `alt text` matches 7 files, all accessibility prose rather than a launch check.",
+      "remediation": "Add `alt` to content images; decorative images take `alt=\"\"` explicitly rather than being left without the attribute.",
+      "verification": "Parse the rendered HTML and assert every `<img>` has an `alt` attribute, empty or not."
+    },
+    {
+      "id": "document-head-basics",
+      "title": "Every page declares lang, charset and viewport",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app",
+        "docs",
+        "internal-tool"
+      ],
+      "tier": "high",
+      "why": "A missing `lang` makes a screen reader guess the pronunciation of the whole page; a missing viewport makes a phone render a desktop layout at 320px. Both are one line, both are invisible on the developer's machine, and both are the kind of default a framework template silently drops when a page is hand-written.",
+      "remediation": "`<html lang=\"..\">`, `<meta charset=\"utf-8\">` and `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">` in the shared layout, not per page.",
+      "verification": "View source on two unrelated routes and confirm all three are present on both -- one route proves the layout, two prove it is the layout and not a copy."
+    },
+    {
+      "id": "canonical-and-sitemap-coherence",
+      "title": "Canonical URLs, sitemap and robots.txt agree with each other",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "docs"
+      ],
+      "tier": "medium",
+      "why": "Three sources that can disagree silently: a sitemap listing a route whose canonical points elsewhere, or a robots disallow on a route the sitemap advertises. Note `canonical` matches 115 files in this estate in a completely different sense (\"the canonical rule\"), so its count is NOT coverage evidence.",
+      "remediation": "Make the canonical the same URL the sitemap lists; remove sitemap entries that robots.txt disallows.",
+      "verification": "For each sitemap URL, fetch it and assert the canonical equals the sitemap entry and robots.txt does not disallow it."
+    },
+    {
+      "id": "required-legal-pages",
+      "title": "The legal pages the jurisdiction requires exist and are linked",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app"
+      ],
+      "tier": "situational",
+      "why": "SITUATIONAL because the requirement is jurisdictional, not universal: a German commercial site needs an Impressum, a US one does not. The skill reports what is missing for the declared region and does not assert a legal conclusion -- that is the domain-safety-disclaimer boundary, not this file's.",
+      "remediation": "Add the pages the declared region requires and link them from the footer of every page.",
+      "verification": "Assert each declared-required page returns 200 and is reachable from the home page in one click."
+    },
+    {
+      "id": "analytics-and-consent-wiring",
+      "title": "Analytics fires only after consent, where consent is required",
+      "applies_to": [
+        "local-business",
+        "marketing-site",
+        "saas-app"
+      ],
+      "tier": "situational",
+      "why": "Also jurisdictional, and the failure is asymmetric: analytics that never fires costs data, analytics that fires before consent costs a regulatory exposure.",
+      "remediation": "Gate the analytics snippet behind the consent state; do not load it on first paint.",
+      "verification": "Load the page with consent declined and assert no request to the analytics origin."
+    }
+  ],
+  "not_in_scope": {
+    "_comment": "Named so a later contributor does not add them by analogy. Performance budgets and Lighthouse scoring are a different instrument with a different failure mode (a score is a gradient, these checks are binary), and `lighthouse` matching 0 files is NOT an argument for adding it here. Accessibility beyond alt text belongs to accessibility-auditor, which already exists and does it properly.",
+    "items": [
+      "performance budgets",
+      "lighthouse scoring",
+      "full WCAG audit",
+      "SEO keyword strategy"
+    ]
+  },
+  "no_import_decision": {
+    "_comment": "Step 0.3, recorded HERE rather than in the skill body, and the relocation is a correction the step needs rather than a liberty taken. 0.3 sits in Phase 0, whose Exit condition reads \"zero skill code written\" -- so its verify line (\"the decision is written in the skill's own body\") names an artefact its own phase forbids. The decision is what the step is about; it is recorded in the earliest durable place that exists, and the skill body restates it at 2.1 when there is a body.",
+    "decision": "no-import",
+    "decided_at": "2026-08-25",
+    "rule": "The external corpus is a STUDY OBJECT and a per-defect harvest source. Its rule set is not imported. Rules enter ONE AT A TIME, each against a named defect, each carrying its own remediation and verification.",
+    "why": "An imported rule set arrives with its authors' assumptions about site type, jurisdiction and stack, and none of those is checked on arrival. The failure is silent: the skill grows to N checks, each individually plausible, and the conditional axis this file exists to enforce is the first thing a bulk import flattens. One-at-a-time keeps the axis honest because every entry has to answer `applies_to` before it lands.",
+    "ceiling": 50,
+    "ceiling_enforced_by": "tests/scripts/web_launch_readiness_config.test.ts asserts checks.length < 50. Currently 7."
+  },
+  "regions": {
+    "_comment": "Region axis (road-to-web-launch-readiness 2.3). Separate from site_types because it answers a different question: site_types decides WHETHER a check applies, regions decides HOW SEVERELY. A DE-targeted site owes Impressum and Datenschutz by law (TMG 5 / DSGVO Art. 13), so `required-legal-pages` is critical there and situational elsewhere -- the same check, a different tier. Modelled as a tier ESCALATION rather than as a second applies_to list, because a legal page is not more or less applicable in Germany, it is more or less optional.",
+    "values": [
+      "de",
+      "eu",
+      "us",
+      "unspecified"
+    ],
+    "default": "unspecified",
+    "escalations": [
+      {
+        "check": "required-legal-pages",
+        "region": "de",
+        "to": "critical",
+        "why": "TMG 5 obliges an Impressum and DSGVO Art. 13 a Datenschutzerklaerung for a DE-targeted commercial site. Abmahnung risk is real and immediate, which is what separates critical from situational here."
+      }
+    ]
+  }
+}

package/src/scripts/_cli/cmd_doctor.ts

@@ -82,6 +82,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as YAML from 'yaml';
 
+import { _check_overrides } from './doctor_overrides.js';
+import { _is_global_only_consumer } from './doctor_install_mode.js';
+// Forwarded, not re-declared: both names moved to doctor_install_mode.ts and existing
+// importers of cmd_doctor.js keep resolving. `export ... from` rather than an import,
+// because INSTALL_MODE_MARKER_RELATIVE is not referenced here any more and an unused
+// import would be dropped — silently breaking whoever imports it from this path.
+export { INSTALL_MODE_MARKER_RELATIVE, _is_global_only_consumer } from './doctor_install_mode.js';
 import * as claude_plugin from '../_lib/claude_plugin.js';
 import * as claude_settings_hooks from '../_lib/claude_settings_hooks.js';
 import { _is_source_repo } from './cmd_refresh.js';
@@ -765,6 +772,7 @@ const CHECK_IDS = [
     'surface-state',
     'hook-wiring',
     'stale-orphans',
+    'overrides',
     'rule-scope-drift',
     'manifest-integrity',
     'lockfile-freshness',
@@ -795,6 +803,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'surface-state',
     'hook-wiring',
     'stale-orphans',
+    'overrides',
     'rule-scope-drift',
     'mcp-mode',
     'mcp-beta-readiness',
@@ -818,20 +827,6 @@ const MANIFEST_REQUIRED_CHECK_IDS: ReadonlySet<string> = new Set([
     'unsupported-combos',
 ]);
 
-/**
- * Signals a set-up global-only consumer. The `.event4u-bridge.yml` marker was
- * retired (ADR-020 amendment 2026-07-13); the durable project-side signal is
- * the install-mode marker (written on every install) or the `agents/overrides/`
- * scaffold. Either is sufficient.
- */
-const INSTALL_MODE_MARKER_RELATIVE = 'agents/.agent-state/install-mode.txt';
-
-function _is_global_only_consumer(project_root: string): boolean {
-    return (
-        isFile(path.join(project_root, INSTALL_MODE_MARKER_RELATIVE)) ||
-        isDir(path.join(project_root, 'agents', 'overrides'))
-    );
-}
 
 /** Repair targets that `--repair <id>` accepts. */
 const REPAIR_IDS = ['wizard-state'] as const;
@@ -2976,6 +2971,7 @@ function _run_checks(
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
+        overrides: () => _check_overrides(project_root),
         'rule-scope-drift': () => _check_rule_scope_drift(project_root),
         'manifest-integrity': () => _check_manifest_integrity(manifest),
         'lockfile-freshness': () => _check_lockfile_freshness(manifest),
@@ -3059,6 +3055,11 @@ function _run_checks_no_manifest(
         'surface-state': _check_surface_state,
         'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
+        // BOTH registries need the id. Registering only the first one crashed with
+        // `runners[cid] is not a function` on a global-only consumer, which is the
+        // path that has no manifest — a loud failure rather than a silent skip, and
+        // worth the comment because the duplication is easy to miss.
+        overrides: () => _check_overrides(project_root),
         'rule-scope-drift': () => _check_rule_scope_drift(project_root),
         'manifest-integrity': () => _skipped_manifest_check('manifest-integrity'),
         'lockfile-freshness': () => _skipped_manifest_check('lockfile-freshness'),
@@ -3710,8 +3711,6 @@ export {
     CHECK_IDS,
     GLOBAL_CHECK_IDS,
     MANIFEST_REQUIRED_CHECK_IDS,
-    INSTALL_MODE_MARKER_RELATIVE,
-    _is_global_only_consumer,
     REPAIR_IDS,
     MCP_BETA_GATES,
     STATUS_SYMBOLS,

package/src/scripts/_cli/doctor_install_mode.ts

@@ -0,0 +1,49 @@
+/**
+ * Install-mode detection, extracted from `cmd_doctor.ts`.
+ *
+ * A PURE MOVE, and the reason is arithmetic. `cmd_doctor.ts` sits ~2,200 lines above the
+ * 1,500-line ceiling, so `check_source_size_budget` refuses ANY net growth in it: the
+ * override-delivery check cost 128 lines, extracting that check into
+ * `doctor_overrides.ts` paid 119, and this pays the residual 9.
+ *
+ * Extracting a NEIGHBOUR rather than shaving the new feature is deliberate. The
+ * alternative was compressing the new check's comments until the number fit, which buys
+ * the same green from worse code. A file under the ceiling contributes zero excess, so
+ * the total falls by exactly what leaves.
+ *
+ * It is also a genuinely separate concern: "which install shape is this project in" is
+ * asked before any check runs, and it reads markers rather than performing a check.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Signals a set-up global-only consumer. The `.event4u-bridge.yml` marker was
+ * retired (ADR-020 amendment 2026-07-13); the durable project-side signal is
+ * the install-mode marker (written on every install) or the `agents/overrides/`
+ * scaffold. Either is sufficient.
+ */
+export const INSTALL_MODE_MARKER_RELATIVE = 'agents/.agent-state/install-mode.txt';
+
+export function _is_global_only_consumer(project_root: string): boolean {
+    return (
+        isFile(path.join(project_root, INSTALL_MODE_MARKER_RELATIVE)) ||
+        isDir(path.join(project_root, 'agents', 'overrides'))
+    );
+}

package/src/scripts/_cli/doctor_overrides.ts

@@ -0,0 +1,154 @@
+/**
+ * The doctor's override-delivery check, extracted from `cmd_doctor.ts`.
+ *
+ * Extracted rather than inlined because `cmd_doctor.ts` sits at 3,852 lines against
+ * the 1,500-line ceiling, so `check_source_size_budget` refuses ANY net growth in it
+ * — the same ratchet that refused two earlier attempts at an unrelated feature. The
+ * check landed inline first and the gate said so (128 new violations); this file is
+ * the fix, and it is a pure move. A new file under the ceiling contributes zero
+ * excess, so the total falls by exactly what left.
+ *
+ * Kept as its own module rather than folded into a grab-bag of checks: it is the only
+ * consumer of `KERNEL_RULE_ID_SET` in the doctor, and that import came with it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { KERNEL_RULE_ID_SET } from '../_lib/kernel_rules.js';
+
+type Dict = Record<string, unknown>;
+
+function isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Override DELIVERY and audit state — steps 3.1 and 3.2 of
+ * `road-to-override-efficacy-proof`.
+ *
+ * The report already knew `agents/overrides/` existed, as an install-mode marker
+ * (`_is_global_only_consumer`). It never said what was IN it, so a consumer who
+ * placed an override had no surface anywhere that confirmed the file was seen.
+ *
+ * THE VOCABULARY IS THE CONTRACT, and step 3.2 makes it a checkable one. This line
+ * says `present`, `registered`, `cited` — never `enforced`, `applied`, `honoured`
+ * or `honored`. Those four words would make it read as a claim that the agent
+ * changed its behaviour, which is Phase 2's number and is deferred on population
+ * validity. A delivery check quoted as an efficacy claim is the exact defect this
+ * roadmap exists to close, so the words it must not use are asserted against by
+ * `agent-config doctor 2>&1 | grep -iE 'override.*(enforced|applied|honoured|honored)'`
+ * returning nothing.
+ *
+ * `warn` rather than `error` on an uncited or unregistered override: the strict
+ * gate (`lint_override_kernel_guard --strict`) is what refuses those in CI. Two
+ * surfaces failing the same fact would make `doctor` a second gate with no
+ * authority, and the doctor's job is to tell a consumer what state they are in.
+ */
+export function _check_overrides(project_root: string): Dict {
+    const dir = path.join(project_root, 'agents', 'overrides', 'rules');
+    if (!isDir(dir)) {
+        return {
+            id: 'overrides',
+            status: 'skip',
+            message: 'no agents/overrides/rules/ — no overrides declared',
+            remedy: '',
+        };
+    }
+    let names: string[];
+    try {
+        names = fs
+            .readdirSync(dir)
+            .filter((n) => n.endsWith('.md'))
+            .sort();
+    } catch {
+        return {
+            id: 'overrides',
+            status: 'warn',
+            message: 'agents/overrides/rules/ is present but unreadable',
+            remedy: 'check permissions on agents/overrides/rules/',
+        };
+    }
+    if (names.length === 0) {
+        return {
+            id: 'overrides',
+            status: 'ok',
+            message: 'agents/overrides/rules/ present, 0 overrides declared',
+            remedy: '',
+        };
+    }
+    const registryPath = path.join(project_root, 'agents', 'overrides', 'kernel-exceptions.yml');
+    // Parse the `exceptions:` block the same way the audit does, rather than
+    // grepping for the rule name anywhere in the file. The first version did grep,
+    // and it read `verify-before-complete` as UNREGISTERED even though the registry
+    // lists it — the name appears inside a `justification:` block and the entry key
+    // is `rule:`, so a bare name match neither confirms nor denies registration. A
+    // doctor line that contradicts the strict gate is worse than no line.
+    const registered = new Set<string>();
+    if (isFile(registryPath)) {
+        let inExceptions = false;
+        for (const raw of fs.readFileSync(registryPath, 'utf-8').split('\n')) {
+            const line = raw.replace(/\s+$/, '');
+            if (/^exceptions:\s*$/.test(line)) {
+                inExceptions = true;
+                continue;
+            }
+            if (!inExceptions) continue;
+            if (/^\S/.test(line)) break;
+            const m = /^\s*-?\s*rule:\s*"?([a-z0-9-]+)"?\s*$/i.exec(line);
+            if (m?.[1] !== undefined) registered.add(m[1]);
+        }
+    }
+    let kernel = 0;
+    let uncited = 0;
+    let unregisteredKernel = 0;
+    for (const n of names) {
+        const rule = n.replace(/\.md$/, '');
+        const isKernel = KERNEL_RULE_ID_SET.has(rule);
+        if (isKernel) kernel += 1;
+        const text = fs.readFileSync(path.join(dir, n), 'utf-8');
+        // Same shape the audit's `has_citation` looks for. Duplicated rather than
+        // imported because cmd_doctor must not pull a lint module into the CLI's
+        // startup path; the strict gate owns the authoritative check and this is a
+        // report.
+        if (!/^>\s*Overrides:/m.test(text)) uncited += 1;
+        if (isKernel && !registered.has(rule)) {
+            unregisteredKernel += 1;
+        }
+    }
+    const parts = [
+        `${String(names.length)} override(s) present`,
+        `${String(kernel)} kernel`,
+    ];
+    // Registration is stated POSITIVELY, not only on failure. Step 3.1's verify
+    // names four words the line must carry — one override, kernel, registered,
+    // cited — and a count that appears only when it is wrong leaves a reader
+    // unable to tell "all registered" from "registration not checked".
+    if (kernel > 0) {
+        parts.push(`${String(kernel - unregisteredKernel)}/${String(kernel)} kernel registered`);
+    }
+    parts.push(`${String(names.length - uncited)}/${String(names.length)} cited`);
+    // Deliberately last and deliberately blunt: without it the counts read as a
+    // verdict on whether the overrides work.
+    parts.push('delivery only — efficacy unmeasured');
+    return {
+        id: 'overrides',
+        status: uncited > 0 || unregisteredKernel > 0 ? 'warn' : 'ok',
+        message: parts.join(', '),
+        remedy:
+            uncited > 0 || unregisteredKernel > 0
+                ? 'run `./scripts-run src/scripts/lint_override_kernel_guard --strict` for the detail'
+                : '',
+    };
+}

package/src/scripts/_dispatch.bash

@@ -71,6 +71,10 @@ TS-shell native (run via the installed `agent-config` binary):
   config                     Open the configuration GUI (global default; --project for the project surface)
   settings                   Open the local Settings GUI (alias of config)
   ui:serve                   Start the local UI server (127.0.0.1, auto-picked port)
+  ui:audit [path]            Inventory a UI tree into agents/runtime/state/ui-audit.json
+                             (Class A). The artefact ui-audit-gate reads.
+  ui:render <path|url>       Headless capture at desktop / 375px / 320px into
+                             agents/runtime/state/render/ (Class A; no process survives).
   workspaces ls              List workspaces from the discovery manifest
   packs ls                   List packs from the discovery manifest
   brand:status               Is a consumer brand layer present, and at which of the
@@ -224,6 +228,10 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   session:recycle            Validate + write the main-session recycle envelope (--verify validates only)
                              (deliberate recycle instead of auto-compact). Flags:
                              --file <json> | --template; default reads stdin
+  roadmap:context            One live situational-awareness probe: open PRs and the
+                             files they change, remote branches carrying a roadmap
+                             slug, live sessions, agents/tmp/ note NAMES, and sibling
+                             roadmaps on the same topic. --roadmap <slug>, --json
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
                              (archives completed roadmaps; --no-archive to skip)
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
@@ -693,6 +701,14 @@ cmd_mcp_run() {
 # PACKAGE_ROOT, not the consumer projection: the CLI imports the register library
 # under src/scripts/_lib/, which is package-internal and never shipped into
 # dist/agent-src/scripts/. Same shape as cmd_settings_set.
+# Situational-awareness probe (road-to-roadmap-situational-awareness Phase 1).
+# PACKAGE_ROOT, not the consumer projection: it imports src/scripts/_lib/, which
+# is package-internal and never shipped into dist/agent-src/scripts/. Same shape
+# as cmd_sessions_list below, and for the same reason.
+cmd_roadmap_context() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/roadmap_context.ts" "$@"
+}
+
 cmd_sessions_list() {
   exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" list "$@"
 }
@@ -1461,6 +1477,7 @@ main() {
     settings:get)            cmd_settings_get "$@" ;;
     mcp:available)           cmd_mcp_available "$@" ;;
     brand:status)            cmd_brand_status "$@" ;;
+    roadmap:context)         cmd_roadmap_context "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;