@event4u/agent-config 14.11.0 → 14.13.0

package/src/scripts/hooks/shims/php

@@ -0,0 +1,101 @@
+#!/usr/bin/env sh
+# Container-only tooling shim — road-to-skill-ecosystem-runtime-enforcement
+# Phase 1 Steps 2-4. AI council 2/2 (2026-08-25) scoped Phase 1 to THIS shim
+# alone; the hook-bypass-flag and package-manager candidates are recorded as
+# out of scope at `blocker: shim-scope-decision`.
+#
+# WHAT IT DOES. Refuses a host invocation of a tool the container-only rule
+# reserves for the project container, and prints the sanctioned in-container
+# form with the caller's own arguments re-quoted, so the alternative is
+# directly runnable rather than a template to adapt.
+#
+# WHY SHELL AND NOT AN INTERPRETED RUNTIME. Startup dominates: this runs on
+# every invocation of the shimmed names, most of which are legitimate, so a
+# node or python start would be paid constantly to say nothing. Same reason the
+# fast-pass below is a case statement rather than a parse.
+#
+# WHY A PATH PREPEND AND NOT A PER-TOOL-CALL HOOK. A prepend costs nothing per
+# call and works for any process the session starts, including ones no hook
+# surface observes. It is also session-scoped and reversible by construction --
+# the installer never writes a profile.
+#
+# EXIT CODE. Non-zero (2) on refusal. Never 0 on a refusal: a shim that exits 0
+# has told the caller nothing the caller must act on, and the recorded trap on
+# this host is the opposite mistake -- an ADVISORY exit 2 read as a hard block.
+# This one is not advisory; the refusal is the point.
+
+set -eu
+
+# --- The global kill switch (Step 7) -------------------------------------
+#
+# One variable disables every hook for one invocation. It is checked FIRST so
+# the escape hatch cannot be shadowed by anything below, and it re-execs the
+# real binary rather than exiting, so `AGENT_CONFIG_DISABLE_HOOKS=1 php -v`
+# does what it says instead of merely not refusing.
+#
+# Finding the real binary: strip this shim's own directory out of PATH and look
+# again. Without that the re-exec finds the shim and loops.
+if [ "${AGENT_CONFIG_DISABLE_HOOKS:-}" = "1" ]; then
+    _shim_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
+    _clean_path=$(printf '%s' "${PATH:-}" | tr ':' '\n' | while IFS= read -r _p; do
+        [ -n "$_p" ] || continue
+        _rp=$(CDPATH= cd -- "$_p" 2>/dev/null && pwd -P) || continue
+        [ "$_rp" = "$_shim_dir" ] && continue
+        printf '%s:' "$_p"
+    done)
+    _real=$(PATH="${_clean_path%:}" command -v "$(basename -- "$0")" 2>/dev/null || true)
+    if [ -n "$_real" ]; then
+        exec "$_real" "$@"
+    fi
+    # Disabled, and there is no real binary to fall through to. Say so rather
+    # than exiting 0: the caller asked for the tool, not for silence.
+    printf '%s: hooks disabled, but no %s found outside the shim directory\n' \
+        "shims/php" "$(basename -- "$0")" >&2
+    exit 127
+fi
+
+# The basename this was invoked as. Dispatch on it so one script serves several
+# names (Step 3) -- today the set is deliberately one entry wide.
+INVOKED="$(basename -- "$0")"
+
+case "$INVOKED" in
+    php) ;;
+    *)
+        # Invoked under a name this shim does not claim. Say so rather than
+        # guessing: a silent pass-through would make the shim look installed and
+        # inert, which is worse than an error.
+        printf '%s: shim invoked under an unclaimed basename %s\n' "shims/php" "$INVOKED" >&2
+        exit 2
+        ;;
+esac
+
+# --- Re-quote the received arguments -------------------------------------
+#
+# Single-quote each argument and escape embedded single quotes as '\'' so the
+# printed line survives copy-paste through a shell unchanged. Without this a
+# suggestion containing a space or a quote is a suggestion that silently does
+# something else when run.
+quoted=''
+for arg in "$@"; do
+    esc=$(printf '%s' "$arg" | sed "s/'/'\\\\''/g")
+    quoted="$quoted '$esc'"
+done
+
+SERVICE="${AGENT_CONFIG_PHP_SERVICE:-php}"
+
+cat >&2 <<EOF
+❌  \`$INVOKED\` was run on the HOST. This project's tooling is container-only.
+
+    Run it in the container instead:
+
+      docker compose exec -T $SERVICE $INVOKED$quoted
+
+    Why: the container-only tooling rule reserves php / artisan / composer /
+    phpstan / rector / ecs / phpunit for the project container, because a host
+    run picks up the host's PHP version and extensions and produces results
+    that do not match CI.
+
+    Override for one command:  AGENT_CONFIG_DISABLE_HOOKS=1 $INVOKED ...
+    Service name:              AGENT_CONFIG_PHP_SERVICE=<name> (default: php)
+EOF
+exit 2

package/src/scripts/hooks/suggestion_capture_hook.ts

@@ -0,0 +1,378 @@
+#!/usr/bin/env tsx
+/**
+ * Suggestion-block capture — a two-slot latch, counts only.
+ *
+ * ## What it measures and why it exists
+ *
+ * `command_suggester/render.ts` emits a numbered-options block with exactly one
+ * `Recommendation: N — …` line and the as-is option always last. Nothing records
+ * whether those blocks are ever *answered*, so no roadmap can cite a selection
+ * rate — and the model-carried alternative is measured and dead:
+ * `orchestration_record` captured 1 of 369 dispatches. This instrument exists so
+ * that figure is not repeated by construction.
+ *
+ * ## Two slots, not one — and the probe is why
+ *
+ * `road-to-suggestion-block-capture` planned a single `user_prompt_submit` hook
+ * reading the transcript tail. A live probe
+ * (`agents/evidence/analysis/suggestion-capture-probe.md`) found something
+ * cheaper: **`stop` carries `last_assistant_message` in the payload**, so the
+ * "was a block emitted" half needs no file read at all, and the turn-1 blind
+ * spot (`transcript_path` present but the file not yet written) does not arise.
+ *
+ *   stop                → detect the signature in `last_assistant_message`,
+ *                         write a latch keyed by `prompt_id`
+ *   user_prompt_submit  → CONSUME the latch, classify `prompt`, append one line
+ *
+ * ## The misclassification guard, which is the whole correctness argument
+ *
+ * A bare `1` three turns later must never read as a pick. So the latch is
+ * **consumed exactly once**: `user_prompt_submit` deletes it after reading, and
+ * a prompt arriving with no latch is `other`, never `option_n`. A latch older
+ * than `LATCH_TTL_MS` is `stale_block`. An unparseable latch is `stale_block`
+ * too — never a guess.
+ *
+ * ## Privacy is a property of the schema, not of a scrubber
+ *
+ * `src/config/suggestion-capture.json` registers five fields and **none can hold
+ * free text**: a timestamp, a boolean, an options COUNT, and two closed enums.
+ * `option_n` records THAT a numbered option was chosen and out of how many —
+ * deliberately not WHICH, because the block's option order is content and the
+ * capture-rate question does not need it. A type with no field able to carry a
+ * prompt cannot leak one; a scrubber can fail.
+ *
+ * Default-OFF (`hooks.suggestion_capture.enabled: true`). `fail_closed: false`,
+ * always exit 0: an instrument must never break a turn it is only observing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { unwrap } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { humanTypedThisTurn } from '../_lib/machine_wake.js';
+
+const EXIT_ALLOW = 0;
+const SETTINGS_FILE = '.agent-settings.yml';
+const SINK_REL = path.join('agents', 'runtime', 'state', 'audit', 'suggestion-capture.jsonl');
+const LATCH_REL = path.join('agents', 'runtime', 'state', 'suggestion-latch.json');
+/** A block older than this cannot be what the current prompt is answering. */
+export const LATCH_TTL_MS = 15 * 60 * 1000;
+
+export type Classification = 'option_n' | 'as_is' | 'other' | 'stale_block';
+export type EvidenceClass = 'render-signature' | 'latch-consumed' | 'latch-stale' | 'no-latch';
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+const isObject = (v: unknown): v is JsonObject =>
+    typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const str = (v: JsonValue | undefined): string => (typeof v === 'string' ? v : '');
+
+/* ── the render signature ──────────────────────────────────────────────────── */
+
+/**
+ * Exactly one `Recommendation:`/`Empfehlung:` line, plus at least two numbered
+ * options. Both halves are required: a numbered list alone is ordinary prose,
+ * and a `Recommendation:` line alone is a sentence.
+ *
+ * The label is matched in both languages because `user-interaction`'s Iron Law 1
+ * makes a wrong-language label a rule violation, not a variant — so a German
+ * session's block carries `Empfehlung:` and a single-language matcher would
+ * under-count exactly the sessions the mirror rule produces.
+ */
+export function detectBlock(text: string): { emitted: boolean; optionsCount: number } {
+    if (text === '') return { emitted: false, optionsCount: 0 };
+    const lines = text.split('\n');
+    const recommendation = lines.filter((l) => /^\s*(?:\*\*)?(?:Recommendation|Empfehlung)\s*:/i.test(l)).length;
+    const numbered = new Set<string>();
+    for (const l of lines) {
+        const m = /^\s*(\d{1,2})[.)]\s+\S/.exec(l);
+        if (m?.[1] !== undefined) numbered.add(m[1]);
+    }
+    const emitted = recommendation === 1 && numbered.size >= 2;
+    return { emitted, optionsCount: emitted ? numbered.size : 0 };
+}
+
+/* ── classification ────────────────────────────────────────────────────────── */
+
+/**
+ * The as-is escape hatch, matched by intent rather than by an exact string:
+ * `command-suggestion-policy` requires it present and last but fixes no wording,
+ * so a literal matcher would silently classify every as-is pick as `other`.
+ */
+const AS_IS_RE = /\b(as[- ]is|as is|unver(?:ä|ae)ndert|so lassen|wie es ist|keep it|leave it|no change)\b/i;
+
+export function classify(prompt: string, optionsCount: number): Classification {
+    const t = prompt.trim();
+    if (t === '') return 'other';
+    if (AS_IS_RE.test(t)) return 'as_is';
+    // A bare number, or a number with trailing punctuation — the shape a pick
+    // actually takes. `1. do the thing` is NOT a pick: it is an instruction that
+    // happens to start with a digit, and counting it would inflate the rate.
+    const bare = /^(\d{1,2})\s*[.)]?\s*$/.exec(t);
+    if (bare?.[1] !== undefined) {
+        const n = Number(bare[1]);
+        // Out-of-range is `other`: a "7" against a 3-option block is answering
+        // something else, and recording it as a pick would corrupt the metric
+        // the whole instrument exists to produce.
+        if (n >= 1 && (optionsCount === 0 || n <= optionsCount)) return 'option_n';
+    }
+    return 'other';
+}
+
+/* ── settings, latch, sink ─────────────────────────────────────────────────── */
+
+/** `hooks.suggestion_capture.enabled: true` — the same mini-parse siblings use. */
+export function enabled(root: string): boolean {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(path.join(root, SETTINGS_FILE), 'utf8');
+    } catch {
+        return false;
+    }
+    let inHooks = false;
+    let inSection = false;
+    for (const line of raw.split('\n')) {
+        if (/^hooks:\s*$/.test(line)) {
+            inHooks = true;
+            inSection = false;
+            continue;
+        }
+        if (/^\S/.test(line)) {
+            inHooks = false;
+            inSection = false;
+            continue;
+        }
+        if (!inHooks) continue;
+        if (/^\s{2}suggestion_capture:\s*$/.test(line)) {
+            inSection = true;
+            continue;
+        }
+        if (/^\s{2}\S/.test(line)) {
+            inSection = false;
+            continue;
+        }
+        if (inSection && /^\s{4}enabled:\s*true\s*$/.test(line)) return true;
+    }
+    return false;
+}
+
+export interface Latch {
+    readonly prompt_id: string;
+    readonly options_count: number;
+    readonly at: number;
+}
+
+export function writeLatch(root: string, latch: Latch): void {
+    const p = path.join(root, LATCH_REL);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(latch)}\n`, 'utf8');
+}
+
+/** Read AND delete. Consume-once is the misclassification guard, not a detail. */
+export function consumeLatch(root: string): Latch | null {
+    const p = path.join(root, LATCH_REL);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(p, 'utf8');
+    } catch {
+        return null;
+    }
+    try {
+        fs.rmSync(p, { force: true });
+    } catch {
+        /* a latch we cannot delete is still consumed for this turn */
+    }
+    try {
+        const v = JSON.parse(raw) as unknown;
+        if (!isObject(v)) return null;
+        const at = v['at'];
+        const oc = v['options_count'];
+        const pid = v['prompt_id'];
+        if (typeof at !== 'number' || typeof oc !== 'number' || typeof pid !== 'string') return null;
+        return { prompt_id: pid, options_count: oc, at };
+    } catch {
+        return null; // unparseable → stale_block, never a guess
+    }
+}
+
+export interface Record_ {
+    readonly ts: string;
+    readonly block_emitted: boolean;
+    readonly options_count: number;
+    readonly evidence_class: EvidenceClass;
+    readonly turn_classification: Classification;
+}
+
+/** The exact key set `src/config/suggestion-capture.json` registers. */
+export const RECORD_KEYS: readonly string[] = [
+    'ts',
+    'block_emitted',
+    'options_count',
+    'evidence_class',
+    'turn_classification',
+];
+
+export function appendRecord(root: string, rec: Record_, now: Date): void {
+    const p = path.join(root, SINK_REL);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const line = {
+        ts: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+        block_emitted: rec.block_emitted,
+        options_count: rec.options_count,
+        evidence_class: rec.evidence_class,
+        turn_classification: rec.turn_classification,
+    };
+    fs.appendFileSync(p, `${JSON.stringify(line)}\n`, 'utf8');
+}
+
+/* ── the two slots ─────────────────────────────────────────────────────────── */
+
+/** Decide what a prompt turn should record. Pure, so the tests drive it directly. */
+export function classifyTurn(
+    prompt: string,
+    latch: Latch | null,
+    nowMs: number,
+): { record: boolean; evidence_class: EvidenceClass; turn_classification: Classification; options_count: number } {
+    if (latch === null) {
+        // No block preceded this turn. Recording every ordinary turn would make
+        // the sink a prompt log with the volume of one, so nothing is written.
+        return { record: false, evidence_class: 'no-latch', turn_classification: 'other', options_count: 0 };
+    }
+    if (nowMs - latch.at > LATCH_TTL_MS) {
+        return {
+            record: true,
+            evidence_class: 'latch-stale',
+            turn_classification: 'stale_block',
+            options_count: latch.options_count,
+        };
+    }
+    return {
+        record: true,
+        evidence_class: 'latch-consumed',
+        turn_classification: classify(prompt, latch.options_count),
+        options_count: latch.options_count,
+    };
+}
+
+/**
+ * Canonical event name, from either invocation shape.
+ *
+ * The dispatcher supplies `envelope.event` (`stop`, `user_prompt_submit`); a
+ * direct/legacy invocation carries only the host's own `hook_event_name`
+ * (`Stop`, `UserPromptSubmit`). Reading just the second one is how the first
+ * version of this concern became a silent no-op under the dispatcher: it ran,
+ * matched nothing, and exited 0 — indistinguishable from a disabled hook.
+ */
+export function eventOf(envelope: JsonObject, payload: JsonObject): string {
+    const canonical = str(envelope['event'] as JsonValue | undefined);
+    const native = str(
+        (envelope['native_event'] ?? payload['hook_event_name']) as JsonValue | undefined,
+    );
+    const raw = (canonical !== '' ? canonical : native).toLowerCase();
+    if (raw === 'stop') return 'stop';
+    if (raw === 'userpromptsubmit' || raw === 'user_prompt_submit') return 'user_prompt_submit';
+    return raw;
+}
+
+/**
+ * The dispatcher calls every in-process concern as `main(argv)` — see
+ * `_run_concern_inproc` in `hooks/dispatch_hook.ts`, and the `ConcernMain`
+ * signature in `hooks/concern_registry.ts`.
+ *
+ * This used to be `main(now: Date = new Date())`, and the mismatch made the
+ * concern a SILENT NO-OP on every live dispatch: argv arrived where a Date was
+ * expected, `now.getTime()` threw `TypeError: now.getTime is not a function`,
+ * and the outer catch — "an instrument never breaks the turn it observes" —
+ * swallowed it and returned EXIT_ALLOW. The dispatcher recorded exit 0 and no
+ * output, which is indistinguishable from a disabled hook. Three earlier
+ * isolation attempts read that silence as a `--project-dir` problem; it was
+ * this.
+ *
+ * The clock stays injectable because the TTL and the timestamp need to be
+ * driven from a test, but it is now the SECOND parameter, where the dispatcher
+ * cannot land on it.
+ */
+export function main(_argv: readonly string[] = [], now: Date = new Date()): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_ALLOW;
+    }
+
+    // `workspace_root` is the dispatcher's; `cwd` is the host payload's. Both
+    // are read because the concern must work under either invocation.
+    const root =
+        str(envelope['workspace_root'] as JsonValue | undefined) ||
+        str(payload['cwd'] as JsonValue | undefined) ||
+        str(envelope['project_root'] as JsonValue | undefined) ||
+        '.';
+    if (!enabled(root)) return EXIT_ALLOW;
+
+    const event = eventOf(envelope, payload);
+    try {
+        if (event === 'stop') {
+            const { emitted, optionsCount } = detectBlock(
+                str(payload['last_assistant_message'] as JsonValue | undefined),
+            );
+            if (emitted) {
+                writeLatch(root, {
+                    prompt_id: str(payload['prompt_id'] as JsonValue | undefined),
+                    options_count: optionsCount,
+                    at: now.getTime(),
+                });
+            }
+            return EXIT_ALLOW;
+        }
+        if (event === 'user_prompt_submit') {
+            // A machine wake is not a user turn. Without this, a background task
+            // notification arriving between the block and the user's "1"
+            // consumes the latch, and the real pick then classifies as `other`
+            // — the instrument records a miss that never happened. Same defect,
+            // same predicate, as the git-authorization ledger; see
+            // `_lib/machine_wake.ts` for the captured discriminator.
+            if (!humanTypedThisTurn(str(payload['prompt'] as JsonValue | undefined))) {
+                return EXIT_ALLOW;
+            }
+            const latch = consumeLatch(root);
+            const v = classifyTurn(str(payload['prompt'] as JsonValue | undefined), latch, now.getTime());
+            if (v.record) {
+                appendRecord(
+                    root,
+                    {
+                        ts: '',
+                        block_emitted: true,
+                        options_count: v.options_count,
+                        evidence_class: v.evidence_class,
+                        turn_classification: v.turn_classification,
+                    },
+                    now,
+                );
+            }
+            return EXIT_ALLOW;
+        }
+    } catch {
+        return EXIT_ALLOW; // an instrument never breaks the turn it observes
+    }
+    return EXIT_ALLOW;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (isCliEntry()) process.exit(main());
+
+export { SINK_REL, LATCH_REL };

