@event4u/agent-config 9.34.0 → 9.36.0

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -9,11 +9,17 @@
  * is deliberately not another reminder. It is a check at the point of
  * delivery that can say no.
  *
- * Two detectors ride on one guard, because building the unsafe part twice
+ * Three detectors ride on one guard, because building the unsafe part twice
  * is how a second detector becomes a second outage:
  *
  *   A — promissory closing  (FC-5, 20 measured occurrences)
  *   B — language mismatch   (19 measured occurrences, fresh pin present)
+ *   C — unverified edit     (the turn changed a file and ran nothing that could
+ *                            have checked it — verify-before-complete's gate,
+ *                            read off the turn's TOOL CALLS rather than its
+ *                            prose, which is why `readTranscriptTail` collects
+ *                            them: `_messageText` keeps `type === 'text'` blocks
+ *                            only, so tool activity is invisible to A and B.)
  *
  * ## Re-entrancy — the shape, stated before registration
  *
@@ -60,10 +66,11 @@
  * mechanism exists and soaks before it binds" — two prior hook-severity
  * mistakes plus a turn-end blast radius made default-on uninsurable in
  * their reading. Both are satisfied literally: the MASTER switch
- * (`hooks.turn_end_gate.enabled`) is default OFF, and WITHIN it both
- * detectors are default ON. A maintainer who opts in gets both without
+ * (`hooks.turn_end_gate.enabled`) is default OFF, and WITHIN it every
+ * detector is default ON. A maintainer who opts in gets all of them without
  * further configuration; until then this concern is a no-op that costs one
- * settings-cascade read per turn-end.
+ * settings-cascade read per turn-end. Detector C landed under the same rule —
+ * the master switch was NOT flipped when it shipped.
  *
  * CONTRACT: dispatcher-internal exit is 1 (EXIT_BLOCK) on a fire, 0
  * otherwise. `fail_closed: false` — deliberately. A crash in a turn-end
@@ -71,6 +78,16 @@
  * crash to a block is the outage this whole file is arranged to avoid.
  * Every unreadable input, missing transcript, absent pin, or malformed
  * state resolves to silence.
+ *
+ * The severity mapping was re-probed when C landed, because
+ * `dispatch_hook.ts` defines `EXIT_WARN = 2` beside `EXIT_BLOCK = 1` and an
+ * advisory finding delivered on the wrong code becomes a hard deny. Result:
+ * this file emits ONLY 0 and 1 internally, `concern_block_exit_parity` pins the
+ * 1, and the dispatcher translates a stop-slot block to host exit **2** —
+ * which a spawned test in `turn_end_gate_hook.test.ts` asserts, because on the
+ * stop slot exit 1 would let the turn end anyway. C is a refusal like A and B,
+ * not an advisory, so there is no advisory path here to put on the wrong code.
+ * Probed, not assumed.
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
@@ -104,7 +121,7 @@ const EXIT_ALLOW = 0;
 export const TRANSCRIPT_READ_MAX_BYTES = 8 * 1024 * 1024; // 8 MB
 
 /** Detector identity, used in the state marker and the refusal text. */
-export type DetectorId = 'promissory' | 'language';
+export type DetectorId = 'promissory' | 'language' | 'verification';
 
 export interface Finding {
     detector: DetectorId;
@@ -360,6 +377,71 @@ export function detectLanguage(reply: string, pinned: Verdict): Finding | null {
     };
 }
 
