@event4u/agent-config 14.12.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

@@ -50,6 +50,7 @@ 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';
@@ -328,6 +329,15 @@ export function main(_argv: readonly string[] = [], now: Date = new Date()): num
             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) {

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 {