package/src/scripts/hot_context_hook.ts

@@ -10,6 +10,22 @@
  * Contract (per the verdict):
  *   - `agents/runtime/state/hot-context.md`, gitignored, OVERWRITTEN on every
  *     `stop` (cache, not journal). 400-word hard cap.
+ *
+ * loss_class: ephemeral-lossy
+ *
+ * Named, not changed (`road-to-runtime-context-floors` step 3.1). The two losses
+ * here are both deliberate and both unrecoverable, which is exactly what the
+ * class asserts: the 400-word cap discards the older half of the window, and
+ * `_redact_lines` DROPS any line the low-impact redactor refuses — including on
+ * a redactor error, which is fail-closed per line. Neither is retrievable from
+ * the output, and neither should be: this file is a privacy-floored cache whose
+ * source of truth is the transcript it was built from, and storing a recovery
+ * for a line dropped for privacy would defeat the reason it was dropped.
+ *
+ * `recoverable-lossy` would be the WRONG class here even though the transcript
+ * still exists, and the distinction is the point of the vocabulary: the class
+ * describes what THIS transform guarantees to its consumer, and this one
+ * guarantees nothing about the dropped content on purpose.
  *   - Written by DETERMINISTIC extraction from the chat-history JSONL
  *     (`agents/runtime/.agent-chat-history`) — never LLM summarization.
  *   - Every extracted line passes the low-impact privacy floor

