@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/_lib/rule_injection.ts

@@ -0,0 +1,239 @@
+/**
+ * Rule-injection core — THE single module both the offline model and the
+ * runtime concern read.
+ *
+ * WHY ONE MODULE. `road-to-trigger-delivered-rule-bodies` step 0.5 states the
+ * failure this prevents in as many words: *an experiment whose offline pricing
+ * and runtime delivery use different matchers measures nothing*. So the price /
+ * recall model (`src/scripts/model_rule_injection.ts`) and the delivery concern
+ * (`src/scripts/hooks/rule_inject_hook.ts`) both import THIS file, and neither
+ * re-implements selection, ordering, capping, or body loading.
+ *
+ * IT OWNS NO MATCHER. Trigger semantics belong to
+ * [`_lib/router_match.ts`](router_match.ts), which is already the single
+ * implementation for every surface that answers "which rules fire on this
+ * prompt?" and is pinned by `tests/scripts/router_match_parity.test.ts`. A
+ * second matcher here would be the violation that test exists to catch, so
+ * `matchTierRules` is a thin, deterministic wrapper over `match_prompt` and
+ * nothing more. Step 0.3's pre-registered comparison found no reason to write
+ * one — see `model_rule_injection.ts`'s header for the measured verdict.
+ *
+ * KERNEL IS NEVER INJECTED. The nine kernel rules are in standing context by
+ * definition; injecting one would be paying twice for a body that is already
+ * there. `match_prompt` returns kernel ids in `activated_rules` because kernel
+ * rules are always active — this module filters them out by construction rather
+ * than relying on a caller to remember.
+ *
+ * IT IMPORTS NO TOKENIZER, AND THAT IS A HOT-PATH FACT RATHER THAN A STYLE
+ * CHOICE. `_lib/token_count.ts` resolves `js-tiktoken` AT MODULE LOAD, and the
+ * concern that imports this file is statically reachable from
+ * `concern_registry.ts` — so importing it here made every hook dispatch on
+ * every slot pay a tokenizer load for a concern that is default-OFF and emits
+ * nothing. Measured on this tree: unbinding the concern moved the
+ * `pre_tool_use` p95 from 202 ms to 196 ms, and the CI latency gate went red on
+ * the branch that introduced it while passing on main.
+ *
+ * So the runtime cap is in BYTES. That is not a weaker bound — it is the same
+ * bound in the unit the budget actually enforces: `hook-token-budget.json`
+ * measures "bytes of concern stdout payload fields", so the cap and its
+ * registered row are now the same number instead of two units that need a
+ * conversion factor to compare. The offline model keeps exact-BPE tokens for
+ * its price table, where the tokenizer is the point and nothing is on a hot
+ * path.
+ *
+ * DETERMINISM IS THE CONTRACT, and the collision cases are the reason it needs
+ * stating. Two triggers on the SAME rule collapse to one entry (a rule is
+ * delivered once, however many of its triggers fired) while the trigger count
+ * survives as `score`. Two DIFFERENT rules both firing are returned in router
+ * declaration order, tier_1 before tier_2 — never in match order, which would
+ * make the output depend on trigger authoring order inside a rule. Capping
+ * sorts by descending score with router order as the tie-break, so the same
+ * prompt against the same router always yields the same bytes.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { match_prompt, type Router, type Trigger } from './router_match.js';
+
+export type { Router, Trigger };
+
+/** Tier a matched rule came from. Kernel is never a value here. */
+export type Tier = 'tier_1' | 'tier_2';
+
+export interface TierRuleMatch {
+    id: string;
+    tier: Tier;
+    /** How many of this rule's triggers matched. Ties break on router order. */
+    score: number;
+    /** Router declaration index within its tier — the deterministic tie-break. */
+    order: number;
+}
+
+/** Kinds of trigger a prompt alone can never fire. */
+export const PATH_TRIGGER_KINDS = ['path_prefix', 'file_pattern'] as const;
+
+export function loadRouter(repoRoot: string): Router {
+    const p = path.join(repoRoot, 'dist', 'router.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as Router;
+}
+
+/** Kernel rule ids, as declared by the router. */
+export function kernelIds(router: Router): Set<string> {
+    const k = Array.isArray(router['kernel']) ? router['kernel'] : [];
+    return new Set(k.map((x) => String(x)));
+}
+
+function tierEntries(router: Router, tier: Tier): Array<{ id: string; triggers: Trigger[] }> {
+    const raw = router[tier];
+    if (!Array.isArray(raw)) return [];
+    return (raw as unknown as Array<Record<string, unknown>>).map((r) => ({
+        id: String(r['id'] ?? ''),
+        triggers: Array.isArray(r['triggers']) ? (r['triggers'] as Trigger[]) : [],
+    }));
+}
+
+/** Every tier rule declared by the router, with its trigger list. */
+export function allTierRules(router: Router): Array<{ id: string; tier: Tier; triggers: Trigger[] }> {
+    const out: Array<{ id: string; tier: Tier; triggers: Trigger[] }> = [];
+    for (const tier of ['tier_1', 'tier_2'] as Tier[]) {
+        for (const e of tierEntries(router, tier)) out.push({ ...e, tier });
+    }
+    return out;
+}
+
+/** Rules whose triggers are ALL path-shaped — unreachable from a prompt alone. */
+export function pathOnlyRuleIds(router: Router): Set<string> {
+    const ids = new Set<string>();
+    for (const r of allTierRules(router)) {
+        if (r.triggers.length === 0) continue;
+        const allPath = r.triggers.every((t) =>
+            PATH_TRIGGER_KINDS.some((k) => k in t),
+        );
+        if (allPath) ids.add(r.id);
+    }
+    return ids;
+}
+
+/** Rules declaring at least one path-shaped trigger. */
+export function pathCapableRuleIds(router: Router): Set<string> {
+    const ids = new Set<string>();
+    for (const r of allTierRules(router)) {
+        if (r.triggers.some((t) => PATH_TRIGGER_KINDS.some((k) => k in t))) ids.add(r.id);
+    }
+    return ids;
+}
+
+/** Rules declaring no trigger at all — cannot be delivered, must stay eager. */
+export function triggerlessRuleIds(router: Router): string[] {
+    return allTierRules(router)
+        .filter((r) => r.triggers.length === 0)
+        .map((r) => r.id);
+}
+
+/**
+ * Which tier rules fire on this prompt (+ optional open files / command).
+ *
+ * Kernel is excluded. Order is router declaration order, tier_1 first.
+ */
+export function matchTierRules(
+    router: Router,
+    prompt: string,
+    openFiles?: Iterable<string> | null,
+    command?: string | null,
+): TierRuleMatch[] {
+    const kernel = kernelIds(router);
+    const res = match_prompt(router, prompt, 'full', openFiles, command);
+    const scores = new Map<string, number>();
+    for (const mt of res.matched_triggers) {
+        const id = String(mt.rule ?? '');
+        if (id === '' || kernel.has(id)) continue;
+        scores.set(id, (scores.get(id) ?? 0) + 1);
+    }
+    const out: TierRuleMatch[] = [];
+    let order = 0;
+    for (const r of allTierRules(router)) {
+        const s = scores.get(r.id);
+        if (s === undefined) {
+            order += 1;
+            continue;
+        }
+        out.push({ id: r.id, tier: r.tier, score: s, order });
+        order += 1;
+    }
+    return out;
+}
+
+/** Where the projected body of a rule lives. */
+export function ruleBodyPath(repoRoot: string, id: string): string {
+    return path.join(repoRoot, 'dist', 'agent-src', 'rules', `${id}.md`);
+}
+
+/** The projected body, or `null` when the rule has no projected file. */
+export function loadRuleBody(repoRoot: string, id: string): string | null {
+    const p = ruleBodyPath(repoRoot, id);
+    if (!fs.existsSync(p)) return null;
+    return fs.readFileSync(p, 'utf8');
+}
+
+/**
+ * UTF-8 byte length — the runtime measure, dependency-free by design.
+ *
+ * Deliberately NOT a token count: see the header. Bytes are exact, need no
+ * tokenizer, and are the unit `hook-token-budget.json` enforces.
+ */
+export function bytesOf(text: string): number {
+    return Buffer.byteLength(text, 'utf8');
+}
+
+export interface SelectionResult {
+    selected: TierRuleMatch[];
+    /** Matched but dropped because the byte cap was reached. */
+    dropped: TierRuleMatch[];
+    /** Byte sum of the selected bodies. */
+    bytes: number;
+    /** Per-rule body byte counts, keyed by id, for every MATCHED rule. */
+    bodyBytes: Map<string, number>;
+}
+
+/**
+ * Apply the per-prompt BYTE cap.
+ *
+ * Highest score first, router order as tie-break; a rule whose body would push
+ * the running total past `capBytes` is dropped and the walk continues, so one
+ * oversized body cannot starve the rest. The returned `selected` list is
+ * re-sorted back into router order — cap order is a budgeting concern, delivery
+ * order is not.
+ *
+ * ONE selection for both callers. The offline model and the runtime concern
+ * call THIS function with THE SAME cap, so the set the price table prices is
+ * byte-for-byte the set the concern delivers. That is step 0.5's requirement,
+ * and expressing the cap in bytes makes it hold without a token/byte
+ * conversion sitting between the two arms.
+ */
+export function selectForInjection(
+    repoRoot: string,
+    matches: TierRuleMatch[],
+    capBytes: number,
+): SelectionResult {
+    const bodyBytes = new Map<string, number>();
+    for (const m of matches) {
+        const body = loadRuleBody(repoRoot, m.id);
+        bodyBytes.set(m.id, body === null ? 0 : bytesOf(body));
+    }
+    const ranked = [...matches].sort((a, b) => b.score - a.score || a.order - b.order);
+    const selected: TierRuleMatch[] = [];
+    const dropped: TierRuleMatch[] = [];
+    let total = 0;
+    for (const m of ranked) {
+        const t = bodyBytes.get(m.id) ?? 0;
+        if (total + t > capBytes && selected.length > 0) {
+            dropped.push(m);
+            continue;
+        }
+        selected.push(m);
+        total += t;
+    }
+    selected.sort((a, b) => a.order - b.order);
+    dropped.sort((a, b) => a.order - b.order);
+    return { selected, dropped, bytes: total, bodyBytes };
+}

package/src/scripts/_lib/run_checkpoint.ts

@@ -57,6 +57,21 @@ export interface RunCheckpoint {
     readonly next_step: string | null;
     /** Commit the tree was on. A resume onto a different commit is normal, and visible. */
     readonly head: string | null;
+    /**
+     * The situational-awareness reading this run last took —
+     * `contextFingerprint()` over `origin/main` plus every open PR's head SHA.
+     *
+     * `road-to-roadmap-situational-awareness` § 5.6. Every other field here
+     * reports **roadmap** drift; none reported **repository** drift, so a run
+     * resumed after a long gap trusted a context reading it never re-took. A
+     * disagreement here forces a re-probe before the first step.
+     *
+     * Optional: a checkpoint written before this field existed, or by a run that
+     * could not reach the probe, is still a valid checkpoint. Absent means "not
+     * known", never "unchanged" — `verifyCheckpoint` treats a null on either
+     * side as unknown, the same way it already treats `head`.
+     */
+    readonly context_fingerprint?: string | null;
     readonly written_at: string;
 }
 
@@ -109,6 +124,16 @@ export interface BuildOptions {
     /** Injected so a test does not depend on the ambient git state. */
     readonly head?: string | null;
     readonly now?: () => Date;
+    /**
+     * The run's situational-awareness fingerprint
+     * (`roadmap:context --fingerprint`). Injected rather than read here, so this
+     * library keeps its no-subprocess property — `readHead` reads `.git`
+     * directly for the same reason, and the probe cannot.
+     *
+     * Omitted → the field is absent, and a resume reports "not known" rather
+     * than asserting the repository stood still.
+     */
+    readonly contextFingerprint?: string | null;
 }
 
 /**
@@ -204,6 +229,12 @@ export function buildCheckpoint(
         parked_steps: counts.parked,
         next_step: counts.next,
         head: opts.head ?? readHead(repoRoot),
+        // Absent rather than null when nothing was supplied: a checkpoint that
+        // predates this field and one written without a probe are the same
+        // state, and both must read as "not known".
+        ...(opts.contextFingerprint !== undefined
+            ? { context_fingerprint: opts.contextFingerprint }
+            : {}),
         written_at: (opts.now ?? ((): Date => new Date()))().toISOString(),
     };
 }
@@ -310,7 +341,16 @@ export interface VerifyResult {
  * 4, actual 3" tells it a step landed after the checkpoint was written and
  * which count to trust.
  */
-export function verifyCheckpoint(repoRoot: string, cp: RunCheckpoint): VerifyResult {
+export function verifyCheckpoint(
+    repoRoot: string,
+    cp: RunCheckpoint,
+    /**
+     * The fingerprint a fresh `roadmap:context --fingerprint` returned, when the
+     * resumed run took one. Omitted → the field reports "not known" rather than
+     * asserting the repository stood still.
+     */
+    currentFingerprint?: string | null,
+): VerifyResult {
     let text: string;
     try {
         text = fs.readFileSync(roadmapPath(repoRoot, cp.roadmap), 'utf-8');
@@ -349,6 +389,19 @@ export function verifyCheckpoint(repoRoot: string, cp: RunCheckpoint): VerifyRes
             // than a missing one: it trains the reader to skip the line.
             agrees: cp.head === null || head === null || cp.head === head,
         },
+        // Repository drift, which no other field here reports. The `actual` is
+        // supplied by the caller (the probe is a subprocess and this library
+        // stays I/O-light) — absent means the caller did not re-probe, and an
+        // unknown on either side is never a disagreement, exactly as for `head`.
+        {
+            field: 'context_fingerprint',
+            claimed: cp.context_fingerprint ?? null,
+            actual: currentFingerprint ?? null,
+            agrees:
+                (cp.context_fingerprint ?? null) === null ||
+                (currentFingerprint ?? null) === null ||
+                cp.context_fingerprint === currentFingerprint,
+        },
     ];
     return { readable: true, fields, agrees: fields.every((f) => f.agrees) };
 }

package/src/scripts/_lib/scoped_projection.ts

@@ -260,3 +260,99 @@ export function scoped_projection_stats(
         workspaces: [...SCOPED_ACTIVE_WORKSPACES].sort(),
     };
 }
