@event4u/agent-config 10.1.0 → 10.3.0

package/src/scripts/hooks/session_eol_hook.ts

@@ -17,6 +17,16 @@
  * SILENCE, never a block (fail-open); hooks cannot inject `/clear`, so the
  * recycle action itself stays advisory-carried by design (roadmap 5.1).
  *
+ * Counter-check (second warn path, also once per session): when the advisory
+ * fired on an earlier Stop and no envelope written since then exists, inject
+ * one further line saying so — the advisory recommends an action whose next
+ * step destroys the session, so recommending it without ever checking the
+ * result is how a silent write failure becomes total context loss. Stamped by
+ * `missing_envelope_warned_at`, gated on the same threshold, so the emergency
+ * off-switch silences BOTH paths. Two independent emitters, at most one line
+ * each per session — the budget the Stop slot carries from this hook is two,
+ * not one.
+ *
  * Phase 4.2 (read surface): every Stop also overwrites
  * `agents/runtime/state/context-fill.json` with the machine-readable fill
  * level + threshold state — display substrate for an external statusline;
@@ -35,6 +45,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
 
+import { RECYCLE_ENVELOPE_REL } from '../_lib/recycle_envelope_paths.js';
 import {
     emptyCounters,
     eolSessionKey,
@@ -67,6 +78,13 @@ export interface SessionEolState {
     counters: EolCounters;
     /** ISO stamp when the recycle advisory fired for this session (F2), or null. */
     advisory_fired_at: string | null;
+    /**
+     * ISO stamp when the follow-up "advised, but no envelope exists" line
+     * fired, or null. Separate from `advisory_fired_at` so the counter-check
+     * is once-per-session in its own right: one reminder is a safety net, one
+     * per Stop for the rest of the session is a nag the reader learns to skip.
+     */
+    missing_envelope_warned_at?: string | null;
     updated_at: string;
 }
 
@@ -105,6 +123,10 @@ export function readState(file: string): SessionEolState {
                 counters: parsed.counters,
                 advisory_fired_at:
                     typeof parsed.advisory_fired_at === 'string' ? parsed.advisory_fired_at : null,
+                missing_envelope_warned_at:
+                    typeof parsed.missing_envelope_warned_at === 'string'
+                        ? parsed.missing_envelope_warned_at
+                        : null,
                 updated_at: typeof parsed.updated_at === 'string' ? parsed.updated_at : '',
             };
         }
@@ -115,10 +137,70 @@ export function readState(file: string): SessionEolState {
         schema_version: 1,
         counters: emptyCounters(),
         advisory_fired_at: null,
+        missing_envelope_warned_at: null,
         updated_at: '',
     };
 }
 
+/**
+ * Is there a recycle envelope under this workspace, written since `since`?
+ *
+ * Two properties, both load-bearing:
+ *
+ * **Only ENOENT counts as missing.** `fs.existsSync` swallows every error into
+ * `false`, so an unreadable directory (EACCES on a mounted or root-owned tree)
+ * would read as "no envelope" and produce the manufactured "your envelope is
+ * gone" warning this check exists to avoid. `statSync` + an errno test is the
+ * only shape that can tell the two apart.
+ *
+ * **Freshness, not mere existence.** The consumer moves the envelope aside at
+ * session_start, so a file still sitting here belongs to a session that never
+ * cleared. Counting it would silence the warning in the case it exists to
+ * catch, and worse: `/clear` would then resume the successor from another
+ * session's state — a wrong resume instead of an empty one. An envelope whose
+ * `written_at` predates the advisory is not this session's.
+ */
+export function envelopeExists(workspaceRoot: string, since: string | null = null): boolean {
+    const target = path.join(workspaceRoot, RECYCLE_ENVELOPE_REL);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(target, 'utf-8');
+    } catch (exc) {
+        // ENOENT is the real "no envelope"; anything else is a failed CHECK,
+        // and a failed check must never assert absence.
+        return (exc as NodeJS.ErrnoException)?.code !== 'ENOENT';
+    }
+    if (since === null) return true;
+    try {
+        const written = (JSON.parse(raw) as { written_at?: unknown }).written_at;
+        // Unparseable or undated: present, and not provably stale. Treat it as
+        // this session's — the alternative warns about a file that is there.
+        if (typeof written !== 'string') return true;
+        return Date.parse(written) >= Date.parse(since);
+    } catch {
+        return true;
+    }
+}
+
+/**
+ * The follow-up line: the advisory already fired, and no envelope arrived.
+ *
+ * This is the half of the reported minimum fix that lives outside the command
+ * — the hook that recommends the call making the same counter-check before the
+ * operator acts on it. Whatever stopped the write (a wrong root, a refusal
+ * scrolled past, a forgotten step), the state visible here is identical, and
+ * the next action the advisory recommended is the one that destroys the
+ * session.
+ */
+export function buildMissingEnvelopeLine(workspaceRoot: string): string {
+    return (
+        `recycle advised earlier, but no envelope exists at ` +
+        `${path.join(workspaceRoot, RECYCLE_ENVELOPE_REL)} — /clear now starts the successor ` +
+        `from nothing. Re-run \`agent-config session:recycle\` and check that it prints the ` +
+        `absolute path it wrote before clearing.`
+    );
+}
+
 /**
  * Resolve the recycle threshold (Phase 3.1): the per-process override wins
  * (tests; `0` = advisory lane off), else the committed constant from
@@ -136,13 +218,22 @@ export function readThresholdTokens(): number | null {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
 }
 
-/** The exactly-one advisory line injected past threshold (Phase 3.2). */
+/**
+ * The exactly-one advisory line injected past threshold (Phase 3.2).
+ *
+ * The `/clear` half is conditional on purpose. An earlier wording read
+ * `run X … then /clear`, which is an instruction to destroy the session with
+ * no check in between — and a reader who followed it while the command was
+ * silently writing nothing lost everything. The proof to wait for is the
+ * absolute path the command prints; naming it costs one clause.
+ */
 export function buildAdvisoryLine(tokens: number, threshold: number): string {
     return (
         `context past recycle threshold (${tokens.toLocaleString('en-US')} of ` +
         `${threshold.toLocaleString('en-US')} tokens): run \`agent-config session:recycle\` to ` +
-        `write the recycle envelope, then /clear — the successor session resumes from the ` +
-        `envelope at session_start (road-to-token-economy-recycling)`
+        `write the recycle envelope. It prints the absolute path it wrote — /clear only after ` +
+        `you have seen that line. The successor session then resumes from the envelope at ` +
+        `session_start (road-to-token-economy-recycling)`
     );
 }
 