package/src/scripts/install-hooks.sh

@@ -32,8 +32,12 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # outputs (e.g. a new guideline bumping the count in README + docs/architecture).
 # `task consistency` is the EXACT CI mirror (sync-check + sync + generate-tools
 # + compile-router + compile-corpus + `git diff --quiet`),
-# so any derived-output drift blocks the push here. Runtime ~15-40s (it
-# regenerates the tool trees) — cheaper than a red CI run and a fixup re-push.
+# so any derived-output drift blocks the push here. Runtime ~10s: three
+# consecutive timed runs on 2026-08-30 measured 9.79s / 10.19s / 10.26s
+# (road-to-agent-turnaround 3.2). The header said "~15-40s" until then, which
+# over-stated this half of the hook by 1.5-4x while the hook AS A WHOLE was far
+# more expensive than either number — see the preflight block below. Still
+# cheaper than a red CI run and a fixup re-push.
 
 # A delete-only push has no content to gate, so every check below is answering
 # a question nobody asked. Measured 2026-08-18 during the 14.0.0 release:
@@ -83,9 +87,20 @@ fi
 # preflight gates read that tree, so on a FRESH worktree (this repo's standard
 # workflow) running preflight first would fail with "produced by regeneration
 # but absent before" — red for a reason the contributor did not cause, which is