+
+/** The installer's deploy tuple: [written, skipped, status, paths]. */
+export type DeployTuple = [number, number, string, string[]];
+
+// --- Deploy-tree prune mechanics ------------------------------------------
+// Moved here WHOLE from `install.ts` (a pure move, names forwarded there) so
+// the prune sits beside `is_pruned_under_scoped`, the predicate it consumes —
+// which is what this module's header says it exists for. It also pays for the
+// `check_source_size_budget` ratchet, which counts every line in a file above
+// 1,500 and which `install.ts` at 5,466 lines cannot grow past.
+
+/**
+ * Remove skills/commands matching `is_pruned` from a completed deploy.
+ *
+ * road-to-install-contract-stability Phase 2 Step 2 (generalized in
+ * road-to-credible-install Phase 2 to back both the core-only lab prune and
+ * the scoped-projection pack prune off the same mechanics). Skills are
+ * pruned by whole directory (tier decided by the skill's `SKILL.md`
+ * frontmatter); commands by file (own frontmatter). Rules / personas /
+ * contexts / templates are core/shared and left intact. Returns
+ * `[pruned_count, adjusted_results]` with the pruned paths removed from each
+ * tool's `written_paths` so the manifest never records them.
+ */
+export function prune_modules_by(
+    deploy_results: Record<string, DeployTuple>,
+    is_pruned: (md_path: string) => boolean,
+): [number, Record<string, DeployTuple>] {
+    let pruned = 0;
+    const adjusted: Record<string, DeployTuple> = {};
+    for (const tool_id of Object.keys(deploy_results)) {
+        const [written, skipped, status, paths] = deploy_results[tool_id] as DeployTuple;
+        const pruned_skill_dirs = new Set<string>();
+        for (const p of paths) {
+            const parts = p.split(path.sep);
+            if (parts.includes('skills')) {
+                const i = parts.indexOf('skills');
+                if (i + 1 < parts.length) {
+                    const skill_root = parts.slice(0, i + 2).join(path.sep);
+                    if (!pruned_skill_dirs.has(skill_root)) {
+                        const skillmd = path.join(skill_root, 'SKILL.md');
+                        if (fs.existsSync(skillmd) && is_pruned(skillmd)) {
+                            pruned_skill_dirs.add(skill_root);
+                        }
+                    }
+                }
+            }
+        }
+        const keep: string[] = [];
+        const delete_files: string[] = [];
+        for (const p of paths) {
+            const parts = p.split(path.sep);
+            let is_target = false;
+            if (parts.includes('skills')) {
+                const i = parts.indexOf('skills');
+                if (i + 1 < parts.length && pruned_skill_dirs.has(parts.slice(0, i + 2).join(path.sep))) {
+                    is_target = true;
+                }
+            } else if (
+                parts.includes('commands') &&
+                path.extname(p) === '.md' &&
+                is_pruned(p)
+            ) {
+                is_target = true;
+            }
+            (is_target ? delete_files : keep).push(p);
+        }
+        for (const d of pruned_skill_dirs) {
+            fs.rmSync(d, { recursive: true, force: true });
+        }
+        for (const p of delete_files) {
+            if (p.split(path.sep).includes('commands') && fs.existsSync(p)) {
+                try {
+                    fs.unlinkSync(p);
+                } catch {
+                    // OSError → swallow, mirroring the .py.
+                }
+            }
+        }
+        pruned += delete_files.length;
+        adjusted[tool_id] = [Math.max(0, written - delete_files.length), skipped, status, keep];
+    }
+    return [pruned, adjusted];
+}
+
+/**
+ * Remove lab-tier skills/commands from a completed deploy (core-only).
+ *
+ * road-to-install-contract-stability Phase 2 Step 2. Thin wrapper over
+ * `_prune_modules_by` — see that function for the mechanics.
+ */
+export function prune_lab_modules(
+    deploy_results: Record<string, DeployTuple>,
+    lab_ids: Set<string>,
+): [number, Record<string, DeployTuple>] {
+    return prune_modules_by(deploy_results, (p) => surface_tiers.is_lab_artefact(p, lab_ids));
+}

