@event4u/agent-config 8.7.0 → 8.9.0

package/src/scripts/hot_context_hook.ts

@@ -30,6 +30,7 @@
 
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -309,6 +310,39 @@ export function restore_hot_context(
     return { action: 'inject', reason: `restored (source=${source || 'startup'})`, context: block };
 }
 
+// ---------------------------------------------------------------------
+// opt-in memory session index (road-to-memory-retrieval-economy P5)
+// ---------------------------------------------------------------------
+
+/**
+ * Build the compact memory index when `memory.session_index: on`; `null`
+ * on the default-off path, empty corpus, or any failure (never blocks).
+ * Memory roots are cwd-relative (same contract as the MCP tool handlers),
+ * so the build runs chdir-wrapped to the workspace root.
+ */
+function _session_index_block_or_null(root: string): string | null {
+    try {
+        // Lazy require (ESM-safe via createRequire) keeps the default-off
+        // fast path free of the memory_lookup + settings-cascade import cost.
+        const req = createRequire(import.meta.url);
+        const mod = req('./session_memory_index.js') as {
+            session_index_enabled: (root: string) => boolean;
+            build_session_index_block: () => string | null;
+        };
+        if (!mod.session_index_enabled(root)) return null;
+        const prev = process.cwd();
+        try {
+            process.chdir(root);
+            return mod.build_session_index_block();
+        } finally {
+            process.chdir(prev);
+        }
+    } catch (exc) {
+        process.stderr.write(`hot-context-hook: session index skipped: ${String(exc)}\n`);
+        return null;
+    }
+}
+
 // ---------------------------------------------------------------------
 // CLI — dispatcher concern entry point
 // ---------------------------------------------------------------------