-# exactly the anti-pattern this gate set exists to avoid. Measured 15s against
-# the 25s `pre_push_budget_seconds` ceiling in src/config/ci-local-parity.yml.
-# `check_enforcement_coverage` (30.7s) stays out of preflight by design.
+# exactly the anti-pattern this gate set exists to avoid.
+#
+# BUDGET: measured 36.05s on 2026-08-30 (road-to-agent-turnaround 3.2, a clean
+# exit-0 run), against the 25s `pre_push_budget_seconds` ceiling in
+# src/config/ci-local-parity.yml. That is 44% OVER, and the header claimed 15s
+# until this measurement. The ceiling's own comment calls it "a real budget, not
+# a wish" — and nothing measures the hook, so the gate set grew past it with no
+# signal. Recorded rather than fixed here: narrowing preflight to the pushed
+# paths is one edit away from turning a push-blocking mirror into a partial one,
+# which is how drift reaches CI instead of the developer.
+#
+# The hook's local cost is therefore ~46s (10s consistency + 36s preflight),
+# which is what the 67s median `git push` in the ten-session corpus is mostly
+# made of. `check_enforcement_coverage` (30.7s) stays out of preflight by design.
 echo "🔍 Preflight — the CI-only repo-content gates..."
 if [ "${AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT:-}" = "1" ]; then
     echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1"