package/src/scripts/_lib/session_register.ts

@@ -226,6 +226,22 @@ export interface SessionRecord {
      * session that was never refused, is still a valid record.
      */
     turn_end_refusals?: Record<string, number>;
+    /**
+     * Repo-relative paths this session has declared it owns, or absent when it
+     * has declared none.
+     *
+     * `road-to-roadmap-situational-awareness` § 3.1. The register compared slugs
+     * and branch names and nothing else, so two sessions on two different
+     * roadmaps that happen to edit the same file were invisible to each other —
+     * the axis that actually predicts a merge conflict was the one axis nobody
+     * carried.
+     *
+     * Additive on exactly the terms `turn_end_refusals` established: a session
+     * that declared no paths leaves the record **byte-identical** to what it was
+     * before this field existed, so a reader that does not know the field is
+     * unaffected and a diff of two records still shows only what changed.
+     */
+    owned_paths?: string[];
 }
 
 /**
@@ -430,11 +446,21 @@ export function foreign_live_records(
  * so the branch comparison was silent by construction while a whole
  * implementation was duplicated. One of the two PRs is thrown away either way.
  */
-export type CollisionKind = 'roadmap' | 'branch';
+/**
+ * `path` is the third axis, added last and cheapest to be wrong about: two
+ * sessions can be on different roadmaps and different branches and still be
+ * editing one file. It is reported SEPARATELY rather than folded into either of
+ * the two above, because the response differs — a roadmap collision means stop,
+ * a branch collision means coordinate, a path collision means take the disjoint
+ * steps first and say so.
+ */
+export type CollisionKind = 'roadmap' | 'branch' | 'path';
 
 export interface Collision {
     kind: CollisionKind;
     record: SessionRecord;
+    /** For `kind: 'path'`, the shared paths. Absent on the other two kinds. */
+    paths?: string[];
 }
 
 /**
@@ -451,7 +477,11 @@ export interface Collision {
  */
 export function classify_collisions(
     others: readonly SessionRecord[],
-    here: { branch: string | null; roadmap_slug: string | null },
+    here: {
+        branch: string | null;
+        roadmap_slug: string | null;
+        owned_paths?: readonly string[];
+    },
 ): Collision[] {
     const out: Collision[] = [];
     for (const r of others) {
@@ -468,5 +498,17 @@ export function classify_collisions(
             out.push({ kind: 'branch', record: r });
         }
     }
+    // Last, and last on purpose: the two axes above are unchanged in meaning and
+    // in order, so a consumer that filters on `roadmap` or `branch` sees exactly
+    // what it saw before this axis existed.
+    const mine = new Set(here.owned_paths ?? []);
+    if (mine.size > 0) {
+        for (const r of others) {
+            const shared = (r.owned_paths ?? []).filter((p) => mine.has(p)).sort();
+            if (shared.length > 0) {
+                out.push({ kind: 'path', record: r, paths: shared });
+            }
+        }
+    }
     return out;
 }

