@event4u/agent-config 14.13.0 → 14.14.1

package/src/scripts/_lib/activation_receipt_producer.ts

@@ -0,0 +1,341 @@
+/**
+ * The activation-receipt producer — independent, append-only, zero model calls.
+ *
+ * `road-to-governed-evidence-production` step 1.1. The receipt SCHEMA
+ * ({@link ActivationReceipt}) and the CLASSIFIER ({@link classifyFailure}) both
+ * predate this module and are NOT reimplemented here; what was missing was a
+ * producer, so nothing ever wrote an `activation` object into an audit line and
+ * the receipt-bearing cascade stages had no subject.
+ *
+ * ## The claims this module is written against
+ *
+ * Stated once, in `docs/contracts/activation-receipt-trust-boundary.md`, and
+ * CITED here rather than restated — step 1.3's verify clause asks for exactly
+ * that split, and a second copy of a falsifiable claim is a second thing to
+ * keep true.
+ *
+ * | Claim | Where it binds in this file |
+ * |---|---|
+ * | TB-1 (no evaluation input decides a STATE) | the import list: no cascade, record, vector or verdict module appears |
+ * | TB-2 (an unobserved rung is absent) | {@link buildActivationReceipt} writes only the rungs it was given |
+ * | TB-3 (every state names an admitted source) | {@link EVIDENCE_SOURCES} + the refusal in {@link buildActivationReceipt} |
+ * | TB-4 (append, never rewrite) | {@link appendActivationLine} opens with `appendFileSync` and mints a fresh `id` |
+ * | EC-1 (zero model calls) | no transport import, no spawn, no key read — asserted by this module's test |
+ * | EC-3 (a missing observation is never bought) | {@link observeProjection} returns absence and does not retry |
+ *
+ * ## What is observable today, and what is not
+ *
+ * Three sources are admitted and all three ship an observer. `adhered` has no
+ * admitted source, so this producer CANNOT emit that rung and a real receipt
+ * reads `unknown` there. That is a coverage fact recorded rather than papered
+ * over: admitting a fourth source with no observer behind it would describe a
+ * capability that does not exist, which is the "population of zero" failure the
+ * roadmap already flags elsewhere.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    LADDER_RUNGS,
+    type ActivationReceipt,
+    type LadderRung,
+    type PrecedenceReason,
+    type RungState,
+} from './activation_ladder.js';
+import type { NoFreeForm } from './runtime_journal.js';
+import { type PrivacyClass } from './privacy_class.js';
+
+type Assert<T extends true> = T;
+
+/**
+ * The closed set of evidence sources a rung state may come from (TB-3).
+ *
+ * Each entry names a surface this producer can read without consulting the
+ * evaluation side. A source may not be added without an observer: the set
+ * describes what can be observed, never what one would like to observe.
+ *
+ * - `source-tree` — the authored artefact exists under `src/`, so it can match
+ *   at all. Reads the `eligible` rung.
+ * - `discovery-manifest` — the built manifest names the artefact for the active
+ *   install, i.e. the selector kept it. Reads the `selected` rung.
+ * - `host-projection` — a host tree carries a file for the artefact. Reads the
+ *   `projected` rung.
+ */
+export const EVIDENCE_SOURCES = ['source-tree', 'discovery-manifest', 'host-projection'] as const;
+export type EvidenceSource = (typeof EVIDENCE_SOURCES)[number];
+
+/** The rung each admitted source is allowed to speak about. One source, one rung. */
+export const SOURCE_RUNG: Readonly<Record<EvidenceSource, LadderRung>> = {
+    'source-tree': 'eligible',
+    'discovery-manifest': 'selected',
+    'host-projection': 'projected',
+};
+
+/** Rungs no admitted source covers today. Present so the gap is enumerable. */
+export const UNOBSERVED_RUNGS: readonly LadderRung[] = LADDER_RUNGS.filter(
+    (r) => !Object.values(SOURCE_RUNG).includes(r),
+);
+
+/**
+ * One observation. `state` is the evidence; `evidence_source` is where it came
+ * from.
+ *
+ * The field is `evidence_source` and not `source` on purpose: `source` is a
+ * member of `FREE_FORM_KEYS`, so a field of that name would make the privacy
+ * assertion at the bottom of this file `Assert<false>` and stop the build. The
+ * rename is the cheap half of keeping this input type incapable of carrying
+ * content.
+ */
+export interface RungObservation {
+    readonly rung: LadderRung;
+    readonly state: Exclude<RungState, 'unknown'>;
+    readonly evidence_source: EvidenceSource;
+}
+
+export interface ReceiptBuild {
+    readonly receipt: ActivationReceipt | null;
+    readonly errors: readonly string[];
+}
+
+/**
+ * Build a receipt from observations.
+ *
+ * TB-2 in one line: the output's `rungs` map has exactly the keys the caller
+ * observed. Nothing is defaulted, nothing is filled in, and a rung nobody looked
+ * at is absent — which `rungState` reads as `unknown` and `ladderRate` keeps out
+ * of its denominator.
+ *
+ * TB-3 in the refusals: an unadmitted source, or an admitted source speaking
+ * about a rung that is not its own, is an ERROR and yields no receipt. It is
+ * not a warning and it is not silently dropped, because a receipt missing a rung
+ * is indistinguishable from a receipt whose rung was refused, and only one of
+ * those is honest.
+ */
+export function buildActivationReceipt(
+    artefact: string,
+    observations: readonly RungObservation[],
+    reason?: PrecedenceReason,
+): ReceiptBuild {
+    const errors: string[] = [];
+    if (!artefact) errors.push('artefact id is required');
+
+    const rungs: Partial<Record<LadderRung, RungState>> = {};
+    for (const o of observations) {
+        if (!(EVIDENCE_SOURCES as readonly string[]).includes(o.evidence_source)) {
+            errors.push(`evidence_source '${o.evidence_source}' is not admitted (TB-3)`);
+            continue;
+        }
+        if (SOURCE_RUNG[o.evidence_source] !== o.rung) {
+            errors.push(
+                `evidence_source '${o.evidence_source}' may only observe rung ` +
+                    `'${SOURCE_RUNG[o.evidence_source]}', not '${o.rung}' (TB-3)`,
+            );
+            continue;
+        }
+        if (rungs[o.rung] !== undefined && rungs[o.rung] !== o.state) {
+            errors.push(`rung '${o.rung}' observed twice with conflicting states`);
+            continue;
+        }
+        rungs[o.rung] = o.state;
+    }
+    if (errors.length > 0) return { receipt: null, errors };
+
+    const receipt: ActivationReceipt = reason === undefined
+        ? { artefact, rungs }
+        : { artefact, rungs, reason };
+    return { receipt, errors: [] };
+}
+
+// --- observers ---------------------------------------------------------------
+
+/**
+ * Observe the `projected` rung: does a host tree carry a file for this artefact?
+ *
+ * EC-3 is the reason this returns `undefined` rather than probing further when
+ * the host root itself is missing. A host tree that does not exist is not
+ * evidence that the artefact was not projected into it — it is the absence of a
+ * place to look, and the honest output of a missing observation is nothing at
+ * all. Escalating from "read a path" to "go find the tree" is the unbounded-cost
+ * mistake EC-3 names, and it is the one a reader would forgive.
+ */
+export function observeProjection(
+    hostRoot: string,
+    artefactRelPath: string,
+): RungObservation | undefined {
+    if (!existsQuiet(hostRoot)) return undefined;
+    return {
+        rung: 'projected',
+        state: existsQuiet(path.join(hostRoot, artefactRelPath)) ? 'reached' : 'not-reached',
+        evidence_source: 'host-projection',
+    };
+}
+
+/**
+ * Observe the `eligible` rung: is the artefact authored in the source tree?
+ *
+ * Same absence rule as {@link observeProjection}: an unreadable source root
+ * yields no observation rather than a negative one.
+ */
+export function observeSourceTree(
+    sourceRoot: string,
+    artefactRelPath: string,
+): RungObservation | undefined {
+    if (!existsQuiet(sourceRoot)) return undefined;
+    return {
+        rung: 'eligible',
+        state: existsQuiet(path.join(sourceRoot, artefactRelPath)) ? 'reached' : 'not-reached',
+        evidence_source: 'source-tree',
+    };
+}
+
+/**
+ * Observe the `selected` rung from an already-loaded discovery-manifest id set.
+ *
+ * Takes the id set rather than a path: loading and parsing the manifest is the
+ * caller's, so this stays a pure predicate and EC-1's "no I/O beyond a read"
+ * holds trivially for it. An EMPTY set is treated as no manifest — not as a
+ * manifest that selected nothing — because those are different observations and
+ * folding them is exactly TB-2's failure.
+ */
+export function observeSelection(
+    selectedIds: ReadonlySet<string>,
+    artefactId: string,
+): RungObservation | undefined {
+    if (selectedIds.size === 0) return undefined;
+    return {
+        rung: 'selected',
+        state: selectedIds.has(artefactId) ? 'reached' : 'not-reached',
+        evidence_source: 'discovery-manifest',
+    };
+}
+
+function existsQuiet(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// --- the audit line ----------------------------------------------------------
+
+/** What THIS producer's lines carry: an artefact id, enums, and counts. */
+const PRODUCER_PRIVACY_CLASS: PrivacyClass = 'ids-only';
+
+export interface ActivationLineInput {
+    /** The artefact the receipt is about. An id, never a path. */
+    artefact: string;
+    /** The rungs actually observed. Absent rungs stay absent (TB-2). */
+    rungs: Readonly<Partial<Record<LadderRung, RungState>>>;
+    /**
+     * The precedence reason, when there is one.
+     *
+     * Named `precedence_reason` and NOT `reason`, which is a `FREE_FORM_KEYS`
+     * member: a field called `reason` on this type makes the assertion at the
+     * bottom of this file `Assert<false>` and stops the build, even though the
+     * value it would hold is a closed six-value enum. The emitted JSON key is
+     * still `reason`, because that is `ActivationReceipt`'s field name and the
+     * ladder module owns the receipt shape. The rename buys the compile-time
+     * floor at the cost of one line of mapping, which is the right trade: a
+     * guard that only rejects genuinely dangerous names is a guard someone has
+     * to keep tuning.
+     */
+    precedence_reason?: PrecedenceReason | undefined;
+    /** ISO-8601 UTC; the caller supplies it so this stays pure. */
+    ts: string;
+    /** ULID, UUID or content hash; the caller supplies it. */
+    id: string;
+    work_id?: string | undefined;
+}
+
+export interface BuiltActivationLine {
+    line: Record<string, unknown> | null;
+    errors: string[];
+}
+
+/**
+ * Build ONE audit-log-v1 line carrying an `activation` object.
+ *
+ * Deliberately the same envelope as `_lib/review_skipped_record.ts` — same
+ * mandatory fields, same `{line, errors}` contract, same refusal to return a
+ * half-built line. `skills_applied` is omitted for the same reason it is there:
+ * this producer has no skill observation to offer, and `[]` would assert one.
+ */
+export function buildActivationLine(input: ActivationLineInput): BuiltActivationLine {
+    const errors: string[] = [];
+    if (!input.artefact) errors.push('artefact is required');
+    if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
+    if (!input.id) errors.push('id (ULID, UUID, or content hash) is required');
+    const observed = Object.keys(input.rungs);
+    if (observed.length === 0) {
+        // A receipt that observed nothing is not a receipt. Writing one would
+        // add a line to an append-only ledger that carries no evidence and
+        // still counts as a record — the shape a later reader mistakes for
+        // coverage.
+        errors.push('a receipt must carry at least one observed rung');
+    }
+    for (const r of observed) {
+        if (!(LADDER_RUNGS as readonly string[]).includes(r)) {
+            errors.push(`'${r}' is not a ladder rung`);
+        }
+    }
+    if (errors.length) return { line: null, errors };
+
+    const activation: Record<string, unknown> = { artefact: input.artefact, rungs: { ...input.rungs } };
+    if (input.precedence_reason !== undefined) activation['reason'] = input.precedence_reason;
+
+    const line: Record<string, unknown> = {
+        schema_version: 1,
+        id: input.id,
+        ts: input.ts,
+        work_id: input.work_id ?? `activation-${input.ts}`,
+        phase: 'report',
+        outcome: 'success',
+        confidence_band: 'high',
+        risk_class: 'low',
+        memory: { asks: 0, hits: 0 },
+        verify: { claims: 0, first_try_passes: 0 },
+        rules_applied: [],
+        privacy_class: PRODUCER_PRIVACY_CLASS,
+        persona: null,
+        input_kind: 'prompt',
+        type: 'note',
+        activation,
+    };
+    return { line, errors: [] };
+}
+
+/**
+ * Append ONE line to the monthly audit log (TB-4).
+ *
+ * `appendFileSync` and nothing else: no read-modify-write, no truncation, no
+ * seek. Returns the file it wrote so a caller can assert the write happened
+ * rather than trusting that it did.
+ */
+export function appendActivationLine(
+    workspaceRoot: string,
+    line: Record<string, unknown>,
+    ts: string,
+): string {
+    const dir = path.join(workspaceRoot, 'agents', 'runtime', 'state', 'audit');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${ts.slice(0, 7)}.jsonl`);
+    fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
+    return file;
+}
+
+/**
+ * The privacy floor, by construction, on this producer's input type.
+ *
+ * Same mechanism as the two producers `docs/contracts/audit-log-v1.md`
+ * § Privacy floor already names. Adding a `path`, `detail`, `reason_text` or
+ * any other `FREE_FORM_KEYS` member below makes this `Assert<false>` and stops
+ * the build. `reason` is one of them, which is why the precedence field is
+ * called `precedence_reason` here and mapped to `reason` on the way out — see
+ * the field's own note.
+ */
+type _ActivationLineInputCarriesNoFreeFormField = Assert<
+    [NoFreeForm<ActivationLineInput>] extends [never] ? false : true
+>;

package/src/scripts/_lib/adr_frontmatter.ts

@@ -308,6 +308,32 @@ export type EvidenceStrength = (typeof EVIDENCE_STRENGTHS)[number];
 
 export const DISCOVERY_STATES = ['complete', 'incomplete'] as const;
 export const AUTHORITY_BASES = ['evidence', 'owner_intent'] as const;
+export type AuthorityBasis = (typeof AUTHORITY_BASES)[number];
+
+/**
+ * Reopen-authority vocabulary (`adr-layout.md` § Reopen authority).
+ *
+ * Moved here from `check_adr_frontmatter.ts` on 2026-08-31 so the ADR gate and
+ * `road-to-harness-promotion-bridge` step 7.2 read ONE list. 7.2's whole
+ * requirement is "route through the existing gate, not a second governance
+ * system"; importing the validator's private constant was not available, and
+ * copying it would have created the second system the step forbids.
+ *
+ * Both fields stay OPTIONAL at the ADR reader — an absent `reopen_policy`
+ * resolves to `unclassified`, never to `owner`.
+ */
+export const REOPEN_POLICIES = ['directional', 'owner', 'unclassified'] as const;
+export type ReopenPolicy = (typeof REOPEN_POLICIES)[number];
+
+export const PROTECTED_DIMENSIONS = [
+    'purpose',
+    'security_floor',
+    'privacy_floor',
+    'external_commitment',
+    'governance',
+    'none',
+] as const;
+export type ProtectedDimension = (typeof PROTECTED_DIMENSIONS)[number];
 
 export interface AdrProvenance {
     kind: string | null;

package/src/scripts/_lib/branch_convergence.ts

@@ -0,0 +1,186 @@
+/**
+ * Per-target branch-convergence policy — does the DEFAULT branch belong in the
+ * integration set when a PR targets something else?
+ *
+ * Decided by AI council on 2026-09-03 (`anthropic/claude-sonnet-4-5` +
+ * `openai/codex-default`) for the `cascade-default-inclusion-policy` blocker of
+ * `road-to-cascading-base-integration`. Both seats independently rejected the
+ * two offered answers — always-include, and include-past-a-commit-distance —
+ * and named the same third one: an explicit per-target policy read from
+ * repository intent. A commit-distance threshold was refused by both as an
+ * unmeasured constant.
+ *
+ * The load-bearing property is WHERE the policy is read from, and both seats
+ * called it non-negotiable: **the resolved PR target commit SHA, and nothing
+ * else.** Reading it from the PR head, the checkout, or an unpinned branch name
+ * lets a reviewed change edit its own acceptance criteria — the confused-deputy
+ * bypass. One seat: *"I would block any implementation reading policy from PR
+ * head, checkout state, or unpinned branch name."* So this module takes a
+ * `targetSha` it never resolves itself and a reader that can only answer at a
+ * SHA; there is deliberately no filesystem access anywhere in it.
+ *
+ * ── Where the policy file lives, and why it is NOT `.agent-settings.yml` ──
+ *
+ * The council's specification named `.agent-settings.yml`, section
+ * `branchConvergence`, on the premise that it is a committed file. In this
+ * repository, and in every consumer this package installs into, it is not:
+ * `.gitignore:317` ignores it here, and `src/config/gitignore-block.txt:56`
+ * writes that same ignore into every consumer's managed block. `git show
+ * <sha>:.agent-settings.yml` therefore returns nothing at every SHA in every
+ * repository this ships to, which would make the policy permanently unreadable
+ * and the feature dead on arrival.
+ *
+ * A SHA-pinned read requires a TRACKED file. The architecture the council
+ * specified is kept byte for byte — same section name, same shape, same
+ * exclusive read from the target SHA — and only the path moves, to a tracked
+ * repo-root file. If `.agent-settings.yml` ever becomes tracked, the
+ * `branchConvergence:` section moves across unchanged.
+ *
+ * Deferred by explicit council instruction and not to be added without
+ * reopening that decision: globs, pattern precedence, inheritance, configurable
+ * reason strings, and any repository-wide fallback policy.
+ */
+import { parse as parseYaml } from 'yaml';
+
+/** The tracked, SHA-readable file the policy is read from. */
+export const POLICY_PATH = '.branch-convergence.yml';
+
+/** The only two answers a target may give. Closed by council instruction. */
+export type DefaultBranchPolicy = 'include' | 'exclude';
+
+export interface BranchConvergenceTarget {
+    readonly defaultBranch: DefaultBranchPolicy;
+}
+
+export interface BranchConvergencePolicy {
+    readonly enabled: boolean;
+    /** Keyed by EXACT target branch name (`release/1.x`), never a pattern. */
+    readonly targets: Readonly<Record<string, BranchConvergenceTarget>>;
+}
+
+/**
+ * Read one path at one commit. Returns `null` when the path does not exist at
+ * that commit — which is a real answer, not an error.
+ *
+ * The signature takes the SHA FIRST and offers no way to ask for the working
+ * tree. That is the trust boundary expressed in a type: a caller cannot
+ * accidentally read the PR head, because there is no argument for it.
+ */
+export type ShaFileReader = (sha: string, repoPath: string) => string | null;
+
+/** The target is not the default branch and no exact entry names it. */
+export class MissingBranchConvergencePolicy extends Error {
+    readonly target: string;
+    constructor(target: string) {
+        super(`MissingBranchConvergencePolicy(target="${target}")`);
+        this.name = 'MissingBranchConvergencePolicy';
+        this.target = target;
+    }
+}
+
+/** The policy exists at the target SHA but does not validate. */
+export class InvalidBranchConvergencePolicy extends Error {
+    constructor(detail: string) {
+        super(`InvalidBranchConvergencePolicy: ${detail}`);
+        this.name = 'InvalidBranchConvergencePolicy';
+    }
+}
+
+/** The PR target names no commit the server will report. Fails closed. */
+export class UnresolvableTargetSha extends Error {
+    readonly target: string;
+    constructor(target: string) {
+        super(`UnresolvableTargetSha(target="${target}")`);
+        this.name = 'UnresolvableTargetSha';
+        this.target = target;
+    }
+}
+
+const TARGET_KEYS = new Set(['defaultBranch']);
+const ROOT_KEYS = new Set(['enabled', 'targets']);
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse and validate the `branchConvergence` section of a policy document.
+ *
+ * Exported separately from the SHA read so the VALIDATION is testable without a
+ * git object, for the same reason `classifyConflicts` is pure in
+ * `sync_pr_branch.ts`: the rejection of a malformed policy is the useful part,
+ * and a validator only reachable through a git call is a validator nobody
+ * covers.
+ *
+ * Duplicate keys are rejected by the YAML parser itself (`uniqueKeys` is on by
+ * default in `yaml` v2), so a target named twice is a parse failure rather than
+ * a silent last-wins.
+ */
+export function parseBranchConvergencePolicy(text: string): BranchConvergencePolicy | null {
+    let doc: unknown;
+    try {
+        doc = parseYaml(text);
+    } catch (exc) {
+        throw new InvalidBranchConvergencePolicy(exc instanceof Error ? exc.message : String(exc));
+    }
+    if (!isPlainObject(doc)) {
+        return null;
+    }
+    const section = doc['branchConvergence'];
+    if (section === undefined) {
+        return null;
+    }
+    if (!isPlainObject(section)) {
+        throw new InvalidBranchConvergencePolicy('`branchConvergence` is not a mapping');
+    }
+    for (const k of Object.keys(section)) {
+        if (!ROOT_KEYS.has(k)) {
+            throw new InvalidBranchConvergencePolicy(`unknown field \`branchConvergence.${k}\``);
+        }
+    }
+    const enabled = section['enabled'];
+    if (typeof enabled !== 'boolean') {
+        throw new InvalidBranchConvergencePolicy('`enabled` must be true or false');
+    }
+    const rawTargets = section['targets'] ?? {};
+    if (!isPlainObject(rawTargets)) {
+        throw new InvalidBranchConvergencePolicy('`targets` must be a mapping');
+    }
+    const targets: Record<string, BranchConvergenceTarget> = {};
+    for (const [name, entry] of Object.entries(rawTargets)) {
+        if (!isPlainObject(entry)) {
+            throw new InvalidBranchConvergencePolicy(`\`targets.${name}\` is not a mapping`);
+        }
+        for (const k of Object.keys(entry)) {
+            if (!TARGET_KEYS.has(k)) {
+                throw new InvalidBranchConvergencePolicy(`unknown field \`targets.${name}.${k}\``);
+            }
+        }
+        const v = entry['defaultBranch'];
+        if (v !== 'include' && v !== 'exclude') {
+            throw new InvalidBranchConvergencePolicy(
+                `\`targets.${name}.defaultBranch\` must be include or exclude, got ${JSON.stringify(v)}`,
+            );
+        }
+        targets[name] = { defaultBranch: v };
+    }
+    return { enabled, targets };
+}
+
+/**
+ * The policy as the PR TARGET carries it, at the target's own commit.
+ *
+ * `null` means the file does not exist at that commit. That is not an error
+ * here — it becomes `MissingBranchConvergencePolicy` one layer up, and only for
+ * a target that actually needs an entry.
+ */
+export function loadPolicyAtSha(targetSha: string, read: ShaFileReader): BranchConvergencePolicy | null {
+    if (!/^[0-9a-f]{7,40}$/.test(targetSha)) {
+        throw new InvalidBranchConvergencePolicy(`\`targetSha\` is not a commit id: ${JSON.stringify(targetSha)}`);
+    }
+    const text = read(targetSha, POLICY_PATH);
+    if (text === null) {
+        return null;
+    }
+    return parseBranchConvergencePolicy(text);
+}