@event4u/agent-config 10.2.0 → 10.4.0

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -129,6 +129,7 @@ import { isSafeTranscriptPath } from './end_review_nudge_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
+import { openRecordStats } from './subagent_ledger_hook.js';
 
 /** Dispatcher-internal block code. Pinned to 1 by `concern_block_exit_parity`. */
 const EXIT_BLOCK = 1;
@@ -842,6 +843,39 @@ export function main(): number {
 
     const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined) || process.cwd();
 
+    // Layer 1b — an open subagent dispatch is an EXPLICIT allow
+    // (road-to-subagent-lifecycle-integrity Phase 3 Step 2).
+    //
+    // A turn waiting on an async subagent has, by construction, outstanding
+    // work the model cannot finish in this turn. Refusing it is the upstream
+    // Stop-hook x async-subagent loop shape (anthropics/claude-code#55754):
+    // the gate refuses, the model still cannot proceed because the dispatch
+    // has not returned, and the refusal repeats.
+    //
+    // This is an allow path and can never become a deny path — it only ever
+    // lets a turn END that would otherwise have been refused. It reads the
+    // Phase-1 ledger; a ledger that is absent, empty or unreadable yields zero
+    // open records and changes nothing, so the gate degrades to exactly its
+    // previous behaviour rather than failing open in the dangerous direction.
+    //
+    // R2 round 2, finding 2: it used to be an early `return EXIT_ALLOW`, which
+    // suppressed ALL FOUR detectors. A pending dispatch explains a promissory
+    // closing (A) and an unsettled completion claim (D); it explains nothing
+    // about a language mismatch (B) or an unverified edit (C), and silencing
+    // those was scope Step 2 never asked for. Applied per detector below.
+    //
+    // R2 round 2, finding 1: the count is TTL-filtered inside
+    // `openRecordStats`. A leaked record from a dispatch that never returned
+    // would otherwise read as "a dispatch is open" forever and, because this
+    // branch is an ALLOW, disable those two detectors indefinitely with no
+    // signal — the ledger's own leak inherited with the opposite polarity.
+    let dispatchOpen = false;
+    try {
+        dispatchOpen = openRecordStats(workspaceRoot).open_count > 0;
+    } catch {
+        // An unreadable ledger is not a reason to change the verdict.
+    }
+
     const transcriptPath = str(
         (payload['transcript_path'] ?? payload['transcriptPath']) as JsonValue | undefined,
     );
@@ -881,7 +915,10 @@ export function main(): number {
     // second, configurable notion of warranted layered on top of it.
     const findings: Finding[] = [];
     for (const f of [
-        detectPromissory(lastAssistant),
+        // A and D are the completion-adjacent pair a pending dispatch excuses
+        // (Phase 3 Step 2, narrowed by R2 round 2 finding 2). B and C are not
+        // excused by anything about a dispatch and run unchanged.
+        dispatchOpen ? null : detectPromissory(lastAssistant),
         detectLanguage(lastAssistant, readLanguagePin(workspaceRoot)),
         detectUnverifiedEdit(toolCalls),
         // Round 7 § Phase 1 — detector D, in the same unconditional list as the
@@ -891,7 +928,7 @@ export function main(): number {
         // gating is where the comment above says gating belongs — inside the
         // detector: no CI observed, or a settled read, or no completion claim
         // ⇒ no finding.
-        detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot)),
+        dispatchOpen ? null : detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot)),
     ]) {
         if (f) findings.push(f);
     }

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -123,6 +123,45 @@ export function isUiWrite(event: ToolEvent): boolean {
     return isUiPath(event.file) || isUiTreePath(event.file);
 }
 
