@event4u/agent-config 7.3.0 → 7.5.0

package/docs/governance-advantage.md

@@ -0,0 +1,72 @@
+# The governance advantage — why compile-time, config-space governance is the moat
+
+Most agent-config packages are a pile of skills. This one's defensible edge is
+not skill *count* — it is **where the governance lives**: compiled into every
+host's own instruction layer at projection time, so it travels with the config
+and is present on every host by construction. Runtime-hook systems can only
+enforce where the host exposes a tool lifecycle — a minority of hosts.
+
+This is a **structural** claim, not a behaviour claim. See the honesty boundary
+at the end.
+
+## The two enforcement layers (and their reach)
+
+| Layer | How it works | Reach |
+|---|---|---|
+| **Compile-time (config space)** | Rules + Iron Laws are compiled into each host's native instruction format at projection time (`.cursorrules`, `.windsurfrules`, `copilot-instructions.md`, `GEMINI.md`, Claude/Augment native rule dirs). | **Every projection target.** |
+| **Runtime hooks** | On hosts exposing a tool lifecycle (`PreToolUse`/`PostToolUse`/`Stop`), a guard can deterministically block a call (e.g. `block_no_verify`). | **Hook-capable hosts only** (~2 of the supported set). |
+
+Full per-host breakdown: [`enforcement-by-host.md`](enforcement-by-host.md).
+
+The point: a runtime-first competitor's strongest enforcement simply **does not
+exist** on a host that has no hook surface. The compile-time layer is there on
+*that same host* because it rides in the config the host already reads.
+
+## Governance in action — three concrete traces
+
+### 1. A safety-floor rule survives projection into a static host
+`commit-policy` (`tier: safety-floor`) is compiled into Cursor's `.cursorrules`
+and Copilot's `copilot-instructions.md`. The host has no hook to block a
+`git commit`, but the constraint is **in the instruction file the host loads at
+session start** — present by construction, not dependent on a runtime primitive
+the host lacks (a static host gives it no runtime attention guarantee, but a
+runtime-only system gives it nothing at all here). A runtime-only system contributes *nothing* on these hosts.
+
+### 2. Intent routing, not a 500-artefact dump
+A prompt does not load all 258 skills. `dist/router.json` (88 rules, intent →
+skill, keyword/phrase/path triggers) carries the right skill on intent. The
+governance value is *selection discipline* — the host gets the relevant rule
+set, not the whole catalogue as context ballast.
+
+### 3. The enforcement spectrum is explicit, not implied
+On Claude Code / Cline (MCP) the safety-floor constraints get **both** layers:
+compile-time instruction **and** a deterministic runtime block. On Cursor /
+Windsurf / Copilot / Gemini they get the compile-time layer alone. We state
+which host gets which — we never imply "deterministic everywhere".
+
+## What this is NOT (honesty boundary)
+
+- **Not "un-strippable".** A human can edit any projected file. The claim is
+  *present-by-construction on every host* — a host's runtime cannot selectively
+  ignore it the way it ignores an absent runtime hook.
+- **Not a measured behaviour-change claim.** A length-controlled A/B
+  (hardened-constraint blocks vs a length-matched placebo) measured **honest-null
+  at the discipline ceiling** — the cooperative rules already catch the test
+  traps, so *adding emphasis* changed nothing measurable. The moat is that
+  governance is **present and portable across hosts**, not that more governance
+  prose provably changes a model's behaviour.
+- **Not deterministic on static hosts.** Compile-time governance is
+  model-cooperative; only hook-capable hosts get a hard block.
+
+## Why it's hard to copy
+
+A runtime-first system would have to re-author its governance to live in
+config space and project into every host's native format — i.e. become a
+content+governance layer — to match the reach. That is a different architecture,
+not a feature bolt-on. Meanwhile this package adds runtime hooks as an opt-in
+*superset* where hosts allow it, without depending on them for the floor.
+
+## See also
+
+- [`enforcement-by-host.md`](enforcement-by-host.md) — per-host enforcement mechanism.
+- [`capability-matrix.md`](capability-matrix.md) — which artifact type projects to which host.