@@ -351,12 +385,23 @@ export function main(): number {
         } else if (event === 'session_start') {
             const source = String(payload.source ?? '');
             const decision = restore_hot_context(root, source);
+            const blocks: string[] = [];
             if (decision.action === 'inject' && decision.context) {
+                blocks.push(decision.context);
+            }
+            // Opt-in compact memory index (road-to-memory-retrieval-economy
+            // P5) — default OFF; rides the same injection surface. Memory
+            // roots are cwd-relative, so resolve from the workspace root.
+            const indexBlock = _session_index_block_or_null(root);
+            if (indexBlock !== null) {
+                blocks.push(indexBlock);
+            }
+            if (blocks.length > 0) {
                 process.stdout.write(
                     JSON.stringify({
                         decision: 'allow',
-                        reason: decision.reason,
-                        context: decision.context,
+                        reason: decision.action === 'inject' ? decision.reason : 'memory session index',
+                        context: blocks.join('\n\n'),
                     }) + '\n',
                 );
             }

package/src/scripts/install-hooks.sh

@@ -42,6 +42,31 @@ if ! ./scripts-run src/scripts/check_no_conflict_markers --quiet; then
     fail=1
 fi
 
+# Changed-files static pass (typecheck + lint) — the deterministic backstop to
+# the behavioural verify-before-complete rule (#818). Catches the compile/lint
+# errors that reach remote CI "Static Checks" (e.g. TS18048). Runs only when
+# the push touches .ts, so docs-only pushes stay fast. Skip a genuine WIP push
+# with AGENT_CONFIG_SKIP_PREPUSH_STATIC=1 (the agent cannot use --no-verify).
+echo "🔍 Static check on changed TypeScript (typecheck + lint)..."
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_STATIC:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_STATIC=1"
+else
+    base="$(git merge-base HEAD origin/main 2>/dev/null || echo HEAD~1)"
+    changed_ts="$(git diff --name-only --diff-filter=d "$base"...HEAD -- '*.ts' 2>/dev/null || true)"
+    if [ -n "$changed_ts" ]; then
+        if ! npx eslint $changed_ts; then
+            echo "❌  ESLint failed on changed TypeScript. Fix before pushing (or AGENT_CONFIG_SKIP_PREPUSH_STATIC=1 for a WIP push)."
+            fail=1
+        fi
+        if ! npm run --silent typecheck; then
+            echo "❌  Typecheck (tsc) failed — this is the class of error remote CI 'Static Checks' catches (#818). Fix before pushing."
+            fail=1
+        fi
+    else
+        echo "⏭️  no changed .ts vs origin/main — skipping."
+    fi
+fi
+
 if [ $fail -ne 0 ]; then
     echo ""
     echo "   Push blocked — fix the failures above and re-push."

package/src/scripts/install.ts

@@ -72,6 +72,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import type * as YamlModule from 'yaml';
 
 import { build_merge_entries } from './_lib/json_pointers.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -2847,15 +2848,40 @@ function _deploy_claude_desktop(
  * discovery (revert = one package release, no per-machine gating).
  * Tier-2/internal flat commands stay command files. A command whose name
  * collides with a real skill is skipped (the skill already owns `/name`).
+ *
+ * Reserved-name floor: a flat `/name` that equals a Claude Code BUILT-IN
+ * command or bundled skill (see `_lib/claude_builtin_names.ts`) would shadow
+ * the built-in — e.g. a `review` wrapper hides Claude Code's own `/review`.
+ * Such slugs get NEITHER a skill wrapper NOR a flat command file on this
+ * anchor (their nested `/cluster:sub` commands are untouched); the flat file
+ * is removed so a future upstream flat-discovery fix cannot resurrect the
+ * shadowing. The suite complements the host — it never overlays built-ins.
  */
 const _CLAUDE_FLAT_WRAPPER_EXTRA = new Set(['commit']); // essential; absent from the manifest
 export function _apply_claude_flat_command_wrappers(
     anchor: string,
     package_root: string,
     current_files: Set<string>,
-): { wrapped: string[]; collisions: string[] } {
+): { wrapped: string[]; collisions: string[]; reserved: string[] } {
     const wrapped: string[] = [];
     const collisions: string[] = [];
+    const reserved: string[] = [];
+    // Reserved-name sweep over ALL flat command files (any tier): a name
+    // shadowing a Claude Code built-in never ships on the claude-code anchor.
+    const commands_dir = path.join(anchor, 'commands');
+    let flat_entries: string[] = [];
+    try {
+        flat_entries = fs.readdirSync(commands_dir).filter((f) => f.endsWith('.md'));
+    } catch {
+        // No commands dir → nothing to sweep.
+    }
+    for (const fname of flat_entries.sort()) {
+        const slug = fname.slice(0, -'.md'.length);
+        if (!is_claude_builtin_name(slug)) continue;
+        fs.rmSync(path.join(commands_dir, fname), { force: true });
+        current_files.delete(`commands/${fname}`);
+        reserved.push(slug);
+    }
     // Tier-0/1 visible command slugs from the locked discovery manifest.
     const eligible = new Set<string>(_CLAUDE_FLAT_WRAPPER_EXTRA);
     try {
@@ -2892,7 +2918,7 @@ export function _apply_claude_flat_command_wrappers(
         current_files.add(`skills/${slug}/SKILL.md`);
         wrapped.push(slug);
     }
-    return { wrapped, collisions };
+    return { wrapped, collisions, reserved };
 }
 
 function _deploy_global_content(
@@ -2949,6 +2975,13 @@ function _deploy_global_content(
                         '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',
+                );
+            }
         }
 
         const missing_targets = _verify_deploy_targets(anchor, plan);

package/src/scripts/lint_agent_skill_names.ts

@@ -14,6 +14,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { command_slug } from './_lib/agent_src.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 
 const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
@@ -97,6 +98,18 @@ function frontmatterNameFromFile(p: string): string | null {
     return _frontmatter_name(fs.readFileSync(p, 'utf-8'));
 }
 
+const USER_INVOCABLE_FALSE_RE = /^user-invocable:\s*false\s*$/m;
+
+/** True when the SKILL.md opts out of slash registration (`user-invocable: false`). */
+export function _opts_out_of_slash(text: string): boolean {
+    if (!text.startsWith('---')) {
+        return false;
+    }
+    const end = text.indexOf('\n---', 3);
+    const block = end !== -1 ? text.slice(3, end) : text;
+    return USER_INVOCABLE_FALSE_RE.test(block);
+}
+
 export function _spec_violation(name: string): string | null {
     if (name.length > MAX_NAME_LEN) {
         return `longer than ${MAX_NAME_LEN} chars`;
@@ -178,6 +191,22 @@ export function check_skills(): string[] {
                     'requires the folder name to match the `name:` field',
             );
         }
+        // Reserved-name floor: a skill named after a Claude Code built-in
+        // command / bundled skill shadows the built-in when projected as
+        // `/name` (e.g. a `mcp` skill hides Claude Code's own /mcp dialog).
+        // Opting out of slash registration (`user-invocable: false`) keeps
+        // the skill model-loadable while the host retains the /name.
+        // Reserved set: src/scripts/_lib/claude_builtin_names.ts.
+        if (
+            is_claude_builtin_name(dirname) &&
+            !_opts_out_of_slash(fs.readFileSync(md, 'utf-8'))
+        ) {
+            violations.push(
+                `${rel}: \`${dirname}\` is a Claude Code built-in command name — ` +
+                    'add `user-invocable: false` (model-only invocation) or rename ' +
+                    'the skill; the suite must never shadow a host built-in',
+            );
+        }
     }
     return violations;
 }