+// ---------------------------------------------------------------------------
+// Detector 3 — an edit the turn never verified
+// ---------------------------------------------------------------------------
+
+/** Tools that CHANGE the tree. The three write tools, nothing inferred. */
+const _EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+/**
+ * Shell commands that count as verification.
+ *
+ * A positive list, and deliberately narrow. The alternative — treating any
+ * `Bash` call as verification — was rejected because `ls` would then clear an
+ * unverified edit, which is the failure mode `verify-before-complete` names
+ * ("relying on partial verification"). The cost of narrowness is a MISSED
+ * detection when a project verifies by some command not listed here, and that is
+ * the safe direction for a gate that can refuse a turn: a false negative costs
+ * one unguarded turn, a false positive teaches the user to switch the gate off.
+ */
+const _VERIFY_RE =
+    /\b(test|tests|vitest|jest|pytest|phpunit|pest|tsc|eslint|ruff|mypy|pyright|clippy|typecheck|lint|build|ci|preflight|smoke[-_:a-z]*|check[-_:a-z]*|validate[-_:a-z]*)\b|\b(task|npm|pnpm|yarn|composer|cargo|go|make|php artisan|bun)\s+(run\s+)?\S*(test|check|lint|build|ci|typecheck)/i;
+
+export function isVerificationCommand(command: string): boolean {
+    return _VERIFY_RE.test(command);
+}
+
+/**
+ * Fire when the turn changed a file and then ran nothing that could have
+ * checked it.
+ *
+ * The window is "after the LAST edit", not "anywhere in the turn": a test run
+ * before the final edit demonstrably did not exercise it, which is the same
+ * freshness argument `verify-before-complete` makes about trusting an earlier
+ * run ("no verification command run in this message → you cannot claim it
+ * passes"). Ordering is the only thing that distinguishes the two, so the
+ * detector reads the sequence rather than a pair of counts.
+ *
+ * Silent when the turn edited nothing — a read-only or conversational turn has
+ * no claim to verify, and refusing one would make the gate fire on the majority
+ * of turns, which is how a guard gets disabled.
+ */
+export function detectUnverifiedEdit(toolCalls: readonly ToolCall[]): Finding | null {
+    let lastEdit = -1;
+    for (let i = 0; i < toolCalls.length; i += 1) {
+        if (_EDIT_TOOLS.has(toolCalls[i]!.name)) lastEdit = i;
+    }
+    if (lastEdit === -1) return null;
+    for (let i = lastEdit + 1; i < toolCalls.length; i += 1) {
+        const c = toolCalls[i]!;
+        if (c.name === 'Bash' && c.command !== undefined && isVerificationCommand(c.command)) {
+            return null;
+        }
+    }
+    const edited = toolCalls[lastEdit]!.path;
+    return {
+        detector: 'verification',
+        // The path, never the diff: the evidence span is quoted into a refusal,
+        // and `ToolCall` is shaped so a file body cannot reach it.
+        evidence: edited ?? toolCalls[lastEdit]!.name,
+        reason:
+            'this turn changed a file and then ran no verification command — ' +
+            'no test, type-check, lint or build call follows the last edit ' +
+            '(verify-before-complete: a claim without a fresh run is unverified)',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Re-entrancy — the guard, keyed on the turn, not on the reply
 // ---------------------------------------------------------------------------
@@ -450,6 +532,24 @@ function markRefusedTurn(
 // Transcript
 // ---------------------------------------------------------------------------
 
+/**
+ * One tool call the assistant made, reduced to what a detector can reason
+ * about: the tool's name, the shell command when it is a shell call, and the
+ * target path when it is a file write.
+ *
+ * Nothing else is kept. A tool input can hold a whole file body, and this
+ * struct is what a refusal quotes back — so it is shaped to be INCAPABLE of
+ * carrying one, the same PII-exclusion-by-construction discipline
+ * `domain-safety-pii` § Surface 2 asks for in a log line.
+ */
+export interface ToolCall {
+    name: string;
+    /** `Bash` only — the command line, so "did anything verify" is answerable. */
+    command?: string;
+    /** Edit/Write only — the file the turn changed, used as the evidence span. */
+    path?: string;
+}
+
 export interface TranscriptTail {
     lastAssistant: string;
     /**
@@ -458,6 +558,14 @@ export interface TranscriptTail {
      * identity; see `alreadyRefusedTurn` for why the prompt's text is not.
      */
     turnOrdinal: number;
+    /**
+     * The tool calls of the CURRENT turn, in order — reset at every genuine user
+     * prompt, so a verification from three turns ago cannot vouch for an edit
+     * made now. `_messageText` keeps only `type === 'text'` blocks, which is why
+     * this needed its own extraction rather than a reading of `lastAssistant`:
+     * tool activity is not in the prose at all.
+     */
+    toolCalls: ToolCall[];
 }
 
 /**
@@ -475,7 +583,7 @@ export function readTranscriptTail(
     transcriptPath: string,
     opts: { homeDir?: string; maxBytes?: number } = {},
 ): TranscriptTail {
-    const empty: TranscriptTail = { lastAssistant: '', turnOrdinal: 0 };
+    const empty: TranscriptTail = { lastAssistant: '', turnOrdinal: 0, toolCalls: [] };
     if (!transcriptPath || !isSafeTranscriptPath(transcriptPath, opts)) return empty;
     let lines: string[];
     try {
@@ -494,6 +602,7 @@ export function readTranscriptTail(
     }
     let lastAssistant = '';
     let turnOrdinal = 0;
+    let toolCalls: ToolCall[] = [];
     for (const rawLine of lines) {
         const line = rawLine.trim();
         if (!line) continue;
@@ -514,15 +623,55 @@ export function readTranscriptTail(
         if (role !== 'assistant' && role !== 'user') continue;
         const msg = entry['message'];
         if (typeof msg !== 'object' || msg === null || Array.isArray(msg)) continue;
-        const text = _messageText((msg as Record<string, unknown>)['content']);
+        const content = (msg as Record<string, unknown>)['content'];
+        // Tool calls are read BEFORE the text guard: an assistant entry that is
+        // only a tool_use block has no text at all, so `continue`-ing on a null
+        // text would drop exactly the entries this detector exists to see.
+        if (role === 'assistant') {
+            toolCalls.push(..._toolCalls(content));
+        }
+        const text = _messageText(content);
         if (text === null) continue;
         if (role === 'assistant') {
             lastAssistant = text;
         } else if (!isSyntheticPrompt(text)) {
             turnOrdinal += 1;
+            // A genuine user prompt starts a new turn, so the previous turn's
+            // tool activity stops counting. Without this reset, a verification
+            // run three turns ago would vouch for an edit made now — the
+            // "fresh" in edit-without-FRESH-verification is this line.
+            toolCalls = [];
+        }
+    }
+    return { lastAssistant: lastAssistant.trim(), turnOrdinal, toolCalls };
+}
+
+/**
+ * Extract this entry's tool calls, keeping only name, shell command and target
+ * path. A tool input can hold a whole file body; nothing but those three fields
+ * is carried forward.
+ */
+function _toolCalls(content: unknown): ToolCall[] {
+    if (!Array.isArray(content)) return [];
+    const out: ToolCall[] = [];
+    for (const blk of content) {
+        if (typeof blk !== 'object' || blk === null || Array.isArray(blk)) continue;
+        const b = blk as Record<string, unknown>;
+        if (b['type'] !== 'tool_use') continue;
+        const name = b['name'];
+        if (typeof name !== 'string') continue;
+        const input = b['input'];
+        const call: ToolCall = { name };
+        if (typeof input === 'object' && input !== null && !Array.isArray(input)) {
+            const inp = input as Record<string, unknown>;
+            const cmd = inp['command'];
+            if (typeof cmd === 'string') call.command = cmd;
+            const p = inp['file_path'] ?? inp['path'] ?? inp['notebook_path'];
+            if (typeof p === 'string') call.path = p;
         }
+        out.push(call);
     }
-    return { lastAssistant: lastAssistant.trim(), turnOrdinal };
+    return out;
 }
 
 function _messageText(content: unknown): string | null {
@@ -547,6 +696,7 @@ export interface GateSettings {
     enabled: boolean;
     promissory: boolean;
     language: boolean;
+    verification: boolean;
 }
 
 /**
@@ -581,7 +731,12 @@ function _isOn(v: unknown): boolean | null {
  * a turn-end outranks one settings read per turn-end.
  */
 export function readGateSettings(workspaceRoot: string): GateSettings {
-    const off: GateSettings = { enabled: false, promissory: true, language: true };
+    const off: GateSettings = {
+        enabled: false,
+        promissory: true,
+        language: true,
+        verification: true,
+    };
     let settings: Record<string, unknown>;
     try {
         settings = load_agent_settings({ cwd: workspaceRoot }) as Record<string, unknown>;
@@ -601,6 +756,7 @@ export function readGateSettings(workspaceRoot: string): GateSettings {
         enabled: flag('enabled', false),
         promissory: flag('promissory', true),
         language: flag('language', true),
+        verification: flag('verification', true),
     };
 }
 
@@ -644,7 +800,7 @@ export function main(): number {
     // in production while its comment claimed it was enforced — the same
     // fixed-the-definition-not-the-caller shape as two other findings in that
     // round, which is why this line exists rather than a default parameter.
-    const { lastAssistant, turnOrdinal } = readTranscriptTail(transcriptPath, {
+    const { lastAssistant, turnOrdinal, toolCalls } = readTranscriptTail(transcriptPath, {
         maxBytes: TRANSCRIPT_READ_MAX_BYTES,
     });
     if (!lastAssistant) return EXIT_ALLOW;
@@ -671,6 +827,10 @@ export function main(): number {
         const f = detectLanguage(lastAssistant, readLanguagePin(workspaceRoot));
         if (f) findings.push(f);
     }
+    if (settings.verification) {
+        const f = detectUnverifiedEdit(toolCalls);
+        if (f) findings.push(f);
+    }
     if (findings.length === 0) return EXIT_ALLOW;
 
     markRefusedTurn(workspaceRoot, sessionKey, turnOrdinal, findings[0]!.detector);
@@ -680,7 +840,8 @@ export function main(): number {
     );
     process.stderr.write(
         `turn-end-gate: REFUSED — this turn is not finished.\n${lines.join('\n')}\n` +
-            '  Do the promised work now, or correct the language, then end the turn.\n' +
+            '  Do the promised work now, correct the language, or run the ' +
+            'verification the edit needs, then end the turn.\n' +
             '  This turn will not be refused a second time.\n' +
             '  Disable: hooks.turn_end_gate.enabled: false in .agent-settings.yml\n',
     );

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse UI-route nudge — deterministic, warn-only, default-OFF.
+ *
+ * The two UI rules have `enforced_by: none` and say so honestly: nothing
+ * observes whether a UI write consulted the design surface first. This concern
+ * observes it — and it is a nudge, not a gate. It never blocks (dispatcher
+ * contract: 0 allow · 2 warn), because the obligation it points at is a
+ * judgement call and a block on a judgement call trades an ignore-problem for
+ * a friction-problem.
+ *
+ * IT DOES NOT READ THE RULES. Stated because the first draft of this header
+ * claimed it did. The UI-surface decision comes from `_lib/ui_surface.ts`; no
+ * code here parses `src/rules/*.md` frontmatter, so the rules' `keyword:`
+ * triggers still have no runtime consumer and this predicate is deliberately
+ * wider than their `file_pattern` list. The two are kept from drifting by
+ * `ui_rule_triggers.test.ts`, which asserts every declared pattern is accepted
+ * here — a test, not a dependency.
+ *
+ * WHAT IT OBSERVES, WHICH IS ALSO THE MEASUREMENT.
+ * Every PreToolUse event passes through here. A read or search touching a
+ * design surface (`fe-design`, `existing-ui-audit`, `design-review`,
+ * `design-intelligence`) latches "consulted" for the session. A Write or Edit
+ * to a UI path with no such latch is the case the nudge exists for. That latch
+ * is exactly the consultation signal the pre-registered consultation rate
+ * counts, so the nudge and the metric read the same event stream rather than
+ * two populations that could drift apart.
+ *
+ * ANTI-LOOP. At most `MAX_NUDGES` per session, then silent — the same
+ * degradation valve `design_slop_hook` carries, for the same reason: an agent
+ * that has decided to proceed must not be re-prompted into a loop.
+ *
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` exists on three
+ * hosts. Everywhere else this concern has nowhere to bind and the obligation
+ * stays model-carried, exactly as the two rules already declare. Run
+ * `agent-config hooks:status` for the host you are actually on.
+ *
+ * Default-OFF: no-ops unless `hooks.ui_route_nudge.enabled: true`.
+ * fail_closed: false — any error returns allow.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { hookSectionEnabled } from '../_lib/hook_settings.js';
+import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+/** Nudges per session before the valve goes silent. */
+export const MAX_NUDGES = 2;
+
+/** Reads or searches that count as consulting the design surface. */
+export const DESIGN_SURFACES = [
+    'fe-design',
+    'existing-ui-audit',
+    'design-review',
+    'design-intelligence',
+] as const;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function unwrap(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+export interface ToolEvent {
+    /** Path the tool touches; "" when the tool names none. */
+    file: string;
+    /** True when the tool proposes new content (Write / Edit). */
+    isWrite: boolean;
+}
+
+/** Best-effort extraction; mirrors the shape `design_slop_hook` reads. */
+export function extractEvent(outer: JsonObject): ToolEvent | null {
+    const envelope = unwrap(outer);
+    const ti = envelope['tool_input'] ?? envelope['toolInput'] ?? envelope['input'];
+    if (!isObject(ti)) return null;
+
+    const fileVal = ti['file_path'] ?? ti['path'] ?? ti['filePath'];
+    const file = typeof fileVal === 'string' ? fileVal : '';
+
+    let isWrite = false;
+    for (const key of ['content', 'new_string', 'new_str', 'text', 'newText']) {
+        if (typeof ti[key] === 'string' && (ti[key] as string).length > 0) isWrite = true;
+    }
+
+    return { file, isWrite };
+}
+
+/**
+ * True when the event OPENS one of the design surfaces.
+ *
+ * Deliberately narrow, and the narrowness is the fix for a real defect: an
+ * earlier version matched the surface name anywhere in the path OR in any
+ * search text the tool carried, including `command`. That silenced the nudge
+ * for a whole session on a `git log -- src/skills/fe-design`, on a grep for
+ * `design-review` while writing a review artefact, and on a read of
+ * `src/rules/design-review-after-ui-write.md` — whose path contains the skill
+ * name without being the skill. Since the same latch is the consultation
+ * signal the pre-registered rate counts, one false positive corrupted both the
+ * gate and the metric.
+ *
+ * So consultation means: a non-write touching `skills/<surface>/`. A search is
+ * not a consultation — reading the skill is.
+ */
+export function isConsultation(event: ToolEvent): boolean {
+    if (event.isWrite || !event.file) return false;
+    const normalized = event.file.replace(/\\/g, '/').toLowerCase();
+    return DESIGN_SURFACES.some((surface) => normalized.includes(`skills/${surface}/`));
+}
+
+/** True when the event writes a UI surface. */
+export function isUiWrite(event: ToolEvent): boolean {
+    if (!event.isWrite || !event.file) return false;
+    return isUiPath(event.file) || isUiTreePath(event.file);
+}
+
+export interface SessionState {
+    consulted: boolean;
+    nudges: number;
+}
+
+function stateFile(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'ui-route-nudge.json');
+}
+
+export function readState(root: string, session: string): SessionState {
+    try {
+        const all = JSON.parse(fs.readFileSync(stateFile(root), 'utf-8')) as Record<
+            string,
+            SessionState
+        >;
+        const entry = all[session];
+        if (entry && typeof entry.consulted === 'boolean' && typeof entry.nudges === 'number') {
+            return entry;
+        }
+    } catch {
+        /* fresh session */
+    }
+    return { consulted: false, nudges: 0 };
+}
+
+/** Sessions retained in the state file; oldest entries drop past this. */
+export const MAX_SESSIONS = 50;
+
+/** Drop the oldest entries so the file cannot grow without bound. */
+export function pruneSessions(
+    all: Record<string, SessionState>,
+    keep: number = MAX_SESSIONS,
+): Record<string, SessionState> {
+    const keys = Object.keys(all);
+    if (keys.length <= keep) return all;
+    const survivors = keys.slice(keys.length - keep);
+    const pruned: Record<string, SessionState> = {};
+    for (const key of survivors) pruned[key] = all[key]!;
+    return pruned;
+}
+
+export function writeState(root: string, session: string, state: SessionState): void {
+    try {
+        const file = stateFile(root);
+        let all: Record<string, SessionState> = {};
+        try {
+            all = JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, SessionState>;
+        } catch {
+            // Fresh file, or one nothing can parse. There is no other session
+            // state to preserve in either case — a corrupt file has already
+            // lost it — so starting from empty is recovery, not discard. The
+            // cost is bounded: a lost latch means at most MAX_NUDGES extra
+            // reminders in the sessions that were in flight.
+        }
+        if (typeof all !== 'object' || all === null || Array.isArray(all)) all = {};
+        all[session] = state;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(pruneSessions(all)));
+    } catch {
+        /* fail-open: a persistence failure must never break a tool call */
+    }
+}
+
+/**
+ * The decision, pure — so the test exercises the logic rather than the
+ * filesystem. Returns the next state and whether to warn.
+ */
+export function decide(
+    event: ToolEvent,
+    state: SessionState,
+): { state: SessionState; warn: boolean } {
+    if (isConsultation(event)) {
+        return { state: { ...state, consulted: true }, warn: false };
+    }
+    if (!isUiWrite(event)) return { state, warn: false };
+    if (state.consulted) return { state, warn: false };
+    if (state.nudges >= MAX_NUDGES) return { state, warn: false };
+    return { state: { ...state, nudges: state.nudges + 1 }, warn: true };
+}
+
+export function nudgeReason(file: string): string {
+    return `Non-trivial UI write to ${file} with no design consultation this session. Run \`existing-ui-audit\` first, then the fe-design loop (brief → build → review). Skip only if this is ui-trivial: <=1 file, <=5 lines, no new component, no new state, no new dependency.`;
+}
+
+export function main(): number {
+    let envelope: JsonValue;
+    try {
+        const raw = readHookStdin();
+        if (!raw.trim()) return EXIT_ALLOW;
+        envelope = JSON.parse(raw) as JsonValue;
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!isObject(envelope)) return EXIT_ALLOW;
+
+    const rootVal = envelope['workspace_root'];
+    const root = typeof rootVal === 'string' && rootVal ? rootVal : process.cwd();
+    if (!hookSectionEnabled(root, 'ui_route_nudge')) return EXIT_ALLOW;
+
+    const sessionVal = envelope['session_id'];
+    const session = typeof sessionVal === 'string' && sessionVal ? sessionVal : 'unknown';
+
+    const event = extractEvent(envelope);
+    if (!event) return EXIT_ALLOW;
+
+    const before = readState(root, session);
+    const { state, warn } = decide(event, before);
+    if (state.consulted !== before.consulted || state.nudges !== before.nudges) {
+        writeState(root, session, state);
+    }
+    if (!warn) return EXIT_ALLOW;
+
+    process.stdout.write(`${JSON.stringify({ reason: nudgeReason(event.file) })}\n`);
+    return EXIT_WARN;
+}
+
+function isCliEntry(): boolean {
+    const entry = process.argv[1];
+    if (!entry) return false;
+    return pathToFileURL(path.resolve(entry)).href === import.meta.url;
+}
+
+if (isCliEntry()) process.exit(main());
+
+export const _HOOK_FILE = fileURLToPath(import.meta.url);