package/docs/guidelines/design-antipatterns.md

@@ -26,6 +26,7 @@ hierarchy, reduced-motion, focus indicator) is in `lint_design_quality`
 |---|---|---|
 | **Guidance** | Subjective taste — Visual / Typography / Color / Layout / Copy patterns, override judgment, the originality self-test | this catalog |
 | **Enforcement** | Objective floors — Q1–Q6 (WCAG contrast, font-size, line-length, reduced-motion, heading hierarchy, focus indicator) as exit-code-2 CI | `lint_design_quality` |
+| **Detection** | Deterministic *aesthetic-tell* flags (P0–P3, rebuttable via DESIGN.md) — the pattern-detectable subset of the entries below | `lint_design_slop` |
 | **Audit method** | HOW to test WCAG (keyboard nav, ARIA, screen-reader procedures) | `accessibility-auditor` |
 | **Stack manifestation** | Concrete Tailwind class / hex bans, shadcn defaults | `tailwind-engineer`, `react-shadcn-ui` (per `framework-neutrality-in-generic-skills`) |
 | **Register** | Brand mode vs product mode — which patterns apply | `docs/guidelines/design-modes.md` |
@@ -34,6 +35,31 @@ This catalog is the canonical *index*; it states the pattern stack-agnostically.
 The stack-specific bans live in the apply skills and link back here by entry ID.
 The objective floors are cited from the linter, never re-eyeballed by an agent.
 
+**Deterministic detector backing** (`lint_design_slop`, dependency-free, zero
+runtime token cost): a pattern-detectable subset of these entries now has a
+deterministic rule that `design-review` cites instead of re-deriving — `V1`,
+`V3`, `V6`, `C2`, `C5`, `T4`, `T6`, `T7`, `L4`, `L8`, `M2`, `M4`, `CP1`, `CP2`,
+plus the **Consistency Locks & layout caps** `V8`, `C6`, `L9`, `L10`
+(rule ids `slop-<id>-*`, registry in `src/scripts/design_slop_rules.ts`). These
+are **flags / rebuttable presumptions**, never hard blocks — a consumer
+`DESIGN.md` that declares the pattern as intentional suppresses the flag. The
+entries needing structural or aesthetic judgment (e.g. `T3` icon-tile stack,
+`L2` three-identical-card grid, `V2` glassmorphism intent, `C7` theme-inversion)
+stay agent-judgment-only and are deliberately **not** in the detector.
+
+### Consistency Locks & layout caps (taste-dials roadmap)
+
+Within-project invariants + repetition caps. Override = declare the value in
+`DESIGN.md` (`## Consistency Locks` / a brutalist or uniform-grid style note).
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| V8 | Shape Lock — ≥ 4 distinct corner-radius scales in one surface | A fragmented radius system reads as no shape decision | Declare the radius scale in `DESIGN.md`; a genuine multi-tier scale documents each tier |
+| C6 | Colour Lock — ≥ 3 distinct saturated accent hue families | No single accent identity; reads as default-palette sprawl | Brand genuinely uses a multi-accent system, declared in `DESIGN.md` / `brand-to-tokens` |
+| C7 | Theme inversion — a light island mid-dark surface (or vice versa) not driven by the theme system | Mid-surface inversion breaks the theme rhythm | Intentional inverted callout with a documented reason — **judgment-only**, design-review calls it (deterministic detection is unreliable) |
+| L9 | Section monotony — ≥ 8 sections, < 4 distinct layout families | Uniform section rhythm collapses scannability | Deliberately uniform grid (e.g. a gallery), declared as such |
+| L10 | Zigzag — > 2 consecutive image-left/text-right two-column sections | The alternating-zigzag landing-page tell | A genuinely sequenced walkthrough where alternation aids comprehension |
+
 ---
 
 ## Visual

