@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_lib/host_projection_reach.ts

@@ -0,0 +1,157 @@
+/**
+ * Per-host projection reach — does each host's generated tree actually carry
+ * artefacts, and when it does not, WHY.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 3 Step 1. The existing
+ * `check_host_loadability.ts` proves two projections PARSE; `smoke_host_loadability.sh`
+ * proves one host CLI (claude) ACCEPTS its plugin. Neither answers the question
+ * this module exists for: **of the host trees this package generates, how many
+ * reach anything, and for each one that does not, is the tool absent or is the
+ * projection empty?**
+ *
+ * Those two are the same green today, and they are opposite findings. A tool
+ * nobody has installed producing no artefacts is correct. A tool that IS
+ * installed producing no artefacts is a dead projection, and the current gates
+ * report it as a clean pass.
+ *
+ * ── The skip reason is the deliverable ──────────────────────────────────────
+ * The step asks to "skip with a recorded reason when the tool is absent, per the
+ * completeness ledger". So an absent tool is `skipped` with a NAMED reason, never
+ * a silent zero — the distinction this whole roadmap is about.
+ *
+ * ── What this does NOT do ───────────────────────────────────────────────────
+ * It does not install into a throwaway HOME and invoke the host's own loader.
+ * That is `smoke_host_loadability.sh`, it exists for claude, and extending it to
+ * eight hosts means eight vendor CLIs on the runner — a dependency decision, not
+ * a check. This module reports REACH from the tree, and says so rather than
+ * implying a host validated anything.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/** One host's generated surface, and how to tell whether the tool is present. */
+export interface HostSurface {
+    /** Tool id, matching `src/install/toolDetection.ts`. */
+    id: string;
+    /** Executables that indicate the tool is installed. */
+    bins: readonly string[];
+    /** Home-relative paths that indicate the tool is installed. */
+    homePaths: readonly string[];
+    /** Repo-relative projection paths this package generates for the host. */
+    projections: readonly string[];
+    /** Below this the projection is treated as empty rather than thin. */
+    minArtefacts: number;
+}
+
+/**
+ * The host surfaces this package generates, with their detection signals.
+ *
+ * Deliberately NOT every id in `toolDetection.ts`: that table lists 23 tools
+ * the wizard can record, most of which this package writes no dedicated tree
+ * for — they read `AGENTS.md`, which is one file and has its own gates. Listing
+ * them here would produce twenty rows of "0 artefacts, correctly", which is the
+ * padding that makes a report unreadable.
+ */
+export const HOST_SURFACES: readonly HostSurface[] = [
+    {
+        id: 'claude-code',
+        bins: ['claude'],
+        homePaths: ['.claude', '.claude.json'],
+        projections: ['.claude/skills', '.claude/rules', '.claude/commands'],
+        minArtefacts: 1,
+    },
+    { id: 'cursor', bins: ['cursor'], homePaths: ['.cursor'], projections: ['.cursor/rules', '.cursor/commands'], minArtefacts: 1 },
+    { id: 'cline', bins: [], homePaths: ['Documents/Cline'], projections: ['.clinerules'], minArtefacts: 1 },
+    { id: 'windsurf', bins: ['windsurf'], homePaths: ['.codeium/windsurf'], projections: ['.windsurf/rules', '.windsurf/workflows'], minArtefacts: 1 },
+    { id: 'gemini-cli', bins: ['gemini'], homePaths: ['.gemini'], projections: ['GEMINI.md'], minArtefacts: 1 },
+    { id: 'copilot', bins: ['copilot'], homePaths: ['.config/github-copilot'], projections: ['.github/copilot-instructions.md'], minArtefacts: 1 },
+];
+
+export type ReachStatus = 'ok' | 'empty-projection' | 'skipped-tool-absent';
+
+export interface HostReach {
+    id: string;
+    status: ReachStatus;
+    artefacts: number;
+    /** Present for every non-`ok` row. A status with no reason is what this replaces. */
+    reason: string;
+    present: boolean;
+}
+
+/** Count files under a projection path — one file is one artefact, recursively. */
+export function countArtefacts(root: string, rel: string): number {
+    const abs = path.join(root, rel);
+    let st: fs.Stats;
+    try {
+        st = fs.statSync(abs);
+    } catch {
+        return 0;
+    }
+    if (st.isFile()) return 1;
+    let n = 0;
+    const walk = (dir: string): void => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (ent.isDirectory()) walk(path.join(dir, ent.name));
+            else n += 1;
+        }
+    };
+    walk(abs);
+    return n;
+}
+
+/** True when any detection signal for the host hits. */
+export function toolPresent(
+    surface: HostSurface,
+    opts: { home?: string; pathEnv?: string; exists?: (p: string) => boolean } = {},
+): boolean {
+    const home = opts.home ?? os.homedir();
+    const exists = opts.exists ?? ((p: string) => fs.existsSync(p));
+    for (const rel of surface.homePaths) {
+        if (exists(path.join(home, rel))) return true;
+    }
+    const pathEnv = opts.pathEnv ?? process.env['PATH'] ?? '';
+    for (const bin of surface.bins) {
+        for (const dir of pathEnv.split(path.delimiter)) {
+            if (dir !== '' && exists(path.join(dir, bin))) return true;
+        }
+    }
+    return false;
+}
+
+export function measureReach(
+    root: string,
+    surfaces: readonly HostSurface[] = HOST_SURFACES,
+    opts: { home?: string; pathEnv?: string; exists?: (p: string) => boolean } = {},
+): HostReach[] {
+    return surfaces.map((s) => {
+        const artefacts = s.projections.reduce((n, rel) => n + countArtefacts(root, rel), 0);
+        const present = toolPresent(s, opts);
+        if (artefacts >= s.minArtefacts) {
+            return { id: s.id, status: 'ok' as const, artefacts, reason: '', present };
+        }
+        if (!present) {
+            return {
+                id: s.id,
+                status: 'skipped-tool-absent' as const,
+                artefacts,
+                reason:
+                    `no detection signal for ${s.id} on this machine (bins: ${s.bins.join(', ') || 'none'}; ` +
+                    `home paths: ${s.homePaths.join(', ') || 'none'}) — an unprojected tree for an ` +
+                    'uninstalled tool is the correct state, not a gap',
+                present,
+            };
+        }
+        return {
+            id: s.id,
+            status: 'empty-projection' as const,
+            artefacts,
+            reason:
+                `${s.id} IS installed and its projection carries ${String(artefacts)} artefact(s) ` +
+                `(${s.projections.join(', ')}) — a dead projection for a present tool, which the ` +
+                'shape gates report as a clean pass because they only read what exists',
+            present,
+        };
+    });
+}