package/src/scripts/lint_behavioural_eval_freshness.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env tsx
+/**
+ * Lint behavioural-eval freshness — a behavioural `evals.json` that pins the
+ * skill body it was authored against must still match the current SKILL.md
+ * body, or it is flagged stale (road-to-skill-eval-coverage Phase 3).
+ *
+ * Sibling to `lint_eval_freshness.ts`, DIFFERENT axis: that gate keeps a
+ * corpus-backed skill's TRIGGER eval fresh against an upstream SHA; this gate
+ * keeps a skill's BEHAVIOURAL eval fresh against its own SKILL.md body. The
+ * two never conflate.
+ *
+ * A skill's `evals/evals.json` is in scope when it carries a `skill_body_sha`
+ * (SHA-256 of the SKILL.md body — post-frontmatter, trimmed — at authoring
+ * time). Absent = unpinned, OUT of scope (nothing to keep fresh), mirroring
+ * `lint_eval_freshness`'s `upstream: null` handling. So the currently-shipped
+ * evals (which carry no pin) never fail — the gate only bites once an author
+ * opts in by pinning.
+ *
+ * In scope, the gate fails when the pinned `skill_body_sha` differs from the
+ * current SKILL.md body sha: the body moved, so the eval may no longer
+ * exercise it — re-verify and re-pin (`--write-floor`-style human step) rather
+ * than let a stale eval pass silently.
+ *
+ * Deterministic, no token spend: reads on-disk files only. The live re-eval is
+ * a separate, spend-bearing step; this gate verifies the pin is current.
+ *
+ * Exit codes: 0 clean (or none in scope) / 1 at least one stale / 2 usage.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+let SKILLS_DIR = path.join(REPO, 'src', 'skills');
+
+export function _setSkillsDirForTest(p: string): void {
+    SKILLS_DIR = p;
+}
+
+type Json = string | number | boolean | null | Json[] | { [k: string]: Json };
+
+function _splitBody(text: string): string {
+    if (!text.startsWith('---\n')) return text.replace(/\s+$/, '');
+    const end = text.indexOf('\n---', 4);
+    if (end === -1) return text.replace(/\s+$/, '');
+    return text.slice(end + 4).replace(/^\n+/, '').replace(/\s+$/, '');
+}
+
+/** SHA-256 of a skill's SKILL.md body (post-frontmatter, trailing-ws-trimmed). */
+export function skillBodySha(skillMdText: string): string {
+    return crypto.createHash('sha256').update(_splitBody(skillMdText), 'utf-8').digest('hex');
+}
+
+export interface FreshnessResult {
+    ok: boolean;
+    stale: Array<{ skill: string; pinned: string; current: string }>;
+    inScope: number;
+}
+
+export function checkFreshness(): FreshnessResult {
+    const stale: FreshnessResult['stale'] = [];
+    let inScope = 0;
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+    } catch {
+        return { ok: true, stale, inScope };
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const evalsPath = path.join(SKILLS_DIR, e.name, 'evals', 'evals.json');
+        const skillMd = path.join(SKILLS_DIR, e.name, 'SKILL.md');
+        if (!fs.existsSync(evalsPath) || !fs.existsSync(skillMd)) continue;
+        let spec: Json;
+        try {
+            spec = JSON.parse(fs.readFileSync(evalsPath, 'utf-8')) as Json;
+        } catch {
+            continue;
+        }
+        const pinned =
+            spec && typeof spec === 'object' && !Array.isArray(spec)
+                ? (spec['skill_body_sha'] as string | undefined)
+                : undefined;
+        if (typeof pinned !== 'string' || pinned === '') continue; // unpinned → out of scope
+        inScope += 1;
+        const current = skillBodySha(fs.readFileSync(skillMd, 'utf-8'));
+        if (current !== pinned) {
+            stale.push({ skill: e.name, pinned, current });
+        }
+    }
+    return { ok: stale.length === 0, stale, inScope };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let quiet = false;
+    for (const a of argv) {
+        if (a === '--quiet') quiet = true;
+        else {
+            process.stderr.write('usage: lint_behavioural_eval_freshness [--quiet]\n');
+            return 2;
+        }
+    }
+    const { ok, stale, inScope } = checkFreshness();
+    if (!ok) {
+        for (const s of stale) {
+            process.stderr.write(
+                `stale behavioural eval: ${s.skill}/evals/evals.json pinned ${s.pinned.slice(0, 12)}… ` +
+                    `but SKILL.md body is ${s.current.slice(0, 12)}… — re-verify and re-pin skill_body_sha\n`,
+            );
+        }
+        return 1;
+    }
+    if (!quiet) {
+        process.stdout.write(
+            `✅  behavioural-eval freshness: ${inScope} pinned eval(s) current (unpinned evals out of scope).\n`,
+        );
+    }
+    return 0;
+}
+
+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 {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/lint_knowledge_scale.ts

@@ -14,9 +14,10 @@
  *   - sessions scale   — `agents/knowledge/sessions/` > 50 pages
  *                        → design fold-through-consolidate-gate for tracked pages
  *   - type scale       — any single memory/knowledge type > 200 files
- *                        → build the pre-decided file-first in-memory BM25 CLI
+ *                        → rank via `_lib/lexical_index.ts` (hand-rolled BM25 +
+ *                          trigram, no engine fork / no FTS5; ADR-061 honoured)
  *   - corpus scale     — > 500 files across all types
- *                        → same BM25 activation path
+ *                        → same lexical-index activation path
  *   - hot-context size — `agents/runtime/state/hot-context.md` > 600 tokens
  *                        (estimated at 4 chars/token) → trim schema / fix the
  *                        deterministic writer
@@ -151,7 +152,7 @@ export function runChecks(root: string): Warning[] {
                 metric: `${n}/${TYPE_FILES_MAX}`,
                 message:
                     `type '${type}' holds ${n} files (> ${TYPE_FILES_MAX}). ` +
-                    'Activation path (pre-decided): build the file-first in-memory BM25 CLI (re-index at session start, no vectors, no service).',
+                    'Activation path (resolved, road-to-retrieval-substrate-hardening B2): rank via the hand-rolled BM25 + trigram index in `_lib/lexical_index.ts` (pure stdlib, NO engine fork / NO SQLite-FTS5, ADR-061 honoured). Measured lift: mean tie-set 3.333 → 1.0 (internal/bench/reports/lexical-ranking.json). Wire it lazily at first lookup + a stat-index, no vectors, no service.',
             });
         }
     }