package/docs/guidelines/design-canon.md

@@ -0,0 +1,62 @@
+# Design Canon — named-systems grounding index
+
+> Lazy-loaded reference. Pull this when a brief names (or a project's
+> `components.json`/deps signal) a published design system, type, or colour
+> reference — so the design is **grounded in named canon**, not improvised.
+> Used by `design-intelligence`; cross-linked from `typography-system`,
+> `iconography`, `design-tokens`, `brand-to-tokens`, `icon-consistency`.
+
+This is a thin **index** — names, one-line summaries, and a "pull this when"
+trigger. It deliberately does **not** bundle the multi-megabyte specs; fetch
+the live spec only when the trigger fires (the canonical URLs below are the
+fetch targets). Precedence (per `brand-source-of-truth`): **consumer brand
+tokens > confirmed session decisions > named canon (this index) > generated
+corpus.** Canon is a gap-filler, never an override of a registered brand value.
+
+## Design systems
+
+| System | Signature traits (one-line) | Pull this when |
+|---|---|---|
+| **Material 3** (Google) | Dynamic colour from a seed (HCT), tonal palettes, elevation by tint not shadow, expressive motion (emphasized easing). | brief says "Material" / "Android"; deps `@mui/material`, `@angular/material`, `react-native-paper`. Spec: m3.material.io |
+| **Apple HIG** | Platform-native clarity/deference/depth, SF type + Dynamic Type, system materials/vibrancy, restrained motion, large touch targets. | brief targets iOS/iPadOS/macOS/visionOS, "native Apple feel". Spec: developer.apple.com/design |
+| **Fluent 2** (Microsoft) | Neutral-forward, acrylic/reveal materials, Segoe/Fluent type ramp, depth via subtle shadow, enterprise density. | brief says "Fluent"/"Windows"/"Office"; deps `@fluentui/*`. Spec: fluent2.microsoft.design |
+| **Carbon** (IBM) | 2px grid, IBM Plex type, strong data-viz system, productive vs expressive themes, accessibility-first. | brief says "Carbon"/"IBM"/data-heavy enterprise; deps `@carbon/*`. Spec: carbondesignsystem.com |
+| **Ant Design** | Dense enterprise/admin, comprehensive component set, token-based theming (v5), wireframe-driven. | brief says "Ant"/admin console/CRUD-heavy; deps `antd`. Spec: ant.design |
+| **Atlassian** | Product-suite consistency, ADS tokens, calm neutral + bold primary, strong empty/loading patterns. | brief says "Atlassian"/Jira-like; deps `@atlaskit/*`. Spec: atlassian.design |
+
+Grounding rule: surface the matching one-liner, then **offer to pull the live
+spec** before committing to the system's conventions. Never reproduce a brand
+book's marks; ground against the *system's* documented principles.
+
+## Typography craft (foundry + theory)
+
+A one-line index — point `typography-system` here; do not inline the content.
+
+- **Theory:** Butterick's *Practical Typography* (practicaltypography.com — line-length, measure, hierarchy rules), *Thinking with Type*.
+- **Calibration / "in use":** Typewolf, Fonts In Use (real pairings, not defaults).
+- **Quality foundries** (beyond the AI-default fonts the anti-slop catalog T7 flags): Klim, Lineto, Colophon, Commercial Type, Grilli Type; libre: League of Movable Type, Google Fonts (chosen deliberately, not reflexively).
+- Pull when: a brief calls for a distinctive type voice, or to escape the Inter/Roboto/Geist default.
+
+## Colour references
+
+Names + when-to-use — not the palettes themselves.
+
+- **Accessibility / contrast:** WCAG contrast checkers (e.g. APCA, WebAIM) — verify text/non-text contrast (ties to `lint_design_quality` Q1 + anti-slop C4). Pull on any colour decision that must clear AA.
+- **Culturally-specific palettes:** Nippon Colors (traditional Japanese), Chinese Colors — pull when the brand/audience is culturally situated and a Western default palette would read as generic.
+- **Systematic palette tools:** the design systems above ship their own token palettes — prefer the system's palette over an ad-hoc picker when a system is in play.
+
+## Icon systems
+
+Each design system ships a matching icon set — prefer it when that system is in
+play (consistency over novelty, per `icon-consistency`): **Material Symbols**
+(Material 3, variable weight/fill/grade), **SF Symbols** (Apple HIG, weight-
+matched to SF text), **Fluent UI System Icons** (Fluent), **Carbon icons**
+(Carbon). Outside a named system, the `iconography` skill resolves a single
+Iconify set (Lucide / Phosphor / Heroicons / Tabler) — pick one and stay in it.
+Pull when: choosing or auditing an icon library.
+
+## See also
+
+- `docs/guidelines/design-antipatterns.md` — the anti-slop catalog (T7 default-font tell, C1/C5 palette tells) this canon helps you escape.
+- `brand-source-of-truth` / `brand-consistency` — the precedence this index obeys.
+- `design-intelligence` — the consumer that surfaces these on a brief signal.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "7.3.0",
+    "version": "7.5.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -81,6 +81,7 @@
         "@typescript-eslint/parser": "^8.59.4",
         "eslint": "^9.39.4",
         "happy-dom": "^20.9.0",
