@event4u/agent-config 14.13.0 → 14.14.0

package/src/scripts/activation_receipt.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env tsx
+/**
+ * `activation_receipt` — observe how far a shipped artefact climbed the
+ * activation ladder, and append the receipt to the audit ledger.
+ *
+ * `road-to-governed-evidence-production` step 1.1's PRODUCTION CALLER. The
+ * producer library (`_lib/activation_receipt_producer.ts`) holds the discipline;
+ * this file holds the three real observations and the write. It exists because
+ * a library nothing calls has no coverage — the same defect the roadmap kept
+ * open on `assertCheapestFirst`. **Corrected 2026-09-01:** that one is now half
+ * closed. `assertCheapestFirst` has two production callers in
+ * `_lib/llm_candidate_proposer.ts` (`:417`, `:446`), so it no longer polices a
+ * population of zero; what it still does not police is a SPENT population,
+ * which is what AC-3 stays open on.
+ *
+ * ## What it observes, and from where
+ *
+ * | Rung | Source | What is read |
+ * |---|---|---|
+ * | `eligible`  | `source-tree`        | the authored artefact under `src/` |
+ * | `selected`  | `discovery-manifest` | `dist/discovery/discovery-manifest.json`, `install.default` |
+ * | `projected` | `host-projection`    | the host tree under `.claude/` |
+ *
+ * `delivered`, `visible` and `adhered` have no admitted source and are therefore
+ * ABSENT from every receipt this writes — which the ladder reads as `unknown`
+ * and keeps out of every rate's denominator. That is the honest state of
+ * coverage today, not a placeholder to be filled with a guess.
+ *
+ * ## Costs and boundaries
+ *
+ * Zero model calls, no network, no subprocess: three `statSync` calls and one
+ * JSON read. Admissible under the `metered-backend-park` blocker, which forbids
+ * a live model harness rather than a filesystem read. Claims:
+ * `docs/contracts/activation-receipt-trust-boundary.md`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+import {
+    appendActivationLine,
+    buildActivationLine,
+    buildActivationReceipt,
+    observeProjection,
+    observeSelection,
+    observeSourceTree,
+    type RungObservation,
+} from './_lib/activation_receipt_producer.js';
+import { LADDER_RUNGS, firstStall, type ActivationReceipt } from './_lib/activation_ladder.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const EXIT_OK = 0;
+export const EXIT_USAGE = 2;
+
+const USAGE = `usage: activation_receipt --rule <id> | --skill <id> [options]
+
+  --rule ID         a rule artefact, e.g. commit-policy
+  --skill ID        a skill artefact, e.g. code-review
+  --host DIR        host projection root (default: .claude)
+  --root DIR        repository root (default: this checkout)
+  --dry-run         observe and print; do NOT append to the audit ledger
+
+Observes the eligible / selected / projected rungs and appends one
+audit-log-v1 line carrying an \`activation\` object. Zero model calls.
+`;
+
+/** Where the artefact lives, per kind, in each of the two trees. */
+interface ArtefactPaths {
+    readonly id: string;
+    readonly sourceRel: string;
+    readonly hostRel: string;
+}
+
+export function artefactPaths(kind: 'rule' | 'skill', id: string): ArtefactPaths {
+    return kind === 'rule'
+        ? { id, sourceRel: path.join('rules', `${id}.md`), hostRel: path.join('rules', `${id}.md`) }
+        : {
+              id,
+              sourceRel: path.join('skills', id, 'SKILL.md'),
+              hostRel: path.join('skills', id, 'SKILL.md'),
+          };
+}
+
+/**
+ * The ids the discovery manifest admits into the DEFAULT install.
+ *
+ * Returns an EMPTY set when the manifest is missing or unreadable, and
+ * `observeSelection` reads an empty set as "no manifest" rather than as "the
+ * manifest selected nothing" — the absent/negative split again, at the one place
+ * a build artefact can legitimately be missing.
+ */
+export function selectedIdsFromManifest(manifestPath: string): Set<string> {
+    let doc: unknown;
+    try {
+        doc = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+        return new Set();
+    }
+    const artefacts = (doc as { artefacts?: unknown }).artefacts;
+    if (!Array.isArray(artefacts)) return new Set();
+    const out = new Set<string>();
+    for (const a of artefacts) {
+        const rec = a as { path?: unknown; install?: { default?: unknown } };
+        if (typeof rec.path !== 'string') continue;
+        if (rec.install?.default !== true) continue;
+        out.add(artefactIdFromPath(rec.path));
+    }
+    return out;
+}
+
+/**
+ * The artefact id a manifest path names.
+ *
+ * `src/rules/commit-policy.md` -> `commit-policy`;
+ * `src/skills/code-review/SKILL.md` -> `code-review`. Any other path yields its
+ * basename without extension, which is not an id anything will match — a
+ * deliberate non-match rather than a guess.
+ */
+export function artefactIdFromPath(p: string): string {
+    const parts = p.split('/');
+    const last = parts[parts.length - 1] ?? '';
+    if (last === 'SKILL.md') return parts[parts.length - 2] ?? '';
+    return last.replace(/\.md$/, '');
+}
+
+export interface ObserveResult {
+    readonly receipt: ActivationReceipt | null;
+    readonly errors: readonly string[];
+    readonly observations: readonly RungObservation[];
+}
+
+/** The three observations, in ladder order. Pure apart from the reads. */
+export function observeArtefact(
+    root: string,
+    hostRoot: string,
+    kind: 'rule' | 'skill',
+    id: string,
+): ObserveResult {
+    const p = artefactPaths(kind, id);
+    const observations: RungObservation[] = [];
+    const eligible = observeSourceTree(path.join(root, 'src'), p.sourceRel);
+    if (eligible !== undefined) observations.push(eligible);
+    const selected = observeSelection(
+        selectedIdsFromManifest(path.join(root, 'dist', 'discovery', 'discovery-manifest.json')),
+        id,
+    );
+    if (selected !== undefined) observations.push(selected);
+    const projected = observeProjection(hostRoot, p.hostRel);
+    if (projected !== undefined) observations.push(projected);
+
+    const { receipt, errors } = buildActivationReceipt(id, observations);
+    return { receipt, errors, observations };
+}
+
+interface Flags {
+    kind?: 'rule' | 'skill';
+    id?: string;
+    host?: string;
+    root?: string;
+    dryRun: boolean;
+}
+
+function parse(argv: readonly string[]): Flags | string {
+    const f: Flags = { dryRun: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--dry-run') {
+            f.dryRun = true;
+            continue;
+        }
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith('--')) return `${a} requires a value`;
+        i += 1;
+        if (a === '--rule') {
+            f.kind = 'rule';
+            f.id = v;
+        } else if (a === '--skill') {
+            f.kind = 'skill';
+            f.id = v;
+        } else if (a === '--host') {
+            f.host = v;
+        } else if (a === '--root') {
+            f.root = v;
+        } else {
+            return `unknown option '${a}'`;
+        }
+    }
+    return f;
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+        process.stdout.write(USAGE);
+        return args.length === 0 ? EXIT_USAGE : EXIT_OK;
+    }
+    const parsed = parse(args);
+    if (typeof parsed === 'string') {
+        process.stderr.write(`activation_receipt: error: ${parsed}\n${USAGE}`);
+        return EXIT_USAGE;
+    }
+    if (parsed.kind === undefined || parsed.id === undefined || parsed.id === '') {
+        process.stderr.write(`activation_receipt: error: one of --rule or --skill is required\n${USAGE}`);
+        return EXIT_USAGE;
+    }
+    const root = parsed.root ?? REPO_ROOT;
+    const hostRoot = parsed.host ?? path.join(root, '.claude');
+
+    const { receipt, errors } = observeArtefact(root, hostRoot, parsed.kind, parsed.id);
+    if (receipt === null) {
+        for (const e of errors) process.stderr.write(`activation_receipt: refused — ${e}\n`);
+        return 1;
+    }
+
+    const stall = firstStall(receipt);
+    const observedCount = Object.keys(receipt.rungs).length;
+    process.stdout.write(
+        `activation_receipt · ${receipt.artefact} · observed ${observedCount}/${LADDER_RUNGS.length} rung(s) · ` +
+            (stall === null
+                ? 'climbed every observed rung · family=none\n'
+                : `stalled at ${stall.stage} · family=${stall.family}\n`),
+    );
+
+    const ts = new Date().toISOString();
+    const { line, errors: lineErrors } = buildActivationLine({
+        artefact: receipt.artefact,
+        rungs: receipt.rungs,
+        ts,
+        id: crypto.randomUUID(),
+    });
+    if (line === null) {
+        for (const e of lineErrors) process.stderr.write(`activation_receipt: refused — ${e}\n`);
+        return 1;
+    }
+    if (parsed.dryRun) {
+        process.stdout.write(`${JSON.stringify(line)}\n`);
+        return EXIT_OK;
+    }
+    const file = appendActivationLine(root, line, ts);
+    process.stdout.write(`activation_receipt · appended to ${path.relative(root, file)}\n`);
+    return EXIT_OK;
+}
+
+function _isCliEntry(): boolean {
+    try {
+        if (process.argv[1] === undefined) return false;
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/ai_council/cross_exam.ts

@@ -0,0 +1,128 @@
+/**
+ * Targeted cross-examination — step 8.1.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` step 8.1: *"Select
+ * a disputed finding, a conflicting pair, or a correct-looking minority claim,
+ * and ask focused rebuttal questions"*, verified by *"the cross-exam prompt
+ * names the exact disputed claim"*.
+ *
+ * ## "Names the exact claim" is a byte-level obligation, not a summary
+ *
+ * The failure this prevents is a composer that paraphrases: *"one reviewer
+ * questioned the index approach"* is a description of a dispute and gives the
+ * cross-examined model nothing to rebut. The prompt therefore carries the
+ * claim's **verbatim text**, unmodified and untruncated, and
+ * {@link crossExamNamesClaim} is the predicate that decides it — a substring
+ * check on the original string, which is the only form of "exact" that survives
+ * a later edit to the prompt's wording.
+ *
+ * ## The claim is untrusted, and is fenced
+ *
+ * A disputed claim is model output. It reaches the prompt through
+ * `wrapUntrustedBlocks` under a nonce, exactly as `build_peer_review_user_prompt`
+ * already does (`prompts.ts:932-942`) — a claim that could close its own fence
+ * could inject instructions into the cross-exam. Fencing does not modify the
+ * payload, which is what lets it coexist with the verbatim obligation above.
+ *
+ * ## Selection is deterministic and ordered, and the order is argued
+ *
+ * `conflicting-pair` outranks `disputed-finding` outranks `minority-claim`. A
+ * conflicting pair is the only kind where **at least one side is definitely
+ * wrong**, so the rebuttal has the highest information density; a lone disputed
+ * finding may resolve to "both are partly right"; a correct-looking minority
+ * claim is last because the majority may simply be right and the call buys the
+ * least. Ties break on the claim id, so selection is a pure function of input.
+ *
+ * Pure and offline: composes a prompt, never dispatches one.
+ */
+import { wrapUntrustedBlocks } from '../_lib/untrusted_content.js';
+
+/** What kind of thing is being cross-examined. Priority order, strongest first. */
+export const CROSS_EXAM_KINDS = ['conflicting-pair', 'disputed-finding', 'minority-claim'] as const;
+export type CrossExamKind = (typeof CROSS_EXAM_KINDS)[number];
+
+/** One candidate for cross-examination. */
+export interface DisputedClaim {
+    readonly id: string;
+    readonly kind: CrossExamKind;
+    /** Neutral label of whoever asserted it (`Response-A`), never a provider name. */
+    readonly assertedBy: string;
+    /** THE CLAIM, VERBATIM. Never summarised, never truncated. */
+    readonly claim: string;
+    /** Neutral label of whoever disputes it, when there is one. */
+    readonly disputedBy?: string;
+    /** The opposing text, verbatim, when there is one. */
+    readonly counterClaim?: string;
+}
+
+/**
+ * The focused questions. Fixed and shared across kinds on purpose: a per-kind
+ * question set is a second thing to keep in sync with the neutrality contract,
+ * and every question below is answerable about any of the three kinds.
+ */
+export const CROSS_EXAM_QUESTIONS: readonly string[] = [
+    'Is the claim above true as stated? Answer yes, no, or "true only under a condition" and name the condition.',
+    'What specific evidence would settle it? Name a file, a measurement, or a test — not a further opinion.',
+    'If it is false, what is the smallest correction that makes it true?',
+    'What would you have to believe for the opposing position to be correct?',
+];
+
+const PREAMBLE = `You are cross-examining ONE specific claim from a council deliberation.
+Do not review the artefact again, do not restate the debate, and do not
+comment on any claim other than the one quoted below. Your entire reply
+answers the numbered questions about that claim.`;
+
+/**
+ * Pick the claim to cross-examine, or `null`.
+ *
+ * Deterministic: kind priority first, then claim id.
+ */
+export function selectCrossExamTarget(candidates: readonly DisputedClaim[]): DisputedClaim | null {
+    if (candidates.length === 0) return null;
+    const ranked = [...candidates].sort((a, b) => {
+        const ka = CROSS_EXAM_KINDS.indexOf(a.kind);
+        const kb = CROSS_EXAM_KINDS.indexOf(b.kind);
+        return ka - kb || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    });
+    return ranked[0] as DisputedClaim;
+}
+
+/** Compose the cross-exam prompt. The claim text is carried verbatim. */
+export function buildCrossExamPrompt(target: DisputedClaim, opts: { readonly nonce?: string } = {}): string {
+    const blocks = [{ heading: `### The claim under examination (asserted by ${target.assertedBy})`, content: target.claim }];
+    if (target.counterClaim !== undefined) {
+        blocks.push({
+            heading: `### The opposing position (asserted by ${target.disputedBy ?? 'another reviewer'})`,
+            content: target.counterClaim,
+        });
+    }
+    const fenced = wrapUntrustedBlocks(blocks, opts.nonce === undefined ? {} : { nonce: opts.nonce });
+    const questions = CROSS_EXAM_QUESTIONS.map((q, i) => `${String(i + 1)}. ${q}`).join('\n');
+    return [
+        PREAMBLE,
+        '',
+        `Kind: ${target.kind} · claim id: ${target.id}`,
+        '',
+        fenced,
+        '',
+        '---',
+        '',
+        'Answer these, in order:',
+        '',
+        questions,
+        '',
+    ].join('\n');
+}
+
+/**
+ * Does this prompt name the exact claim?
+ *
+ * A plain substring check on the ORIGINAL string. Deliberately not a similarity
+ * score: "exact" that tolerates a threshold is not exact, and the paraphrase is
+ * the failure mode. Both sides of a pair must be present when a pair was given.
+ */
+export function crossExamNamesClaim(prompt: string, target: DisputedClaim): boolean {
+    if (!prompt.includes(target.claim)) return false;
+    if (target.counterClaim !== undefined && !prompt.includes(target.counterClaim)) return false;
+    return true;
+}

package/src/scripts/ai_council/explain_route.ts

@@ -0,0 +1,157 @@
+/**
+ * Free explain mode — step 12.2.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` step 12.2: *"Add
+ * a free explain mode: why task-side orchestration resolved to council, which
+ * topology would run, estimated spend and calls, evidence source — with no paid
+ * model call to explain routing"*, verified by *"explain mode issues zero
+ * provider calls"*.
+ *
+ * ## Free is the load-bearing word, and it is structural
+ *
+ * This module imports **no client, no transport and no dispatch**. It reads
+ * `explainLadder` (`_lib/judgment_ladder.ts:499`, itself regex-only) and
+ * `estimate_cost` (`pricing.ts:121`, arithmetic over a price table). There is
+ * nothing here to make a call WITH, which is a stronger guarantee than a
+ * documented promise not to — and the test asserts the import graph rather than
+ * trusting this paragraph.
+ *
+ * ## Three of the four fields are answerable today; one is not
+ *
+ *   1. **why it resolved to council** — `explainLadder`'s full per-rung trail,
+ *      including rungs that were evaluated-and-rejected with the detector's own
+ *      reason and rungs the short-circuit never reached. Free.
+ *   2. **which topology would run** — NOT ANSWERABLE. 7.2 is open, no selector
+ *      exists, and naming a topology here would be a guess dressed as an
+ *      explanation. Reported as {@link TOPOLOGY_UNAVAILABLE}, never omitted:
+ *      a field silently missing from an explanation reads as "not applicable".
+ *   3. **estimated spend and calls** — arithmetic over the configured members,
+ *      the round count and the price table, with the subscription-seat
+ *      distinction `pricing.ts` already draws: a non-billable seat contributes
+ *      calls but **zero** dollars, and the estimate says so per member rather
+ *      than folding it into a total.
+ *   4. **evidence source** — which artefact, if any, licenses the routing.
+ *      `none` is a legal and common value today and is rendered as such.
+ *
+ * Pure and offline.
+ */
+import { explainLadder } from '../_lib/judgment_ladder.js';
+import type { LadderExplanation, LadderInputs } from '../_lib/judgment_ladder.js';
+import { estimate_cost, estimate_input_tokens } from './pricing.js';
+import type { PriceTable } from './pricing.js';
+
+/** The exact string the topology field carries while no selector exists. */
+export const TOPOLOGY_UNAVAILABLE = 'unavailable — no topology selector exists (step 7.2 open)';
+
+/** One member, as the estimate needs it. */
+export interface EstimateMember {
+    readonly name: string;
+    readonly provider: string;
+    readonly model: string;
+    /**
+     * `false` for a vendor-official CLI seat running under the user's
+     * subscription auth — it contributes CALLS but no dollars, per
+     * `pricing.ts` § billable-aware aggregation.
+     */
+    readonly billable: boolean;
+}
+
+export interface SpendEstimate {
+    readonly calls: number;
+    readonly usd: number;
+    readonly perMember: readonly {
+        readonly name: string;
+        readonly calls: number;
+        readonly usd: number;
+        readonly billable: boolean;
+    }[];
+    /** Members whose calls are real but whose spend is zero. Named, not hidden. */
+    readonly nonBillableMembers: readonly string[];
+}
+
+export interface RouteExplanation {
+    /** Field 1 — free, from the regex-only resolver. */
+    readonly ladder: LadderExplanation;
+    /** Field 2 — always {@link TOPOLOGY_UNAVAILABLE} today. Present, never omitted. */
+    readonly topology: string;
+    /** Field 3 — arithmetic, no call. */
+    readonly spend: SpendEstimate;
+    /** Field 4 — the artefact licensing the route, or `'none'`. */
+    readonly evidenceSource: string;
+}
+
+/**
+ * Estimate calls and spend without issuing one.
+ *
+ * `calls` counts every member on every round; `usd` counts only the billable
+ * ones. Reporting a subscription seat's answer at API rates is the defect
+ * `pricing.ts` records finding on 2026-08-27, and this keeps the two figures
+ * separate rather than reproducing it.
+ */
+export function estimateSpend(
+    members: readonly EstimateMember[],
+    rounds: number,
+    questionText: string,
+    maxOutputTokens: number,
+    table: PriceTable,
+): SpendEstimate {
+    const inputTokens = estimate_input_tokens(questionText);
+    const perMember = members.map((m) => {
+        const calls = Math.max(0, rounds);
+        if (!m.billable) return { name: m.name, calls, usd: 0, billable: false };
+        const c = estimate_cost(m.provider, m.model, inputTokens, maxOutputTokens, table);
+        return { name: m.name, calls, usd: (c.input_usd + c.output_usd) * calls, billable: true };
+    });
+    return {
+        calls: perMember.reduce((a, m) => a + m.calls, 0),
+        usd: perMember.reduce((a, m) => a + m.usd, 0),
+        perMember,
+        nonBillableMembers: perMember.filter((m) => !m.billable).map((m) => m.name),
+    };
+}
+
+/** Build the whole explanation. No call is issued and none can be. */
+export function explainRoute(
+    ladderInputs: LadderInputs,
+    members: readonly EstimateMember[],
+    rounds: number,
+    questionText: string,
+    maxOutputTokens: number,
+    table: PriceTable,
+    evidenceSource: string = 'none',
+): RouteExplanation {
+    return {
+        ladder: explainLadder(ladderInputs),
+        topology: TOPOLOGY_UNAVAILABLE,
+        spend: estimateSpend(members, rounds, questionText, maxOutputTokens, table),
+        evidenceSource,
+    };
+}
+
+/** Human-readable rendering. Every one of the four fields appears, including the unavailable one. */
+export function renderRouteExplanation(e: RouteExplanation): string {
+    const lines = [
+        'council: explain (free — no provider call was issued)',
+        '',
+        `  resolution   rung ${String(e.ladder.result.rung)} / ${e.ladder.result.verdict}`,
+        `  because      ${e.ladder.result.reason}`,
+        '  ladder trail',
+    ];
+    for (const r of e.ladder.trail) {
+        lines.push(`    rung ${String(r.rung)} → ${r.resolves_to.padEnd(8)} ${r.status.padEnd(12)} ${r.reason}`);
+    }
+    if (e.ladder.no_spawn_reason !== undefined) lines.push(`  no spawn     ${e.ladder.no_spawn_reason}`);
+    lines.push(
+        '',
+        `  topology     ${e.topology}`,
+        `  estimated    ${String(e.spend.calls)} call(s), $${e.spend.usd.toFixed(4)}`,
+    );
+    for (const m of e.spend.perMember) {
+        lines.push(
+            `    ${m.name.padEnd(14)} ${String(m.calls)} call(s), $${m.usd.toFixed(4)}` +
+                (m.billable ? '' : '  (subscription seat — calls are real, spend is not)'),
+        );
+    }
+    lines.push(`  evidence     ${e.evidenceSource}`, '');
+    return lines.join('\n');
+}