package/src/scripts/lint_roadmap_complexity.ts

@@ -190,6 +190,9 @@ function lint_roadmap(
     _check_execution_mode(fm, problems);
     if (warnings) {
         _check_autonomous_authoring(text, fm, warnings);
+        _check_human_gate_steps(text, warnings);
+        _check_human_gate_phase_headings(text, warnings);
+        _check_human_gate_exit_criteria(text, warnings);
     }
     return problems;
 }
@@ -236,6 +239,127 @@ function _check_autonomous_authoring(text: string, fm: string, warnings: string[
     }
 }
 
+// Human-gate step patterns (templates/roadmaps.md rule 22) — checkbox
+// steps that park work on a human instead of the agent. Steps are
+// agent-executable by default; genuinely user-clearable gates belong in
+// a structured `## Blockers` entry, agent-checkable verifications become
+// commands / targeted tests. Warnings never fail the lint; they fire for
+// every execution mode (an interactive roadmap with sprinkled human-check
+// steps is the same authoring bug, just slower to hurt).
+const HUMAN_GATE_STEP_PATS: Array<[RegExp, string]> = [
+    [
+        /\b(user|maintainer|human|operator|stakeholder|product owner) (verifies|reviews|approves|confirms|signs?[- ]off(?: on)?|inspects|validates)\b/i,
+        "'<human> verifies / reviews / approves …' step",
+    ],
+    [
+        /\bmanually (verify|review|check|test|confirm|inspect|validate)\b/i,
+        "'manually verify / check …' step",
+    ],
+    [
+        /\bwait for (the )?(user|maintainer|stakeholders?|approval|confirmation|review|feedback)\b/i,
+        "'wait for approval / user' step",
+    ],
+    [/\bask the (user|maintainer)\b/i, "'ask the user' step"],
+    [
+        /\b(get|obtain|request|await|collect) ((the|an?|final) )?((user|maintainer|stakeholder|product owner|team) )?(approval|confirmation|sign[- ]?off)\b/i,
+        "'obtain approval / sign-off' step",
+    ],
+    [/\bsign[- ]?off (from|by)\b/i, "'sign-off from <human>' step"],
+    [/\bhuman review (required|needed|gate)\b/i, "'human review required' step"],
+    [
+        /\b(confirm|check|verify|review|clarify) with the (user|maintainer)\b/i,
+        "'confirm with the user' step",
+    ],
+];
+
+// Human-gate phase headings (template rule 22) — a phase whose TITLE is
+// the human checkpoint ("## Phase 5 — Review / Sign-off", "## User
+// Acceptance"). Whole-heading match after an optional "Phase N" prefix,
+// so working headings ("## Review existing skills") never fire.
+const HUMAN_GATE_HEADING_PAT =
+    /^#{2,3}\s+(?:phase\s+\d+\s*(?:[—–:.-])?\s*)?(?:review(?:\s*(?:[/&+]|and)\s*sign[- ]?off)?|sign[- ]?off|approval|user\s+acceptance(?:\s+testing)?|manual\s+(?:verification|review|testing|qa)|human\s+(?:validation|review))\s*$/i;
+
+// Human-approval exit / acceptance criteria (template rule 22) — criteria
+// must be agent-decidable (exit code, file exists, test passes), never
+// "user approves" / "looks good". Applied inside Exit-criteria /
+// Acceptance blocks only.
+const HUMAN_GATE_CRITERIA_PAT =
+    /\b(user|maintainer|human|operator|stakeholder|product owner)\b[^\n]{0,60}\b(approv\w*|confirm\w*|sign[- ]?off|reviews)\b|\b(approval|confirmation|sign[- ]?off)\s+(from|by|received)\b|\blooks good\b/i;
+
+const EXIT_CRITERIA_OPENER_PAT = /^\s*(?:[-*]\s+)?\*{0,2}(exit criteria|acceptance(?: criteria)?)\*{0,2}\s*:?/i;
+
+const RULE22_HINT =
+    'templates/roadmaps.md rule 22: steps and criteria are agent-decidable; ' +
+    'replace with an agent-verifiable check (command / targeted test) or, ' +
+    'if only a human can decide/authorize, a structured ## Blockers entry';
+
+function _check_human_gate_steps(text: string, warnings: string[]): void {
+    for (const rawLine of text.split('\n')) {
+        if (!/^\s*-\s*\[ \]/.test(rawLine)) {
+            continue;
+        }
+        for (const [re, label] of HUMAN_GATE_STEP_PATS) {
+            if (re.test(rawLine)) {
+                warnings.push(
+                    `human-gate step (${label}): ` +
+                        `"${rawLine.trim().slice(0, 80)}" — ${RULE22_HINT}`,
+                );
+                break;
+            }
+        }
+    }
+}
+
+function _check_human_gate_phase_headings(text: string, warnings: string[]): void {
+    for (const rawLine of text.split('\n')) {
+        if (!rawLine.startsWith('#')) {
+            continue;
+        }
+        if (HUMAN_GATE_HEADING_PAT.test(rawLine)) {
+            warnings.push(
+                `human-gate phase heading: "${rawLine.trim().slice(0, 80)}" — ` +
+                    'a phase whose work only a human can finish blocks autonomous ' +
+                    `execution; ${RULE22_HINT}`,
+            );
+        }
+    }
+}
+
+function _check_human_gate_exit_criteria(text: string, warnings: string[]): void {
+    let inHeadingBlock = false;
+    let inInlineBlock = false;
+    for (const rawLine of text.split('\n')) {
+        const heading = /^#{1,6}\s+(.*)$/.exec(rawLine);
+        if (heading) {
+            inHeadingBlock = /\b(acceptance|exit criteria)\b/i.test(heading[1]!);
+            inInlineBlock = false;
+            continue;
+        }
+        if (rawLine.trim() === '') {
+            inInlineBlock = false;
+            continue;
+        }
+        const opener = EXIT_CRITERIA_OPENER_PAT.test(rawLine);
+        if (opener) {
+            inInlineBlock = true;
+        }
+        if (!inHeadingBlock && !inInlineBlock) {
+            continue;
+        }
+        // Open-checkbox lines are covered by _check_human_gate_steps;
+        // done/deferred/cancelled lines record history, not future gates.
+        if (/^\s*-\s*\[[ xX~-]\]/.test(rawLine)) {
+            continue;
+        }
+        if (HUMAN_GATE_CRITERIA_PAT.test(rawLine)) {
+            warnings.push(
+                `human-approval exit criterion: "${rawLine.trim().slice(0, 80)}" — ` +
+                    `criteria must be agent-decidable; ${RULE22_HINT}`,
+            );
+        }
+    }
+}
+
 function _check_execution_mode(fm: string, problems: string[]): void {
     if (!fm || !/^execution:/m.test(fm)) {
         return; // absent field = interactive default — valid