package/src/scripts/install.ts

@@ -98,6 +98,7 @@ import {
     type RuleScope,
 } from '../install/rule_scope.js';
 import { isExclusivelyPackageOnly, stampHostLayerFingerprint } from '../install/partitionEligibility.js'; // ADR-236
+import * as claude_rule_rewrite from '../install/claudeRuleRewrite.js';
 import { RULE_SOURCE_REL } from '../install/wizard-plan.js';
 import { flattenSurface, computeSurfaceDelta, type SettingsSurface } from '../shared/settingsSurface.js';
 import { settingsSchema } from '../server/schemas/settings.js';
@@ -109,6 +110,7 @@ import {
     render_native_model_md,
 } from './_lib/model_tier.js';
 import { main as cmdMigrateMain } from './_cli/cmd_migrate.js';
+import { SCOPE_DETECT_AI_DIRS, SCOPE_DETECT_MANIFESTS } from '../install/detect.js';
 
 // ---------------------------------------------------------------------------
 // Python-runtime parity helpers
@@ -2328,28 +2330,12 @@ function _run_scope_prompt(opts: Options, reason: string, custom_path: string |
     return 'project';
 }
 
-const SCOPE_DETECT_MANIFESTS: readonly string[] = [
-    'package.json',
-    'composer.json',
-    'pyproject.toml',
-    'Cargo.toml',
-    'go.mod',
-    'Gemfile',
-];
-const SCOPE_DETECT_AI_DIRS: readonly string[] = [
-    '.claude',
-    '.cursor',
-    '.windsurf',
-    '.augment',
-    '.clinerules',
-    '.copilot',
-    '.gemini',
-    '.codex',
-    '.aider',
-    '.continue',
-    '.roo',
-    '.kilocode',
-];
+// SCOPE_DETECT_MANIFESTS and SCOPE_DETECT_AI_DIRS were duplicated here, byte
+// for byte, alongside their definitions in `src/install/detect.ts`. Two copies
+// of a detection constant is the shape that makes divergence invisible: the
+// test pinned ONE of them exactly, so a change to the other would have passed
+// CI. De-duplicated 2026-08-26 (road-to-internal-estate-fit 2.3) — one exported
+// definition, imported here.
 const SCOPE_DETECT_AI_FILES: readonly string[] = [
     'CLAUDE.md',
     'AGENTS.md',
@@ -3246,20 +3232,16 @@ function _deploy_global_content(
         // Runs before the postcheck + inventory record so `current_files`
         // reflects the transformed tree and reaping stays consistent.
         if (tool_id === 'claude-code') {
+            // Rules land verbatim from the copy above; see the module. It also
+            // renders the flat-command wrapper report, unchanged.
             const res = _apply_claude_flat_command_wrappers(anchor, package_root, current_files);
-            if (res.wrapped.length > 0 && !state.QUIET) {
-                info(
-                    `  claude-code: ${res.wrapped.length} visible flat command(s) projected as ` +
-                        'skill wrappers (Claude Code flat-command discovery workaround)',
-                );
-            }
-            if (res.reserved.length > 0 && !state.QUIET) {
-                info(
-                    `  claude-code: ${res.reserved.length} flat command(s) withheld — name is a ` +
-                        `Claude Code built-in (${res.reserved.join(', ')}); nested /cluster:sub ` +
-                        'commands remain available',
-                );
-            }
+            claude_rule_rewrite.rewriteAndReport(
+                path.join(anchor, 'rules'),
+                state.QUIET,
+                info,
+                warn,
+                res,
+            );
         }
 
         const missing_targets = _verify_deploy_targets(anchor, plan);

package/src/scripts/inventory_frontmatter.ts

@@ -28,6 +28,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { generatedBy } from './_lib/generated_by.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/inventory_frontmatter.ts → parents[2] is the repo root.
@@ -266,7 +267,7 @@ function _mostCommon(counter: Map<string, number>): [string, number][] {
 export function main(): number {
     _OUT.length = 0;
     emit('# Frontmatter inventory (generated)\n');
-    emit('Generated by `scripts/inventory_frontmatter.py`. Raw material for');
+    emit(generatedBy('inventory_frontmatter', 'Raw material for'));
     emit('Phase 1 of the frontmatter-schema roadmap. Do not edit by hand.\n');
 
     inventory_type('skills', gather_files(path.join(SRC, 'skills'), (b) => b === 'SKILL.md'));

package/src/scripts/lint_adr_sweep_routing.ts

@@ -43,6 +43,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -317,6 +318,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         names = [];
     }
 
+    // Per-artifact accounting. `scanned` counts candidate ROWS, so a sweep
+    // artifact whose table the parser walked past contributes zero rows and is
+    // indistinguishable from one with no candidates — exactly the "looked at
+    // almost nothing" reading the ledger exists to separate from "found
+    // nothing".
+    const ledger = new GateLedger('lint_adr_sweep_routing');
+    ledger.plan(names);
     const violations: Violation[] = [];
     let scanned = 0;
     for (const name of names) {
@@ -325,7 +333,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         const [v, n] = lintSweep(rel, fs.readFileSync(abs, 'utf-8'));
         violations.push(...v);
         scanned += n;
+        if (v.length > 0) ledger.fail(name, `${String(v.length)} unrouted candidate row(s)`);
+        else if (n === 0) ledger.skip(name, 'no_applicable_files');
+        else ledger.complete(name);
     }
+    ledger.report(json ? () => undefined : undefined);
 
     process.stdout.write(`scanned: ${scanned}\n`);
     try {