package/src/scripts/_lib/ignored_blocker.ts

@@ -0,0 +1,148 @@
+/**
+ * The ignored-blocker detector (`road-to-runtime-event-journal` Phase 3).
+ *
+ * `outcome_envelope.ts` already refuses to report a failure as a success. The
+ * gap it left is one layer up: nothing recorded whether the ORCHESTRATOR did
+ * anything with that failure. A `blocked` return the orchestrator dropped and a
+ * `blocked` return it read and deliberately set aside were byte-identical, so
+ * an ignored blocker was undetectable by construction — not hard to detect,
+ * *undetectable*, because the distinguishing fact was never written down.
+ *
+ * The acknowledgment field set closes that, and this module is the predicate
+ * over it. One rule, stated once:
+ *
+ *   a return in a NON-SUCCESS state carrying NO acknowledgment is an
+ *   IGNORED BLOCKER.
+ *
+ * Two boundaries follow from it and are load-bearing in opposite directions:
+ *
+ * 1. **`rejected-with-reason` is NOT a finding.** A reader who read the
+ *    blocker, weighed it and rejected it with a named reason has consumed the
+ *    return. Reporting that would make the detector fire on the compliant
+ *    path, and a detector that punishes the behaviour it wants is a detector
+ *    people route around.
+ * 2. **A success carrying no acknowledgment is NOT a finding.** Requiring an
+ *    acknowledgment on every return would make the field a formality on the
+ *    99 % path and noise on the 1 % that matters. Only a non-success return
+ *    was ever owed a decision.
+ *
+ * Nothing here is a gate. It is a predicate plus a query shape, so both the
+ * in-session check and the after-the-fact journal query answer the same
+ * question with the same rule rather than two that drift.
+ */
+
+import { NON_SUCCESS_STATES } from './outcome_envelope.js';
+import type { ConsumptionState, OutcomeEnvelope, TerminalState } from './outcome_envelope.js';
+
+/**
+ * Is this return an ignored blocker?
+ *
+ * The core condition, in one place so that neutralising it for a sensitivity
+ * probe neutralises BOTH the live check and the journal query — a test that can
+ * only be broken in one of the two would establish sensitivity for half the
+ * mechanism.
+ */
+export function isIgnoredBlocker(env: Pick<OutcomeEnvelope, 'state' | 'acknowledgment'>): boolean {
+    return NON_SUCCESS_STATES.has(env.state) && env.acknowledgment === undefined;
+}
+
+/** Why a return was reported, in a form a caller can print without re-deriving it. */
+export interface IgnoredBlockerFinding {
+    readonly state: TerminalState;
+    /** The producer's next action — the thing that went unactioned. */
+    readonly suggestion: string;
+    /** Set when the finding came from a journal row; null for an in-session envelope. */
+    readonly episodeId: string | null;
+}
+
+/** Report the ignored blockers in a batch of returns held in memory. */
+export function findIgnoredBlockers(
+    envelopes: readonly Pick<OutcomeEnvelope, 'state' | 'suggestion' | 'acknowledgment'>[],
+): IgnoredBlockerFinding[] {
+    return envelopes
+        .filter((e) => isIgnoredBlocker(e))
+        .map((e) => ({ state: e.state, suggestion: e.suggestion, episodeId: null }));
+}
+
+// ---------------------------------------------------------------------------
+// The journal join (Phase 3.2)
+// ---------------------------------------------------------------------------
+
+/**
+ * One journal row, as far as THIS question needs it.
+ *
+ * Deliberately a structural type over four field names rather than an import
+ * of the journal module's own row type. The journal is written on a sibling
+ * track; coupling this predicate to its internal API would make the answer to
+ * "was this blocker ignored" un-testable until that module lands, and would
+ * couple two things whose only real contract is the four names below.
+ *
+ * The contract this join depends on, and nothing else:
+ *
+ * | field          | type                          | source                                   |
+ * |----------------|-------------------------------|------------------------------------------|
+ * | `episode_id`   | `string`                      | the episode spine (Phase 2.1)            |
+ * | `state`        | `TerminalState`               | reused verbatim from `outcome_envelope`  |
+ * | `consumption`  | `ConsumptionState` \| `null`  | this phase's field set (Phase 3.1)       |
+ * | `suggestion`   | `string`                      | the envelope's next action               |
+ *
+ * `consumption` is NULL — not absent — in the journal, because a SQL column
+ * has no third state. {@link rowIsIgnoredBlocker} maps that null onto the
+ * envelope's absent case, and that mapping is the whole of the impedance
+ * between the two representations.
+ */
+export interface JournalConsumptionRow {
+    readonly episode_id: string;
+    readonly state: TerminalState;
+    readonly consumption: ConsumptionState | null;
+    readonly suggestion: string;
+}
+
+/**
+ * The join, as SQL, for the journal's own reader to run once the table exists.
+ *
+ * Kept beside the predicate rather than in the journal module so the two
+ * cannot drift: if this string and {@link rowIsIgnoredBlocker} ever disagree,
+ * the disagreement is visible in one file. It is a documented query shape, not
+ * a live query — nothing in this module opens a database.
+ */
+export const IGNORED_BLOCKER_QUERY = `
+SELECT episode_id, state, suggestion
+FROM journal_events
+WHERE state IN ('blocked', 'approval-required', 'exhausted', 'stagnated')
+  AND consumption IS NULL
+ORDER BY episode_id
+`.trim();
+
+/**
+ * The row-level twin of {@link isIgnoredBlocker}, expressed THROUGH it so the
+ * two cannot answer the same question differently.
+ */
+export function rowIsIgnoredBlocker(row: JournalConsumptionRow): boolean {
+    return isIgnoredBlocker({
+        state: row.state,
+        ...(row.consumption === null ? {} : { acknowledgment: acknowledgmentOfRow(row.consumption) }),
+    });
+}
+
+/**
+ * Rehydrate a row's `consumption` column into an acknowledgment.
+ *
+ * The reason is not carried on this projection — the detector never reads it,
+ * and inventing one here would put a fabricated string where a real reason
+ * belongs. `rejected-with-reason` therefore gets a locator instead of prose.
+ */
+function acknowledgmentOfRow(consumption: ConsumptionState): NonNullable<OutcomeEnvelope['acknowledgment']> {
+    return consumption === 'rejected-with-reason'
+        ? { consumption, reason: '(recorded in the journal row)' }
+        : { consumption };
+}
+
+/** Report the ignored blockers in a set of journal rows. */
+export function findIgnoredBlockersInJournal(
+    rows: readonly JournalConsumptionRow[],
+): IgnoredBlockerFinding[] {
+    return rows
+        .filter((r) => rowIsIgnoredBlocker(r))
+        .map((r) => ({ state: r.state, suggestion: r.suggestion, episodeId: r.episode_id }));
+}