@event4u/agent-config 8.6.0 → 8.8.0

package/src/scripts/domain_soundness_status.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env tsx
+/**
+ * Domain-soundness validation status + ratchet
+ * (road-to-domain-soundness Phase 1 + Phase 3).
+ *
+ * The four non-coding profiles (finance, founder, ops, content_creator) SELL
+ * concrete domain value (DCF, runway, RICE, incident command, messaging), but
+ * the skills are forged on TS/PHP — "promising, not proven" off those stacks.
+ * A disclaimer floor bounds liability, NOT correctness. This tool makes the
+ * provenance honest and machine-checkable: it enumerates the default-surface
+ * domain skills those profiles ship (from source — each profile's
+ * `skills_hint`, never hardcoded) and reports each as:
+ *
+ *   - `validated`   — ships `evals/domain-truth.json` (a sourced answer key,
+ *                     authored by domain competence, distinct from behavioural
+ *                     evals.json). Presence is the machine signal; a passing
+ *                     run against it is the maintainer's Phase-3 gate.
+ *   - `unvalidated` — no domain-truth fixture: general-purpose scaffold, domain
+ *                     correctness not independently validated.
+ *
+ * A domain skill can pass a format/behavioural eval AND carry a disclaimer AND
+ * still embed a wrong domain assumption — this axis is the one that catches it.
+ *
+ * Modes:
+ *   (default)      human report.
+ *   --json         machine-readable.
+ *   --check        ratchet gate (CI): the count of `validated` skills may not
+ *                  drop below the pinned floor (internal/evals/domain-soundness-floor.json);
+ *                  a missing floor is an all-zero floor (bootstrap-inert). The
+ *                  floor only rises via --write-floor after a fixture lands and
+ *                  passes. This is the enforced-honesty gate: it makes a claimed
+ *                  validation impossible to assert without the fixture on disk.
+ *   --write-floor  pin the current validated count as the floor (maintainer
+ *                  action after authoring + running a domain-truth fixture).
+ *
+ * Exit codes: 0 ok / 1 ratchet regression / 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** The non-coding profiles whose default surface this tool scopes. */
+export const NON_CODING_PROFILES: readonly string[] = [
+    'finance',
+    'founder',
+    'ops',
+    'content_creator',
+];
+
+export interface StatusOptions {
+    skillsDir?: string;
+    profilesDir?: string;
+    floorPath?: string;
+}
+
+export interface SkillStatus {
+    skill: string;
+    status: 'validated' | 'unvalidated';
+}
+
+export interface SoundnessReport {
+    validationSet: SkillStatus[];
+    validated: number;
+    unvalidated: number;
+    total: number;
+}
+
+function _skillsDir(o: StatusOptions): string {
+    return o.skillsDir ?? path.join(REPO_ROOT, 'src', 'skills');
+}
+function _profilesDir(o: StatusOptions): string {
+    return o.profilesDir ?? path.join(REPO_ROOT, 'src', 'agent-src', 'profiles');
+}
+export function _floorPath(o: StatusOptions = {}): string {
+    return (
+        o.floorPath ??
+        path.join(REPO_ROOT, 'internal', 'evals', 'domain-soundness-floor.json')
+    );
+}
+
+/** Union of the non-coding profiles' `skills_hint`, restricted to real skills. */
+export function validationSet(o: StatusOptions = {}): string[] {
+    const profilesDir = _profilesDir(o);
+    const skillsDir = _skillsDir(o);
+    const out = new Set<string>();
+    for (const p of NON_CODING_PROFILES) {
+        const f = path.join(profilesDir, `${p}.yml`);
+        let doc: unknown;
+        try {
+            doc = parseYaml(fs.readFileSync(f, 'utf-8'));
+        } catch {
+            continue;
+        }
+        const profile = (doc as { profile?: unknown } | null)?.profile;
+        const defaults = (profile as { defaults?: unknown } | null)?.defaults;
+        const hint = (defaults as { skills_hint?: unknown } | null)?.skills_hint;
+        if (Array.isArray(hint)) {
+            for (const s of hint) {
+                if (typeof s === 'string' && fs.existsSync(path.join(skillsDir, s, 'SKILL.md'))) {
+                    out.add(s);
+                }
+            }
+        }
+    }
+    return [...out].sort();
+}
+
+function _isValidated(skillsDir: string, skill: string): boolean {
+    return fs.existsSync(path.join(skillsDir, skill, 'evals', 'domain-truth.json'));
+}
+
+export function computeStatus(o: StatusOptions = {}): SoundnessReport {
+    const skillsDir = _skillsDir(o);
+    const set = validationSet(o);
+    const validationSetStatus: SkillStatus[] = set.map((skill) => ({
+        skill,
+        status: _isValidated(skillsDir, skill) ? 'validated' : 'unvalidated',
+    }));
+    const validated = validationSetStatus.filter((s) => s.status === 'validated').length;
+    return {
+        validationSet: validationSetStatus,
+        validated,
+        unvalidated: validationSetStatus.length - validated,
+        total: validationSetStatus.length,
+    };
+}
+
+function _readFloor(floorPath: string): number {
+    try {
+        const raw = JSON.parse(fs.readFileSync(floorPath, 'utf-8')) as { validated?: number };
+        return raw.validated ?? 0;
+    } catch {
+        return 0;
+    }
+}
+
+export function writeFloor(o: StatusOptions = {}): SoundnessReport {
+    const report = computeStatus(o);
+    const p = _floorPath(o);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(
+        p,
+        JSON.stringify(
+            {
+                _comment:
+                    'Domain-soundness ratchet floor (road-to-domain-soundness Phase 3). ' +
+                    'domain_soundness_status --check fails if the validated count drops below this. ' +
+                    'Regenerate with --write-floor ONLY after a domain-truth fixture lands and passes.',
+                validated: report.validated,
+            },
+            null,
+            2,
+        ) + '\n',
+    );
+    return report;
+}
+
+export function checkRatchet(o: StatusOptions = {}): { ok: boolean; message: string } {
+    const report = computeStatus(o);
+    const floor = _readFloor(_floorPath(o));
+    if (report.validated < floor) {
+        return {
+            ok: false,
+            message: `validated domain skills ${report.validated} < floor ${floor}`,
+        };
+    }
+    return { ok: true, message: `validated ${report.validated}/${report.total} (floor ${floor})` };
+}
+
+function _renderHuman(r: SoundnessReport): string {
+    const lines = [
+        'Domain-soundness status — non-coding default-surface skills',
+        `  validated:   ${r.validated}/${r.total}`,
+        `  unvalidated: ${r.unvalidated}/${r.total}`,
+        '',
+    ];
+    for (const s of r.validationSet) {
+        const mark = s.status === 'validated' ? '✅' : '·';
+        lines.push(`  ${mark} ${s.skill.padEnd(28)} ${s.status}`);
+    }
+    return lines.join('\n');
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const known = new Set(['--json', '--check', '--write-floor']);
+    for (const a of argv) {
+        if (!known.has(a)) {
+            process.stderr.write('usage: domain_soundness_status [--json | --check | --write-floor]\n');
+            return 2;
+        }
+    }
+    if (argv.includes('--write-floor')) {
+        const r = writeFloor();
+        process.stdout.write(`✅  domain-soundness floor pinned: validated ${r.validated}/${r.total}\n`);
+        return 0;
+    }
+    if (argv.includes('--check')) {
+        const { ok, message } = checkRatchet();
+        if (!ok) {
+            process.stdout.write(`❌  domain-soundness ratchet regressed: ${message}\n`);
+            return 1;
+        }
+        process.stdout.write(`✅  domain-soundness ratchet: ${message}.\n`);
+        return 0;
+    }
+    const report = computeStatus();
+    if (argv.includes('--json')) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return 0;
+    }
+    process.stdout.write(_renderHuman(report) + '\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/generate_index.ts

@@ -410,6 +410,20 @@ export function _render_catalog(
         '',
         `## Skills (${skills.length})`,
         '',
+        '> **Behavioural-eval coverage is measured, not implied.** A skill is',
+        '> behaviourally evaluated only if it ships `evals/evals.json`; most do',
+        '> not yet. Coverage is reported per tier (`./scripts-run',
+        '> src/scripts/skill_eval_coverage`) and CI-ratcheted so it can only rise.',
+        '> Listing here never implies a skill is behaviourally tested — the',
+        '> current coverage and its gap are published on [the proof page](proof.md).',
+        '',
+        '> **Non-coding domain correctness is scoped, not proven.** The',
+        '> `finance` / `founder` / `ops` / `content` skills are forged on TS/PHP',
+        '> codebases; their embedded domain heuristics are labeled `unvalidated`',
+        '> until they pass a sourced `evals/domain-truth.json` fixture',
+        '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
+        '> floor bounds liability, not correctness — see [the proof page](proof.md).',
+        '',
         _render_table(skills, ['kind', 'name', 'extra', 'description'], '../', _to_shipped_path),
         '',
         `## Rules (${publicRules.length})`,

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.sh

@@ -23,8 +23,14 @@ set -euo pipefail
 COPY_DIRS="rules"  # Subdirectories where files must be real copies (space-separated)
 
 # Rules that are internal to the agent-config package and should NOT be shipped to consumers.
-# These are only relevant when developing the agent-config package itself.
-EXCLUDE_RULES="source-of-truth.md augment-portability.md docs-sync.md"
+# Static COMPAT floor only (see src/install/rule_scope.ts for the recorded
+# source-of-truth.md decision — same treatment on project AND global paths).
+# The full workspace/pack scoping list is resolved at runtime by
+# resolve_excluded_rules() via src/install/rule_scope_cli.ts, which re-uses
+# the projection predicate (rule_in_scope) so install semantics can never
+# drift from projection semantics. This variable is the fail-safe fallback
+# when no node/tsx runtime is available (over-ship, never under-ship).
+EXCLUDE_RULES="source-of-truth.md"
 
 # Files inside target/.augment/ that are NOT managed by sync (created by the bridge installer).
 # Never remove them in clean_stale even though they are absent in the source manifest.
@@ -284,6 +290,47 @@ create_symlink() {
 
 # --- Core functions ---
 
+# Resolve the full excluded-rule list for this install via the shared
+# scoping CLI (workspace/pack scope from <TARGET>/.agent-settings.yml,
+# router/frontmatter truth, kernel-safe). Overwrites EXCLUDE_RULES on
+# success; keeps the static compat fallback on any failure
+# (road-to-request-scoped-rule-load Phase 1b).
+resolve_excluded_rules() {
+    local rules_src="$SOURCE_PAYLOAD/rules"
+    local settings_file="$TARGET_DIR/.agent-settings.yml"
+    local cli="$SOURCE_DIR/src/install/rule_scope_cli.ts"
+    [[ -f "$cli" && -d "$rules_src" ]] || { log_verbose "rule-scope CLI unavailable — static exclude fallback"; return 0; }
+
+    local tsx_bin=""
+    if [[ -x "$SOURCE_DIR/node_modules/.bin/tsx" ]]; then
+        tsx_bin="$SOURCE_DIR/node_modules/.bin/tsx"
+    elif command -v npx >/dev/null 2>&1; then
+        tsx_bin="npx --yes tsx"
+    else
+        log_verbose "no tsx/npx runtime — static exclude fallback"
+        return 0
+    fi
+
+    local resolved
+    local -a cli_args=(--rules-dir "$rules_src")
+    [[ -f "$settings_file" ]] && cli_args+=(--settings "$settings_file")
+    # TMPDIR pinned for the child: tsx writes its transform cache under
+    # $TMPDIR — on macOS TMPDIR is exported, and callers (tests, wrappers)
+    # may point it INTO the install target, leaking tsx-cache files into a
+    # consumer tree / breaking dry-run's zero-file guarantee.
+    # shellcheck disable=SC2086
+    if resolved=$(TMPDIR=/tmp $tsx_bin "$cli" "${cli_args[@]}" 2>/dev/null); then
+        # Newline list → space list (is_excluded_rule iterates words).
+        EXCLUDE_RULES="$(echo "$resolved" | tr '\n' ' ')"
+        local n
+        n="$(echo "$resolved" | grep -c . || true)"
+        log_verbose "rule scope resolved: $n excluded rule(s)"
+    else
+        log_verbose "rule-scope CLI failed — static exclude fallback"
+    fi
+    return 0
+}
+
 # Check if a relative path matches an excluded rule
 is_excluded_rule() {
     local rel_path="$1"
@@ -470,6 +517,60 @@ clean_stale() {
 }
 
 
+# Emit host-NATIVE rule surfaces for consumer Cursor (.mdc with globs) and
+# Windsurf (.windsurf/rules + .windsurfrules) via the exported condense
+# emitters — so consumer installs carry the same trigger signal as the
+# maintainer projection (road-to-request-scoped-rule-load Phase 1b Step 3;
+# the recorded install-time-vs-dist decision lives in
+# src/install/emit_host_rules_cli.ts). Sets CURSOR_NATIVE_EMITTED /
+# WINDSURF_NATIVE_EMITTED so the legacy surfaces (raw-md symlink farm,
+# bash frontmatter-stripping concatenator) run only as no-node fallbacks.
+CURSOR_NATIVE_EMITTED=false
+WINDSURF_NATIVE_EMITTED=false
+emit_host_rules() {
+    local project_root="$1"
+    local rules_dir="$project_root/.augment/rules"
+    local cli="$SOURCE_DIR/src/install/emit_host_rules_cli.ts"
+    [[ -d "$rules_dir" && -f "$cli" ]] || return 0
+
+    local -a tools=()
+    is_tool_enabled "cursor" && tools+=("cursor")
+    is_tool_enabled "windsurf" && tools+=("windsurf")
+    [[ ${#tools[@]} -gt 0 ]] || return 0
+
+    if $DRY_RUN; then
+        log_verbose "emit host-native rules (${tools[*]})"
+        return 0
+    fi
+
+    local tsx_bin=""
+    if [[ -x "$SOURCE_DIR/node_modules/.bin/tsx" ]]; then
+        tsx_bin="$SOURCE_DIR/node_modules/.bin/tsx"
+    elif command -v npx >/dev/null 2>&1; then
+        tsx_bin="npx --yes tsx"
+    else
+        log_verbose "no tsx/npx runtime — legacy host-rule surfaces"
+        return 0
+    fi
+
+    local tools_csv
+    tools_csv="$(IFS=,; echo "${tools[*]}")"
+    # TMPDIR pinned: tsx cache must never land in the install target.
+    # shellcheck disable=SC2086
+    if TMPDIR=/tmp $tsx_bin "$cli" --rules-dir "$rules_dir" \
+        --project-root "$project_root" --tools "$tools_csv" >/dev/null 2>&1; then
+        for tool in "${tools[@]}"; do
+            case "$tool" in
+                cursor)   CURSOR_NATIVE_EMITTED=true;   log_info "Emitted native .cursor/rules/*.mdc" ;;
+                windsurf) WINDSURF_NATIVE_EMITTED=true; log_info "Emitted native .windsurf/rules + .windsurfrules" ;;
+            esac
+        done
+    else
+        log_verbose "host-rule emission failed — legacy fallback surfaces"
+    fi
+    return 0
+}
+
 # Create tool-specific rule symlinks (filtered by --tools selection).
 # Map: tool ID → (target dir, relative prefix from target → .augment/rules).
 create_tool_symlinks() {
@@ -482,7 +583,11 @@ create_tool_symlinks() {
     local -a tool_dirs=()
     local -a rel_prefixes=()
     is_tool_enabled "claude-code" && { tool_ids+=("claude-code"); tool_dirs+=(".claude/rules");  rel_prefixes+=("../../.augment/rules"); }
-    is_tool_enabled "cursor"      && { tool_ids+=("cursor");      tool_dirs+=(".cursor/rules");  rel_prefixes+=("../../.augment/rules"); }
+    # Cursor gets NATIVE .mdc files when emit_host_rules succeeded — the
+    # raw-md symlink farm is the no-node fallback only (Phase 1b Step 3).
+    if ! $CURSOR_NATIVE_EMITTED; then
+        is_tool_enabled "cursor"  && { tool_ids+=("cursor");      tool_dirs+=(".cursor/rules");  rel_prefixes+=("../../.augment/rules"); }
+    fi
     is_tool_enabled "cline"       && { tool_ids+=("cline");       tool_dirs+=(".clinerules");    rel_prefixes+=("../.augment/rules"); }
 
     if [[ ${#tool_dirs[@]} -eq 0 ]]; then
@@ -596,6 +701,9 @@ generate_windsurfrules() {
     local project_root="$1"
     local rules_dir="$project_root/.augment/rules"
 
+    # Native emission (frontmatter-aware, trigger-preserving) already wrote
+    # .windsurfrules — this bash concatenator is the no-node fallback only.
+    $WINDSURF_NATIVE_EMITTED && { log_verbose "skip bash .windsurfrules (native emitted)"; return 0; }
     [[ -d "$rules_dir" ]] || return 0
     is_tool_enabled "windsurf" || { log_verbose "skip .windsurfrules (windsurf not selected)"; return 0; }
 
@@ -1107,6 +1215,10 @@ main() {
     #     install the file does not exist yet → defaults preserved.
     resolve_settings
 
+    # 0c. Resolve the excluded-rule set for this install (workspace/pack
+    #     scope via the shared rule_scope CLI; static compat fallback).
+    resolve_excluded_rules
+
     # 1. Hybrid sync payload → target/.augment/
     sync_hybrid "$SOURCE_PAYLOAD" "$TARGET_DIR/.augment"
     if $USE_RULES_SYMLINKS; then
@@ -1130,7 +1242,9 @@ main() {
         log_verbose "skip .github/copilot-instructions.md (copilot not selected)"
     fi
 
-    # 3. Create tool-specific symlinks
+    # 3. Emit host-native rule surfaces (cursor .mdc / windsurf), then
+    #    create tool-specific symlinks for the remaining tools.
+    emit_host_rules "$TARGET_DIR"
     create_tool_symlinks "$TARGET_DIR"
     create_skill_symlinks "$TARGET_DIR"
 

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