package/src/scripts/_lib/skill_catalogue.ts

@@ -730,6 +730,17 @@ export interface ProjectionModeCounts {
     prunedUnderScoped: number;
     /** Pack ids active by default under `scoped`, sorted. */
     activePacks: string[];
+    /**
+     * Skills a `projection.mode: tiered` install deploys natively — those
+     * predicted to reach the model WITH their description. `null` when no tier
+     * split exists on this machine, which is the common case and is NOT zero.
+     */
+    tierACount: number | null;
+    /**
+     * Skills `tiered` withholds from the native catalogue; still served by the
+     * MCP recovery tools. `null` under the same condition as `tierACount`.
+     */
+    tierBCount: number | null;
 }
 
 /**
@@ -791,8 +802,26 @@ export function formatProjectionModes(
         `  legacy-all:  ${counts.legacyAll}`,
         `  pruned under scoped: ${counts.prunedUnderScoped}`,
         `  active packs under scoped: ${counts.activePacks.length}`,
-        '',
     ];
+    if (counts.tierACount === null || counts.tierBCount === null) {
+        lines.push(
+            '  tiered:      no split on this machine (agents/runtime/state/skill-tiers.json',
+            '               absent) — not zero, unmeasured. `tiered` ships the full surface',
+            '               until a split exists.',
+        );
+    } else {
+        lines.push(
+            `  tiered:      tier A ${counts.tierACount} native + tier B ${counts.tierBCount} ` +
+                `MCP-only = ${counts.tierACount + counts.tierBCount}`,
+        );
+        if (counts.tierACount + counts.tierBCount !== counts.legacyAll) {
+            lines.push(
+                `               ⚠️  tier A + tier B (${counts.tierACount + counts.tierBCount}) != ` +
+                    `legacy-all (${counts.legacyAll}) — the split is STALE, recompute it.`,
+            );
+        }
+    }
+    lines.push('');
     if (rows.length === 0) {
         lines.push(
             'No host root measured. Pass --host-root <dir> (repeatable) to read what',
@@ -959,6 +988,7 @@ export interface MigrationEligibility {
         | 'observation-not-comparable'
         | 'no-truncation-observed'
         | 'already-scoped'
+        | 'already-tiered'
         | 'below-observed-skill-volume';
     /** Populated only when eligible, for the message. */
     droppedEntries?: number;
@@ -981,11 +1011,17 @@ export interface MigrationEligibility {
  */
 export function migrationEligibility(
     host: string,
-    resolvedMode: 'scoped' | 'legacy-all',
+    resolvedMode: 'scoped' | 'legacy-all' | 'tiered',
     currentSkillCount: number,
     limits: ReadonlyMap<string, KnownHostLimit>,
 ): MigrationEligibility {
     if (resolvedMode === 'scoped') return { eligible: false, reason: 'already-scoped' };
+    // `tiered` already withholds skills from the native catalogue, so an offer to
+    // migrate to `scoped` has nothing to buy. It gets its OWN reason rather than
+    // reusing `already-scoped`: the two narrow on different axes (packs vs the
+    // host's listing budget), and a caller reading the reason should be able to
+    // tell which one the install is actually on.
+    if (resolvedMode === 'tiered') return { eligible: false, reason: 'already-tiered' };
     const limit = limits.get(host);
     if (limit === undefined) return { eligible: false, reason: 'no-observation-for-host' };
     if (limit.projectedSkills === null) return { eligible: false, reason: 'observation-not-comparable' };