@event4u/agent-config 9.34.0 → 9.36.0

package/src/scripts/lint_rule_skill_pack_reach.ts

@@ -0,0 +1,263 @@
+#!/usr/bin/env tsx
+/**
+ * lint_rule_skill_pack_reach — a rule and the skills it routes to must be able
+ * to arrive in the same install.
+ *
+ * The defect that motivated this is real and was undocumented in the direction
+ * it actually runs. `ui-audit-gate` and `design-review-after-ui-write` are
+ * `packs: [frontend-design]`; `existing-ui-audit`, `design-review` and
+ * `fe-design` are `packs: [engineering-base]`. The direction the rule prose
+ * described — frontend-design without engineering-base — cannot happen, because
+ * `frontend-design` declares `requires: [engineering-base]`. The reverse can: a
+ * plain `laravel` or `react` install carries the skills and **no rule that ever
+ * routes to them**, since both packs only *suggest* frontend-design.
+ *
+ * TWO CHECKS, AND THEY ARE NOT THE SAME QUESTION.
+ *
+ *   unreachable-route (error) — a rule routes to a skill that a pack-legal
+ *   install of that rule cannot receive. The consumer gets the obligation
+ *   without the artefact that discharges it.
+ *
+ *   unrouted-skill (advisory) — a skill that IS routed somewhere reaches a pack
+ *   none of its routing rules reach. The consumer has the artefact and no path
+ *   to it. This is the measured case above.
+ *
+ *   Scope, stated because the obvious reading is wider than the scan: the
+ *   subject set is skills some rule already routes to. A skill NO rule routes
+ *   to anywhere is never examined, deliberately — most of the estate is in
+ *   that set by design (a skill invoked by name needs no rule), so reporting
+ *   it would bury the finding this check exists for. Advisory for the same
+ *   reason: reachability-only-by-invocation is a legitimate design, so a
+ *   finding here is a question, not a verdict.
+ *
+ * The install closure is `pack + requires*` — the transitive expansion the
+ * resolver performs. `suggests` is deliberately NOT followed: it is advisory,
+ * the wizard may offer it and the user may decline, so an invariant that
+ * counted it would pass on installs that do not exist.
+ *
+ * ADVISORY UNTIL ITS FINDING SET IS EMPTY, AND THE FIRST RUN SAYS WHY.
+ * Measured on introduction: 12 `unreachable-route` and 14 `unrouted-skill`
+ * findings across 116 rules. The UI pair is one instance of an estate-wide
+ * pattern — safety floors routing into packs their own pack does not pull, and
+ * skills delivered by a pack whose routing rule ships in a different one.
+ * Shipping this as a blocking gate on day one would have meant either 12
+ * unrelated fixes smuggled into a feature change or a suppression file created
+ * on day one, which is the ratchet-shaped failure this repo has recorded
+ * before. So `--strict` exists and the default does not use it: promotion to
+ * error is a one-flag change once the set is empty, and the count is printed
+ * on every run so "still 12" cannot quietly become "still 30".
+ *
+ * Exit codes: 0 advisory run (default) or clean · 1 `unreachable-route`
+ * findings under `--strict` · 2 usage or IO error. A scan that walked no rules
+ * exits 2 rather than green — a gate that scanned nothing must never read as a
+ * pass.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const RULES_DIR = path.join(REPO, 'src', 'rules');
+const SKILLS_DIR = path.join(REPO, 'src', 'skills');
+const PACKS_FILE = path.join(REPO, 'src', 'config', 'discovery', 'packs.yml');
+
+export interface PackDef {
+    id: string;
+    requires: string[];
+}
+
+export interface Finding {
+    kind: 'unreachable-route' | 'unrouted-skill';
+    subject: string;
+    detail: string;
+}
+
+/** Frontmatter block between the leading fences, or "" when absent. */
+function frontmatterOf(content: string): string {
+    if (!content.startsWith('---')) return '';
+    const end = content.indexOf('\n---', 3);
+    return end === -1 ? '' : content.slice(3, end);
+}
+
+function frontmatterObject(file: string): Record<string, unknown> {
+    const raw = frontmatterOf(fs.readFileSync(file, 'utf-8'));
+    if (!raw.trim()) return {};
+    try {
+        const parsed = parseYaml(raw) as unknown;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? (parsed as Record<string, unknown>)
+            : {};
+    } catch {
+        return {};
+    }
+}
+
+function stringList(value: unknown): string[] {
+    if (Array.isArray(value)) return value.filter((v): v is string => typeof v === 'string');
+    if (typeof value === 'string') return [value];
+    return [];
+}
+
+/** Parse the pack registry into id → hard requirements. */
+export function readPacks(file: string): Map<string, PackDef> {
+    const parsed = parseYaml(fs.readFileSync(file, 'utf-8')) as unknown;
+    const out = new Map<string, PackDef>();
+    if (!Array.isArray(parsed)) return out;
+    for (const entry of parsed) {
+        if (!entry || typeof entry !== 'object') continue;
+        const record = entry as Record<string, unknown>;
+        const id = record['id'];
+        if (typeof id !== 'string') continue;
+        out.set(id, { id, requires: stringList(record['requires']) });
+    }
+    return out;
+}
+
+/** `pack + requires*` — what an install selecting `pack` actually receives. */
+export function installClosure(pack: string, packs: Map<string, PackDef>): Set<string> {
+    const seen = new Set<string>();
+    const queue = [pack];
+    while (queue.length > 0) {
+        const current = queue.pop()!;
+        if (seen.has(current)) continue;
+        seen.add(current);
+        for (const required of packs.get(current)?.requires ?? []) queue.push(required);
+    }
+    return seen;
+}
+
+interface RuleInfo {
+    name: string;
+    packs: string[];
+    routesToSkills: string[];
+}
+
+export function readRules(dir: string): RuleInfo[] {
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => {
+            const fm = frontmatterObject(path.join(dir, f));
+            return {
+                name: f.replace(/\.md$/, ''),
+                packs: stringList(fm['packs']),
+                routesToSkills: stringList(fm['routes_to'])
+                    .filter((r) => r.startsWith('skill:'))
+                    .map((r) => r.slice('skill:'.length)),
+            };
+        });
+}
+
+export function readSkillPacks(dir: string): Map<string, string[]> {
+    const out = new Map<string, string[]>();
+    for (const name of fs.readdirSync(dir)) {
+        const file = path.join(dir, name, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        out.set(name, stringList(frontmatterObject(file)['packs']));
+    }
+    return out;
+}
+
+export function analyze(
+    rules: RuleInfo[],
+    skillPacks: Map<string, string[]>,
+    packs: Map<string, PackDef>,
+): Finding[] {
+    const findings: Finding[] = [];
+
+    // 1. unreachable-route — the obligation without the artefact.
+    for (const rule of rules) {
+        if (rule.packs.length === 0) continue; // unscoped rule ships everywhere
+        for (const skill of rule.routesToSkills) {
+            const target = skillPacks.get(skill);
+            if (target === undefined) continue; // a missing skill is check_references' job
+            if (target.length === 0) continue; // unscoped skill ships everywhere
+            const unreachableFrom = rule.packs.filter((p) => {
+                const closure = installClosure(p, packs);
+                return !target.some((tp) => closure.has(tp));
+            });
+            if (unreachableFrom.length === 0) continue;
+            findings.push({
+                kind: 'unreachable-route',
+                subject: `${rule.name} → skill:${skill}`,
+                detail: `rule pack(s) [${unreachableFrom.join(', ')}] do not reach skill pack(s) [${target.join(', ')}]`,
+            });
+        }
+    }
+
+    // 2. unrouted-skill — the artefact without a path to it.
+    const routedSkills = new Set(rules.flatMap((r) => r.routesToSkills));
+    for (const skill of routedSkills) {
+        const target = skillPacks.get(skill);
+        if (target === undefined || target.length === 0) continue;
+        const routingRules = rules.filter((r) => r.routesToSkills.includes(skill));
+        for (const skillPack of target) {
+            const closure = installClosure(skillPack, packs);
+            const reached = routingRules.some(
+                (r) => r.packs.length === 0 || r.packs.some((p) => closure.has(p)),
+            );
+            if (reached) continue;
+            findings.push({
+                kind: 'unrouted-skill',
+                subject: `skill:${skill}`,
+                detail: `an install of pack [${skillPack}] receives this skill but none of its routing rule(s) [${routingRules.map((r) => r.name).join(', ')}]`,
+            });
+        }
+    }
+
+    return findings;
+}
+
+function main(): number {
+    const packs = readPacks(PACKS_FILE);
+    const rules = readRules(RULES_DIR);
+    const skillPacks = readSkillPacks(SKILLS_DIR);
+
+    if (rules.length === 0 || skillPacks.size === 0 || packs.size === 0) {
+        process.stderr.write(
+            `❌  lint_rule_skill_pack_reach scanned nothing (rules=${rules.length}, skills=${skillPacks.size}, packs=${packs.size}) — refusing to report a pass\n`,
+        );
+        return 2;
+    }
+
+    const findings = analyze(rules, skillPacks, packs);
+    const errors = findings.filter((f) => f.kind === 'unreachable-route');
+    const advisories = findings.filter((f) => f.kind === 'unrouted-skill');
+
+    // --quiet suppresses the per-finding lines but never the count line: this
+    // gate is expected to stay non-empty for a while, and a quiet run that
+    // printed nothing at all would read as clean.
+    const quiet = process.argv.includes('--quiet');
+    if (!quiet) {
+        for (const finding of errors) {
+            process.stdout.write(`❌  ${finding.subject} — ${finding.detail}\n`);
+        }
+        for (const finding of advisories) {
+            process.stdout.write(`⚠️  ${finding.subject} — ${finding.detail}\n`);
+        }
+    }
+
+    const strict = process.argv.includes('--strict');
+    process.stdout.write(
+        `scanned: ${rules.length} rule(s), ${skillPacks.size} skill(s), ${packs.size} pack(s) — ${errors.length} unreachable-route, ${advisories.length} unrouted-skill\n`,
+    );
+    if (errors.length > 0 && !strict) {
+        process.stdout.write(
+            `advisory run: ${errors.length} unreachable-route finding(s) reported, exit 0. Promote with --strict once the set is empty.\n`,
+        );
+    }
+    return strict && errors.length > 0 ? 1 : 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {
+    try {
+        process.exit(main());
+    } catch (error) {
+        process.stderr.write(`❌  ${(error as Error).message}\n`);
+        process.exit(2);
+    }
+}

package/src/scripts/memory_lookup.ts

@@ -529,8 +529,7 @@ function* _iter_knowledge_entries(): Generator<[string, Record<string, unknown>]
 /**
  * Naive relevance score: max over keys of (glob-match | substring).
  *
- * Good enough for the `absent` path where retrieval is best-effort.
- * The `present` path returns a real score from agent-memory.
+ * Retrieval is best-effort by design — this is the only scoring path.
  *
  * DOCUMENTED FALLBACK (road-to-reachable-code-memory Phase 6 / ADR-129):
  * this is the primary, always-available scorer. It has a known correctness

package/src/scripts/report_consultation_rate.ts

@@ -0,0 +1,358 @@
+#!/usr/bin/env tsx
+/**
+ * report_consultation_rate — the consultation half of the pre-registered
+ * frontend-skill metrics, computed from transcripts.
+ *
+ * WHAT IT MEASURES, AND WHY ONLY HALF.
+ * `agents/settings/contexts/skill-catalogue-baseline.md` pre-registers two
+ * rates. Exactly one of them is mechanically computable, and the reason the
+ * other is not is a roadmap non-goal rather than an oversight:
+ *
+ *   CONSULTATION RATE — share of UI-write turns in a session that happened
+ *   AFTER the session opened a design surface. Every input is a tool call:
+ *   the write, its path, the prior read. Computable, and computed here.
+ *
+ *   DISCHARGE RATE — share of UI-write turns followed by a review verdict
+ *   that is "render-scoped or explicitly static-scoped". A verdict is PROSE.
+ *   Deciding whether a paragraph is a scoped verdict means matching prose,
+ *   which the roadmap's non-goals forbid ("no prose-matching missed-activation
+ *   detector", the FC-8 boundary the round-6 phase drew). So this script does
+ *   NOT compute it, and does not approximate it under its name.
+ *
+ * What it offers instead is a labelled PROXY: how often a UI-write turn is
+ * followed, in the same session, by opening `design-review`. That is a
+ * consultation-shaped fact about the review skill, not a fact about a verdict —
+ * an agent can open the skill and still write "looks good". Reported under its
+ * own name so it can never be quoted as the discharge rate.
+ *
+ * ONE EVENT STREAM, NOT TWO. The UI-write and consultation predicates are
+ * imported from the `ui-route-nudge` concern rather than restated. A metric
+ * whose denominator drifted from the nudge's trigger would make any later A/B
+ * uninterpretable — the two would be measuring different populations while
+ * appearing to measure one.
+ *
+ * PRIVACY, stated at the precision the code actually holds. The text report is
+ * counts and rates only. The `--json` form additionally echoes the SCAN ROOT
+ * (`store`) — the directory the caller pointed at, which is a local path and is
+ * the one thing a reader needs to know what was measured. Nothing else crosses:
+ * no transcript filename, no session id, no path from inside a session, no
+ * prompt or file content. The measurement reads those and keeps none of them.
+ *
+ * Exit: 0 always, except a usage/IO error (1). Advisory — it gates nothing.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+    isConsultation,
+    isUiWrite,
+    type ToolEvent,
+} from './hooks/ui_route_nudge_hook.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Tool names that propose new file content on this host. */
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'MultiEdit']);
+
+/** The skill whose opening the discharge PROXY counts. */
+const REVIEW_SURFACE = 'design-review';
+
+/**
+ * One transcript tool call, tagged with the assistant turn it belongs to.
+ *
+ * The turn index is what makes the published unit honest. The pre-registered
+ * metric is a share of UI *turns*; an earlier version counted `tool_use` parts
+ * and published the count as turns, which inflates any turn that writes two
+ * files and mixes a per-session numerator with a per-call denominator.
+ */
+export interface TimedEvent {
+    event: ToolEvent;
+    turn: number;
+}
+
+export interface SessionMeasurement {
+    /** Assistant turns containing at least one UI write. */
+    uiWriteTurns: number;
+    /** Those turns that followed a consultation in the same session. */
+    consulted: number;
+    /** Those turns followed later by opening the review skill. */
+    reviewOpenedAfter: number;
+}
+
+export interface RateReport {
+    store: string;
+    /** False when the store directory does not exist — never the same as empty. */
+    storeExists: boolean;
+    /** Transcripts read. Capped by --limit; the cap is reported when it bites. */
+    sessions: number;
+    /** True when --limit truncated the store rather than reading all of it. */
+    truncated: boolean;
+    sessionsWithUiWrite: number;
+    /** Assistant turns containing at least one UI write — the denominator. */
+    uiWriteTurns: number;
+    consulted: number;
+    reviewOpenedAfter: number;
+}
+
+/**
+ * Default transcript store for a project directory.
+ *
+ * The host flattens the path by replacing BOTH separators and dots — a worktree
+ * at `<repo>/.claude/worktrees/x` lands in `…-agent-config--claude-worktrees-x`,
+ * with two dashes where `/.` was. Replacing only `/` (the shape the older census
+ * helper carries) produces a directory that does not exist, and the caller then
+ * reads a clean zero out of a store it never found.
+ */
+export function defaultStore(cwd: string): string {
+    return path.join(os.homedir(), '.claude', 'projects', cwd.replace(/[/.]/g, '-'));
+}
+
+/**
+ * Map one transcript `tool_use` part onto the event shape the nudge decides
+ * over. Returns null for parts that carry no path — they cannot be either a
+ * UI write or a consultation.
+ */
+export function toolUseToEvent(part: Record<string, unknown>): ToolEvent | null {
+    const name = part['name'];
+    const input = part['input'];
+    if (typeof name !== 'string' || input === null || typeof input !== 'object') return null;
+    const ti = input as Record<string, unknown>;
+    const fileVal = ti['file_path'] ?? ti['path'] ?? ti['filePath'] ?? ti['notebook_path'];
+    if (typeof fileVal !== 'string' || fileVal === '') return null;
+    return { file: fileVal, isWrite: WRITE_TOOLS.has(name) };
+}
+
+/**
+ * Walk one session's tool events in order and measure it.
+ *
+ * Shares the nudge's PREDICATES (`isUiWrite`, `isConsultation`) but not its
+ * `decide`, deliberately: `decide` stops warning after `MAX_NUDGES`, which is
+ * correct for a reminder and wrong for a denominator — measuring through it
+ * would silently drop every UI write past the second one in a session.
+ *
+ * Ordering is load-bearing. A consultation counts only for writes that come
+ * after it; a session that opens `fe-design` at the end does not retroactively
+ * consult for the file it already wrote.
+ */
+export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement {
+    const out: SessionMeasurement = { uiWriteTurns: 0, consulted: 0, reviewOpenedAfter: 0 };
+    let consulted = false;
+    /** turn -> was the session already consulted when that turn first wrote UI */
+    const writeTurns = new Map<number, boolean>();
+    let lastReviewOpenAt = -1;
+    const reviewOpenPositions: number[] = [];
+    const writePositions: Array<{ position: number; turn: number }> = [];
+
+    timed.forEach(({ event, turn }, position) => {
+        if (isUiWrite(event)) {
+            if (!writeTurns.has(turn)) {
+                writeTurns.set(turn, consulted);
+                writePositions.push({ position, turn });
+            }
+            return;
+        }
+        if (isConsultation(event)) {
+            consulted = true;
+            if (event.file.replace(/\\/g, '/').toLowerCase().includes(`skills/${REVIEW_SURFACE}/`)) {
+                reviewOpenPositions.push(position);
+                lastReviewOpenAt = position;
+            }
+        }
+    });
+
+    out.uiWriteTurns = writeTurns.size;
+    for (const wasConsulted of writeTurns.values()) if (wasConsulted) out.consulted += 1;
+    // A single max comparison, not a scan per write: the proxy asks only whether
+    // ANY review-open follows, so the last one decides every earlier write.
+    void reviewOpenPositions;
+    for (const { position } of writePositions) {
+        if (lastReviewOpenAt > position) out.reviewOpenedAfter += 1;
+    }
+    return out;
+}
+
+/** Read every `tool_use` part of one transcript file, in order. */
+export function readSessionEvents(file: string): TimedEvent[] {
+    const events: TimedEvent[] = [];
+    let turn = -1;
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+        if (!line.trim()) continue;
+        let entry: Record<string, unknown>;
+        try {
+            entry = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+            continue;
+        }
+        if (entry['type'] !== 'assistant') continue;
+        turn += 1;
+        const msg = entry['message'];
+        const content =
+            msg !== null && typeof msg === 'object'
+                ? (msg as Record<string, unknown>)['content']
+                : null;
+        if (!Array.isArray(content)) continue;
+        for (const part of content) {
+            if (part === null || typeof part !== 'object') continue;
+            const p = part as Record<string, unknown>;
+            if (p['type'] !== 'tool_use') continue;
+            const event = toolUseToEvent(p);
+            if (event) events.push({ event, turn });
+        }
+    }
+    return events;
+}
+
+export function measureStore(store: string, limit: number): RateReport {
+    const report: RateReport = {
+        store,
+        storeExists: fs.existsSync(store),
+        sessions: 0,
+        truncated: false,
+        sessionsWithUiWrite: 0,
+        uiWriteTurns: 0,
+        consulted: 0,
+        reviewOpenedAfter: 0,
+    };
+    // A store that is not there and a store with nothing in it are different
+    // findings, and only one of them is about the agent. Collapsing them into
+    // one clean zero is the failure this repo has recorded four times.
+    if (!report.storeExists) return report;
+
+    // mtime is read ONCE per file, not inside the comparator: a comparator that
+    // stats is O(n log n) syscalls and throws ENOENT if a live store rotates a
+    // transcript mid-sort — a measurement must not crash on the store being used.
+    const all = fs
+        .readdirSync(store)
+        .filter((f) => f.endsWith('.jsonl'))
+        .map((f) => path.join(store, f))
+        .map((file) => {
+            let mtimeMs = 0;
+            try {
+                mtimeMs = fs.statSync(file).mtimeMs;
+            } catch {
+                /* vanished between readdir and stat — sort it last, skip it below */
+            }
+            return { file, mtimeMs };
+        })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+    const files = all.slice(0, limit).map((f) => f.file);
+    report.truncated = all.length > files.length;
+    report.sessions = files.length;
+    for (const file of files) {
+        let measured: SessionMeasurement;
+        try {
+            measured = measureSession(readSessionEvents(file));
+        } catch {
+            continue; // rotated or unreadable transcript — skip, never crash
+        }
+        if (measured.uiWriteTurns === 0) continue;
+        report.sessionsWithUiWrite += 1;
+        report.uiWriteTurns += measured.uiWriteTurns;
+        report.consulted += measured.consulted;
+        report.reviewOpenedAfter += measured.reviewOpenedAfter;
+    }
+    return report;
+}
+
+function pct(n: number, d: number): string {
+    return d === 0 ? 'n/a' : `${((100 * n) / d).toFixed(1)}%`;
+}
+
+export function render(report: RateReport, threshold: number): string {
+    const lines: string[] = [];
+    lines.push('consultation rate — advisory, gates on nothing');
+    lines.push('');
+    if (!report.storeExists) {
+        lines.push('  ❌  transcript store not found — nothing was measured.');
+        lines.push('      This is not a rate of zero. Point --store at a real store;');
+        lines.push('      `ls ~/.claude/projects` lists them.');
+        return lines.join('\n');
+    }
+    lines.push(
+        `  sessions scanned                 ${report.sessions}${report.truncated ? ' (TRUNCATED by --limit)' : ''}`,
+    );
+    lines.push(`  sessions with a UI write         ${report.sessionsWithUiWrite}`);
+    lines.push(`  UI-write turns                   ${report.uiWriteTurns}`);
+    lines.push('');
+    lines.push(
+        `  CONSULTATION RATE                ${pct(report.consulted, report.uiWriteTurns)}  (${report.consulted}/${report.uiWriteTurns})`,
+    );
+    lines.push(
+        `  discharge PROXY (review opened)  ${pct(report.reviewOpenedAfter, report.uiWriteTurns)}  (${report.reviewOpenedAfter}/${report.uiWriteTurns})`,
+    );
+    lines.push('');
+
+    if (report.sessionsWithUiWrite < threshold) {
+        lines.push(
+            `  ⚠  ${report.sessionsWithUiWrite} session(s) with a UI write — below the pre-registered floor of ${threshold}.`,
+        );
+        lines.push('     Report the rate as provisional; it is not yet a baseline.');
+        lines.push('');
+    }
+
+    lines.push('  The PROXY is not the discharge rate. It counts a UI-write turn followed by');
+    lines.push('  opening `design-review` in the same session. A verdict is prose, and matching');
+    lines.push('  prose is a roadmap non-goal, so the discharge rate stays unmeasured rather');
+    lines.push('  than approximated under its own name.');
+    return lines.join('\n');
+}
+
+/**
+ * Value of `flag`, or `fallback` when it is absent.
+ *
+ * Throws when the flag is present with no value after it. The earlier version
+ * returned the fallback there, so `--store` as the last argv element silently
+ * measured the DEFAULT store — and since the text report never prints the scan
+ * root, the substitution was invisible in exactly the output a reader would
+ * publish. A usage error is the only honest answer to "you asked for a store
+ * and named none".
+ */
+function argValue(flag: string, fallback: string): string {
+    const index = process.argv.indexOf(flag);
+    if (index === -1) return fallback;
+    const value = process.argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+
+/** Parse a positive-integer flag, or fail loudly. Never silently NaN. */
+function intArg(flag: string, fallback: string): number {
+    const raw = argValue(flag, fallback);
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${flag} must be a positive integer (got ${JSON.stringify(raw)})`);
+    }
+    return parsed;
+}
+
+function main(): number {
+    const store = argValue('--store', defaultStore(process.cwd()));
+    const limit = intArg('--limit', '200');
+    // Validated for the same reason --limit is, and it was not: a NaN threshold
+    // makes `sessionsWithUiWrite < NaN` false, which SUPPRESSES the provisional
+    // warning — the run then reads as a settled baseline over any corpus.
+    const threshold = intArg('--min-sessions', '20');
+
+    const report = measureStore(store, limit);
+    if (process.argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+        process.stdout.write(`${render(report, threshold)}\n`);
+    }
+    return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {
+    try {
+        process.exit(main());
+    } catch (error) {
+        process.stderr.write(`❌  ${(error as Error).message}\n`);
+        process.exit(1);
+    }
+}

package/src/scripts/report_skill_activation.ts

@@ -114,7 +114,11 @@ export interface UsageReport {
 
 /** Default store for the current working directory, mangled the way the host does. */
 export function defaultStore(cwd: string): string {
-  return path.join(os.homedir(), '.claude', 'projects', cwd.replace(/\//g, '-'));
+  // Dots are flattened too, not only separators: a worktree at
+  // `<repo>/.claude/worktrees/x` lands in `…-agent-config--claude-worktrees-x`.
+  // Replacing only `/` returns a directory that does not exist, and the caller
+  // then reads a clean zero out of a store it never found.
+  return path.join(os.homedir(), '.claude', 'projects', cwd.replace(/[/.]/g, '-'));
 }
 
 export function measureUsage(store: string, limit: number): UsageReport {

package/src/scripts/schemas/command.schema.json

@@ -257,6 +257,10 @@
       "type": "boolean",
       "description": "AI OS Product UI allowlist (road-to-ai-os-product-ui.md Phase 1). When true, the command is exposed in the browser /tasks surface and may be spawned by POST /api/v1/task/run. Default false — commands that touch git, secrets, or run destructive migrations must stay false (terminal only). Per-command opt-in, never opt-out."
     },
+    "requires_confirmation": {
+      "type": "boolean",
+      "description": "Optional, additive: the command's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). Twin of the same key in skill.schema.json's execution block; commands carry no execution block, so it sits top-level. A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. Mechanism: stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate with `agent-config gates --pending`. Nothing BINDS on it yet (blocker confirmation-degraded-host-semantics: 5 of 8 hosts have no pre_tool_use slot)."
+    },
     "auto_detect": {
       "type": "boolean",
       "description": "6.1.0 orchestrator auto-detection opt-in (Step 1, non-interactive-contract). When true, the orchestrator auto-detects its sub-command per the confidence-tiered detection table instead of always showing the menu, honoring the non-interactive-contract (TTY/CI detection, --yes/--json, abort schemas). Per-orchestrator kill-switch: set false to always show the menu; overridable globally via commands.auto_detect in .agent-settings.yml and per-invocation via --no-auto-detect. Only orchestrators (type: orchestrator) carry it."

package/src/scripts/schemas/skill.schema.json

@@ -222,6 +222,10 @@
           },
           "description": "U3 (ecosystem harvest): optional deny-list layered UNDER allowed_tools — defense-in-depth; a tool matching here is refused even if a broad allow pattern would admit it. Supports the scoped-grant syntax (e.g. Bash(git push:*))."
         },
+        "requires_confirmation": {
+          "type": "boolean",
+          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: on 5 of 8 hosts there is no pre_tool_use slot, so a guard would degrade to prose while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
+        },
         "command": {
           "type": "array",
           "minItems": 1,