@@ -213,10 +304,29 @@ export function main(): number {
         tokens >= threshold &&
         state.advisory_fired_at === null;
 
+    // The counter-check: the advisory fired on an EARLIER Stop (so `state`,
+    // the pre-update snapshot, already carries the stamp) and no envelope has
+    // appeared since. It can never collide with `shouldAdvise` — that branch
+    // requires `advisory_fired_at === null` — so at most one line is emitted
+    // per Stop, and this one at most once per session.
+    //
+    // `threshold !== null` gates it for the same reason the advisory is gated:
+    // `AGENT_RECYCLE_THRESHOLD_TOKENS=0` is documented as the emergency switch
+    // for the whole advisory lane, and a lane that keeps one more warn after
+    // being switched off is not off.
+    const shouldWarnMissing =
+        threshold !== null &&
+        state.advisory_fired_at !== null &&
+        (state.missing_envelope_warned_at ?? null) === null &&
+        !envelopeExists(workspaceRoot, state.advisory_fired_at);
+
     const nextState: SessionEolState = {
         schema_version: 1,
         counters,
         advisory_fired_at: shouldAdvise ? now : state.advisory_fired_at,
+        missing_envelope_warned_at: shouldWarnMissing
+            ? now
+            : (state.missing_envelope_warned_at ?? null),
         updated_at: now,
     };
     try {
@@ -237,6 +347,16 @@ export function main(): number {
         );
         return EXIT_WARN;
     }
+    if (shouldWarnMissing) {
+        process.stdout.write(
+            `${JSON.stringify({
+                decision: 'warn',
+                reason: 'session-eol: recycle advised, no envelope written',
+                additional_context: buildMissingEnvelopeLine(workspaceRoot),
+            })}\n`,
+        );
+        return EXIT_WARN;
+    }
     return 0;
 }
 

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -400,6 +400,34 @@ export function readCiSettled(workspaceRoot: string): { seen: boolean; settled:
 const _COMPLETION_RE =
     /(^|\n)\s*(?:\*\*)?(?:fertig\b|damit ist alles erledigt|aufgabe erledigt|alles erledigt\b|komplett(?:er)? (?:auftrag|abgearbeitet)|der komplette auftrag ist durch|done[.!]|all done\b|task complete)/i;
 
+/**
+ * The line the claim was found on says the opposite of a claim.
+ *
+ * A line-anchored keyword cannot tell "Fertig." from "Fertig ist der Fix noch
+ * nicht." — both open with the same token, and the second is exactly the honest
+ * status report this gate exists to ENCOURAGE. Measured 2026-08-12: three of ten
+ * realistic closings were refused, and all three were "not done yet" lines.
+ *
+ * This is a negation check on the SAME line, not another attempt to enumerate
+ * completion phrasings. The council that reviewed this guard (anthropic +
+ * openai, 2026-08-12) stated the bound plainly: a finite pattern cannot cover an
+ * infinite false-positive set, so extending the keyword list again would repeat
+ * the move that has already failed three times on the sibling git guard. What
+ * makes a block defensible here is not the pattern — it is that the pattern only
+ * fires as a TRIGGER to consult structured CI state (`ci.settled`), which is the
+ * council's Tier-2 shape. This check removes the cases where the prose itself
+ * already contradicts the trigger.
+ */
+const _NEGATED_CLAIM_RE =
+    /\b(noch nicht|nicht fertig|nicht durch|wäre verfrüht|ist verfrüht|not yet|not done|isn'?t done|nein)\b/i;
+
+/** The line `at` falls on — the scope a negation has to appear in to count. */
+function _lineAround(prose: string, at: number): string {
+    const start = prose.lastIndexOf('\n', at) + 1;
+    const end = prose.indexOf('\n', at);
+    return prose.slice(start, end === -1 ? prose.length : end);
+}
+
 export function detectCompletionClaim(
     reply: string,
     ci: { seen: boolean; settled: boolean },
@@ -410,6 +438,9 @@ export function detectCompletionClaim(
     const m = _COMPLETION_RE.exec(prose);
     if (!m) return null;
     const at = m.index;
+    // The trigger fired, but the line it fired on negates it — a status report,
+    // not a claim. Refusing these punishes exactly the honesty the gate wants.
+    if (_NEGATED_CLAIM_RE.test(_lineAround(prose, at))) return null;
     return {
         detector: 'completion',
         evidence: prose.slice(at, at + 120).trim(),

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());
+}