+        "js-tiktoken": "^1.0.21",
         "tsx": "^4.22.3",
         "typescript": "^5.9.3",
         "vite": "^5.4.21",

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

@@ -722,6 +722,27 @@ hooks:
   injection_scan:
     enabled: false
 
+  # PreToolUse RTK-wrap nudge (token-saving Phase 3). Default-OFF. When enabled
+  # AND `rtk` is on PATH (a live probe — not a self-reported flag), warns (exit
+  # 2, never blocks) "re-run wrapped with rtk" before a single verbose CLI
+  # command (git/npm/cargo/docker/…), so verbose output is filtered for 60–90%
+  # token saving. Skips completeness-critical / piped / compound commands and
+  # `git diff`. No-op when rtk is absent. Opt in once you have rtk installed.
+  rtk_wrap:
+    enabled: false
+
+  # PreToolUse anti-slop nudge (road-to-anti-slop-detector Phase 3). Default-OFF.
+  # When enabled, runs the lint_design_slop registry against about-to-be-written
+  # UI content (html/css/jsx/…) and WARNS (exit 2, never blocks) on P0/P1
+  # aesthetic tells — the side-stripe signature, gradient-text, magic z-index,
+  # etc. Flags are rebuttable: declare intent in DESIGN.md, design-slop-disable,
+  # or proceed. Anti-loop: a file::rule signature surfaced 3x goes silent so it
+  # never traps the agent. The universal gate is the lint_design_slop linter/CI;
+  # this hook is a host-limited convenience layer (pre_tool_use fires on ~2-3
+  # hosts). Opt in once you trust the signal-to-noise on your UI.
+  design_slop:
+    enabled: false
+
 # --- Decision engine ---
 #
 # Controllable gates layered over the observability surface. Absent

package/src/scripts/_cli/cmd_analyze_session.ts