+/**
+ * The two handover shapes `design-fidelity` routes on a FILE rather than on a
+ * word: its `file_pattern: *design.html` and its
+ * `path_prefix: .claude/design-system/`. Reading one is the agent reaching
+ * rung 1 of the data-basis ladder before it writes.
+ *
+ * A SHARED PREDICATE, NOT A DECISION INPUT HERE. `decide` does not branch on
+ * it: the nudge's behaviour is unchanged by an artifact read, and the phase
+ * that introduced this states `nothing behavioural`. The one consumer is
+ * `report_consultation_rate`, which measures over transcripts. Keeping the
+ * predicate beside `isUiWrite` / `isConsultation` is what stops the analyzer
+ * and the nudge from classifying the same event differently.
+ *
+ * THIS IS A COPY OF THE RULE'S TRIGGERS, NOT A READ OF THEM — same honesty
+ * boundary the header states for `ui_surface.ts`: nothing here parses
+ * `src/rules/*.md`. `ui_route_nudge_artifact_read.test.ts` pins the two against
+ * the rule's own frontmatter so the copy cannot drift silently.
+ *
+ * **Not disjoint from `isConsultation` by construction** —
+ * `src/skills/design-review/references/design.html` satisfies both. Callers
+ * must evaluate the two independently rather than branching on the first hit;
+ * an early return on this predicate silently removes such an event from the
+ * consultation numerator.
+ *
+ * **Known over-count, not fixed here.** A `Grep` / `Glob` whose `path` argument
+ * happens to be the artifact satisfies this predicate although nothing was
+ * read — the same search-is-not-a-read class `isConsultation` was narrowed to
+ * exclude. It is not excluded here because `ToolEvent` carries no tool name,
+ * and adding one would change the shared shape `isConsultation` and `isUiWrite`
+ * are measured through, moving a published rate this branch does not own. The
+ * consequence is stated where it matters: the rate is a CEILING on
+ * read-before-write, and `report_consultation_rate`'s output says so.
+ */
+export function isArtifactRead(event: ToolEvent): boolean {
+    if (event.isWrite || !event.file) return false;
+    const normalized = event.file.replace(/\\/g, '/').toLowerCase();
+    return normalized.endsWith('design.html') || normalized.includes('.claude/design-system/');
+}
+
 export interface SessionState {
     consulted: boolean;
     nudges: number;
@@ -203,8 +242,22 @@ export function decide(
     return { state: { ...state, nudges: state.nudges + 1 }, warn: true };
 }
 
+/**
+ * Did anything worth persisting change?
+ *
+ * Enumerated per field rather than deep-compared. **A new field must be added
+ * here or it does not persist** — a review on this branch caught exactly that
+ * shape: two session fields were computed on every event and written on none,
+ * because the guard tested the two older fields by name. Those fields are gone
+ * (the measurement lives in the analyzer, one implementation instead of two),
+ * but the guard stays enumerated and this note stays with it.
+ */
+export function stateChanged(before: SessionState, after: SessionState): boolean {
+    return before.consulted !== after.consulted || before.nudges !== after.nudges;
+}
+
 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.`;
+    return `Non-trivial UI write to ${file} with no design consultation this session. Run \`existing-ui-audit\` first, then the fe-design loop (brief → inventory, if an artifact was provided → 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 {
@@ -230,7 +283,7 @@ export function main(): number {
 
     const before = readState(root, session);
     const { state, warn } = decide(event, before);
-    if (state.consulted !== before.consulted || state.nudges !== before.nudges) {
+    if (stateChanged(before, state)) {
         writeState(root, session, state);
     }
     if (!warn) return EXIT_ALLOW;

package/src/scripts/lint_design_antipattern_parity.ts

@@ -0,0 +1,201 @@
+/**
+ * Gate: catalog ↔ slop-rule parity (road-to-design-detector-evidence Phase 1).
+ *
+ * `src/scripts/design_slop_rules.ts` states in its header that every rule cites
+ * its catalog id "so prose ↔ rule stay traceable". Nothing enforced that. The
+ * unit test validates the *shape* `/^[A-Z]+\d+$/` and never opens
+ * `docs/guidelines/design-antipatterns.md`, so a rule citing `Z99` passed, and a
+ * catalog entry could silently lose or gain a detector with no signal anywhere.
+ * The tree happened to be consistent; the defect was that consistency was
+ * unguarded, not that it was absent.
+ *
+ * This gate makes the claim true, in both directions:
+ *
+ *   A. every non-`Q*` catalog entry appears exactly once in § Detector status
+ *   B. every § Detector status row names a catalog entry that exists
+ *   C. the set of `backed` rows equals the registry's `catalogId` set
+ *   D. every status is one of the five allowed values
+ *   E. every non-`backed` row carries a reason
+ *
+ * `Q*` entries are out of scope by construction: they are objective floors owned
+ * by `lint_design_quality`, not aesthetic tells, and the status table says so.
+ *
+ * Pure core (`parityFindings`) takes both documents as text, so the failure
+ * paths are unit-testable without the filesystem. Exit 0 = clean, 1 = at least
+ * one finding.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
+const QUIET = process.argv.includes('--quiet');
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const CATALOG = path.join(REPO, 'docs', 'guidelines', 'design-antipatterns.md');
+const REGISTRY = path.join(REPO, 'src', 'scripts', 'design_slop_rules.ts');
+
+/** The five statuses § Detector status may use. */
+export const STATUSES = ['backed', 'floor', 'judgment-only', 'deferred', 'candidate'] as const;
+export type Status = (typeof STATUSES)[number];
+
+export interface ParityFinding {
+    kind: string;
+    msg: string;
+}
+
+const ENTRY_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|/gm;
+const STATUS_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|\s*([a-z-]*)\s*\|([^|]*)\|/gm;
+const STATUS_SECTION = /^## Detector status$([\s\S]*?)(?=^## )/m;
+const CATALOG_ID = /^\s+catalogId:\s*"([A-Z]+\d+)"/gm;
+
+/** Catalog entry ids outside the § Detector status section. */
+export function catalogEntries(catalogMd: string): string[] {
+    const section = STATUS_SECTION.exec(catalogMd)?.[0] ?? '';
+    const outside = section === '' ? catalogMd : catalogMd.replace(section, '');
+    return [...outside.matchAll(ENTRY_ROW)].map((m) => m[1] as string);
+}
+
+/** `id -> {status, note}` parsed from the § Detector status table. */
+export function statusRows(catalogMd: string): Map<string, { status: string; note: string }> {
+    const section = STATUS_SECTION.exec(catalogMd)?.[1] ?? '';
+    const out = new Map<string, { status: string; note: string }>();
+    for (const m of section.matchAll(STATUS_ROW)) {
+        out.set(m[1] as string, { status: (m[2] ?? '').trim(), note: (m[3] ?? '').trim() });
+    }
+    return out;
+}
+
+/** `catalogId` values declared by the rule registry. */
+export function registryCatalogIds(registryTs: string): string[] {
+    return [...registryTs.matchAll(CATALOG_ID)].map((m) => m[1] as string);
+}
+
+/** Pure invariant check over both documents. */
+export function parityFindings(catalogMd: string, registryTs: string): ParityFinding[] {
+    const out: ParityFinding[] = [];
+
+    if (STATUS_SECTION.exec(catalogMd) === null) {
+        return [
+            {
+                kind: 'no-status-section',
+                msg: 'design-antipatterns.md has no `## Detector status` section — the parity claim has nothing to check against',
+            },
+        ];
+    }
+
+    const entries = catalogEntries(catalogMd);
+    const seen = new Set<string>();
+    for (const id of entries) {
+        if (seen.has(id)) out.push({ kind: 'duplicate-entry', msg: `${id}: appears more than once in the catalog tables` });
+        seen.add(id);
+    }
+
+    const rows = statusRows(catalogMd);
+
+    // A — every catalog entry is classified.
+    for (const id of seen) {
+        if (!rows.has(id)) {
+            out.push({ kind: 'unclassified', msg: `${id}: catalog entry missing from § Detector status` });
+        }
+    }
+    // B — every classified row names a real entry.
+    for (const id of rows.keys()) {
+        if (!seen.has(id)) {
+            out.push({ kind: 'orphan-status', msg: `${id}: § Detector status row names an entry that no catalog table defines` });
+        }
+    }
+    // D + E — status vocabulary and reasons.
+    for (const [id, row] of rows) {
+        if (!(STATUSES as readonly string[]).includes(row.status)) {
+            out.push({
+                kind: 'bad-status',
+                msg: `${id}: status '${row.status || '(empty)'}' is not one of ${STATUSES.join(', ')}`,
+            });
+            continue;
+        }
+        if (row.status !== 'backed' && row.note === '') {
+            out.push({ kind: 'missing-reason', msg: `${id}: status '${row.status}' carries no reason` });
+        }
+    }
+
+    // C — backed set equals the registry set, both directions.
+    const backed = new Set([...rows].filter(([, r]) => r.status === 'backed').map(([id]) => id));
+    const registry = new Set(registryCatalogIds(registryTs));
+    for (const id of backed) {
+        if (!registry.has(id)) {
+            out.push({ kind: 'backed-without-rule', msg: `${id}: marked backed but no registry rule declares that catalogId` });
+        }
+    }
+    for (const id of registry) {
+        if (!backed.has(id)) {
+            const known = rows.get(id);
+            out.push({
+                kind: 'rule-without-backed',
+                msg: known
+                    ? `${id}: a registry rule declares this catalogId but § Detector status marks it '${known.status}'`
+                    : `${id}: a registry rule declares this catalogId and no catalog entry carries it`,
+            });
+        }
+    }
+
+    return out;
+}
+
+function _print(s: string): void {
+    if (!QUIET) process.stdout.write(`${s}\n`);
+}
+
+export function main(): number {
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_design_antipattern_parity',
+            candidates: [path.relative(REPO, CATALOG), path.relative(REPO, REGISTRY)],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const catalogMd = fs.readFileSync(CATALOG, 'utf-8');
+    const registryTs = fs.readFileSync(REGISTRY, 'utf-8');
+    const findings = parityFindings(catalogMd, registryTs);
+
+    const entries = catalogEntries(catalogMd).length;
+    const backed = [...statusRows(catalogMd).values()].filter((r) => r.status === 'backed').length;
+
+    if (findings.length === 0) {
+        _print(`✅  catalog ↔ rule parity OK — ${entries} entries classified, ${backed} detector-backed`);
+        return 0;
+    }
+    _print(`❌  catalog ↔ rule parity — ${findings.length} finding(s):`);
+    for (const f of findings) _print(`  - ${f.msg}`);
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}