@@ -0,0 +1,347 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config analyze-session` — post-session report from on-disk runtime
+ * state.
+ *
+ * Read-only diagnostic. No daemon, no network, no model calls. It reads two
+ * real data sources the work-engine / context-hygiene hook leave behind and
+ * prints a deterministic Markdown report:
+ *
+ *   1. the work_engine state envelope `.work-state.json` (version 1) — loaded
+ *      via `load_state` from `explain_last/state_loader.ts`. Fields read:
+ *        - `changes`  — files touched (array of {kind, stack, file, summary}).
+ *        - `outcomes` — directive → "success" / "blocked" / … .
+ *        - `halts`    — array of recorded halts.
+ *   2. `agents/runtime/state/context-hygiene.json` — fields read:
+ *        - `tool_calls`           (int)
+ *        - `consecutive_same_tool`(int)
+ *        - `loop_detected`        (bool)
+ *
+ * There is NO general token/cost data source in this package (only
+ * video-specific telemetry), so the report deliberately does NOT report
+ * tokens or cost — it prints a single honest "not tracked" line instead.
+ *
+ * Exit codes (mirroring `cmd_explain`'s `last` subject):
+ *   0  report rendered (even when a source file is absent — graceful note).
+ *   1  the work-state file is missing or unreadable.
+ *   2  invocation error (bad project root, bad --state-file path).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ProjectRootError, resolve_project_root } from '../_lib/agent_settings.js';
+import { StateLoadError, load_state } from './explain_last/state_loader.js';
+
+type Dict = Record<string, unknown>;
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const CONTEXT_HYGIENE_RELATIVE = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'context-hygiene.json',
+);
+
+/** Python `raise SystemExit(code)` analogue — propagates an explicit code. */
+class SystemExitError extends Error {
+    constructor(public readonly code: number) {
+        super(`system-exit-${code}`);
+    }
+}
+
+/** argparse-style usage / help exit (code 2 / 0). Caught at the CLI entry. */
+class ArgparseExit extends Error {
+    constructor(public readonly code: number) {
+        super(`argparse-exit-${code}`);
+    }
+}
+
+function eprint(line = ''): void {
+    process.stderr.write(line + '\n');
+}
+
+function isPlainObject(value: unknown): value is Dict {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function _resolve_root(arg: string | null): string {
+    try {
+        const [root] = resolve_project_root(arg, { cwd: process.cwd() });
+        return root;
+    } catch (exc) {
+        if (exc instanceof ProjectRootError) {
+            eprint(`❌  analyze-session: ${exc.message}`);
+            throw new SystemExitError(2);
+        }
+        throw exc;
+    }
+}
+
+/** `Path.relative_to(base)` — returns null when `p` is not under `base`. */
+function relativeToOrNull(p: string, base: string): string | null {
+    const rel = path.relative(base, p);
+    if (rel === '') return rel;
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        return null;
+    }
+    return rel;
+}
+
+/**
+ * Read the context-hygiene snapshot. Returns the parsed object, or `null`
+ * when the file is absent / unreadable / not an object — the caller renders
+ * a graceful "not available" note rather than failing the whole report.
+ */
+function _load_context_hygiene(project_root: string): Dict | null {
+    const p = path.join(project_root, CONTEXT_HYGIENE_RELATIVE);
+    if (!fs.existsSync(p)) {
+        return null;
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        return null;
+    }
+    let payload: unknown;
+    try {
+        payload = JSON.parse(text);
+    } catch {
+        return null;
+    }
+    return isPlainObject(payload) ? payload : null;
+}
+
+/** Render `value` as an integer string, or `'?'` when not a finite number. */
+function intOrUnknown(value: unknown): string {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return String(Math.trunc(value));
+    }
+    return '?';
+}
+
+/**
+ * Build the deterministic Markdown report from already-loaded state.
+ *
+ * Pure function — no I/O, no clock, no environment. Both inputs come from the
+ * caller so the report is unit-testable in isolation.
+ *
+ * @param state    the parsed `.work-state.json` (version 1).
+ * @param hygiene  the parsed context-hygiene snapshot, or `null` when absent.
+ */
+export function render_report(state: Dict, hygiene: Dict | null): string {
+    const lines: string[] = [];
+    lines.push('# Session analysis');
+    lines.push('');
+
+    // --- Files touched (from state.changes) ---
+    const changes = Array.isArray(state['changes']) ? (state['changes'] as unknown[]) : [];
+    lines.push(`## Files touched (${changes.length})`);
+    lines.push('');
+    if (changes.length === 0) {
+        lines.push('_No files recorded as changed._');
+    } else {
+        for (const change of changes) {
+            if (!isPlainObject(change)) continue;
+            const file = typeof change['file'] === 'string' ? change['file'] : '(unknown file)';
+            const summary =
+                typeof change['summary'] === 'string' && change['summary'].length > 0
+                    ? ` — ${change['summary']}`
+                    : '';
+            lines.push(`- \`${file}\`${summary}`);
+        }
+    }
+    lines.push('');
+
+    // --- Per-directive outcomes (from state.outcomes) ---
+    const outcomes = isPlainObject(state['outcomes']) ? (state['outcomes'] as Dict) : {};
+    const directives = Object.keys(outcomes).sort(); // deterministic order
+    const blocked = directives.filter((d) => outcomes[d] === 'blocked');
+    lines.push(`## Outcomes (${directives.length})`);
+    lines.push('');
+    if (directives.length === 0) {
+        lines.push('_No directive outcomes recorded._');
+    } else {
+        for (const directive of directives) {
+            const result = outcomes[directive];
+            const marker = result === 'blocked' ? '⚠️ ' : '';
+            lines.push(`- ${marker}\`${directive}\`: ${String(result)}`);
+        }
+    }
+    lines.push('');
+    if (blocked.length > 0) {
+        lines.push(`**Blocked directives (${blocked.length}):** ${blocked.join(', ')}`);
+        lines.push('');
+    }
+
+    // --- Halts (from state.halts) ---
+    const halts = Array.isArray(state['halts']) ? (state['halts'] as unknown[]) : [];
+    lines.push(`## Halts (${halts.length})`);
+    lines.push('');
+    if (halts.length === 0) {
+        lines.push('_No halts recorded._');
+    } else {
+        lines.push(`This session recorded ${halts.length} halt(s).`);
+    }
+    lines.push('');
+
+    // --- Tool activity (from context-hygiene) ---
+    lines.push('## Tool activity');
+    lines.push('');
+    if (hygiene === null) {
+        lines.push('_Context-hygiene snapshot not available._');
+    } else {
+        const toolCalls = intOrUnknown(hygiene['tool_calls']);
+        const consecutive = intOrUnknown(hygiene['consecutive_same_tool']);
+        const loop = hygiene['loop_detected'] === true;
+        lines.push(`- Tool calls: ${toolCalls}`);
+        lines.push(`- Consecutive same-tool calls: ${consecutive}`);
+        lines.push(`- Loop detected: ${loop ? 'yes' : 'no'}`);
+    }
+    lines.push('');
+
+    // --- Honest token/cost note (no per-session source in this package) ---
+    lines.push('## Token / cost');
+    lines.push('');
+    lines.push('Token/cost: not tracked (no per-session source).');
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+function _analyze_session(project_root: string, state_file: string | null): number {
+    const target_state = state_file || path.join(project_root, '.work-state.json');
+    let state: Dict;
+    try {
+        state = load_state(target_state) as Dict;
+    } catch (exc) {
+        if (exc instanceof StateLoadError) {
+            // Never print absolute paths in errors (username leakage).
+            const rel = relativeToOrNull(target_state, project_root);
+            const shown = rel !== null ? rel : path.basename(target_state);
+            const msg = exc.message.split(target_state).join(shown);
+            eprint(`❌  analyze-session: ${msg}`);
+            return exc.exitCode;
+        }
+        throw exc;
+    }
+    const hygiene = _load_context_hygiene(project_root);
+    process.stdout.write(render_report(state, hygiene));
+    return 0;
+}
+
+interface Opts {
+    project: string | null;
+    state_file: string | null;
+}
+
+const PROG = 'agent-config analyze-session';
+const USAGE = `usage: ${PROG} [-h] [--project PROJECT] [--state-file STATE_FILE]\n`;
+
+const _HELP = `\
+usage: ${PROG} [--project PATH] [--state-file PATH]
+
+Print a post-session report from on-disk runtime state. Read-only;
+no daemon, no network, no model calls.
+
+Sources read:
+  .work-state.json (version 1)
+    · changes  — files touched
+    · outcomes — per-directive success / blocked
+    · halts    — recorded halts
+  agents/runtime/state/context-hygiene.json
+    · tool_calls · consecutive_same_tool · loop_detected
+
+Token/cost is NOT reported — this package has no per-session token
+source (only video-specific telemetry).
+
+options:
+  --project PATH       project root (defaults to anchor walk from cwd)
+  --state-file PATH    .work-state.json path (default <root>/.work-state.json)
+  -h, --help           show this help and exit
+
+exit codes:
+  0  report rendered (a missing source file is noted, not fatal)
+  1  no recent run found (state file missing or unreadable)
+  2  invocation error (bad project root, bad --state-file path)
+`;
+
+function _argError(msg: string): never {
+    process.stderr.write(USAGE);
+    process.stderr.write(`${PROG}: error: ${msg}\n`);
+    throw new ArgparseExit(2);
+}
+
+function _parse(argv: string[]): Opts {
+    const opts: Opts = { project: null, state_file: null };
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i] as string;
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_HELP);
+            throw new ArgparseExit(0);
+        }
+        const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+        const flag = eq >= 0 ? a.slice(0, eq) : a;
+        const inlineVal = eq >= 0 ? a.slice(eq + 1) : null;
+        if (flag === '--project' || flag === '--state-file') {
+            const dest = flag === '--project' ? 'project' : 'state_file';
+            let value: string;
+            if (inlineVal !== null) {
+                value = inlineVal;
+            } else {
+                if (i + 1 >= argv.length) {
+                    _argError(`argument ${flag}: expected one argument`);
+                }
+                value = argv[i + 1] as string;
+                i += 1;
+            }
+            opts[dest] = value;
+            i += 1;
+            continue;
+        }
+        _argError(`unrecognized arguments: ${a}`);
+    }
+    return opts;
+}
+
+export function main(argv: string[] | null = null): number {
+    const argv_list = argv !== null ? Array.from(argv) : process.argv.slice(2);
+    const opts = _parse(argv_list);
+    let project_root: string;
+    try {
+        project_root = _resolve_root(opts.project);
+    } catch (exc) {
+        if (exc instanceof SystemExitError) {
+            return exc.code;
+        }
+        throw exc;
+    }
+    return _analyze_session(project_root, opts.state_file);
+}
+
+// --- CLI entry ---
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    try {
+        process.exitCode = main(process.argv.slice(2));
+    } catch (e) {
+        if (e instanceof ArgparseExit) {
+            process.exitCode = e.code;
+        } else if (e instanceof SystemExitError) {
+            process.exitCode = e.code;
+        } else {
+            throw e;
+        }
+    }
+}
+
+export { _parse, _resolve_root, _load_context_hygiene, _analyze_session, ArgparseExit, SystemExitError };
+export type { Opts };

package/src/scripts/_dispatch.bash

@@ -933,6 +933,13 @@ cmd_explain() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_explain.ts" "$@"
 }
 
+# `agent-config analyze-session` — read-only post-session report from on-disk
+# runtime state (.work-state.json + context-hygiene.json). No daemon, no
+# network, no model calls. See scripts/_cli/cmd_analyze_session.ts.
+cmd_analyze_session() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_analyze_session.ts" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -991,6 +998,7 @@ main() {
     doctor)                  cmd_doctor "$@" ;;
     versions)                cmd_versions "$@" ;;
     explain)                 cmd_explain "$@" ;;
+    analyze-session)         cmd_analyze_session "$@" ;;
     help|--help|-h|"")
       # Optional `--tier=0|1|all` filter (default 0).
       local tier_arg="0"