@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/experience_card.ts

@@ -0,0 +1,272 @@
+/**
+ * Experience cards — the `kind: experience` variant of the knowledge card.
+ *
+ * **Where these live, and why it was a decision.** AI council 2026-08-30,
+ * anthropic + openai, 2/2 convergent: they live in `agents/knowledge/`
+ * alongside external-source cards, as a STRICT TAGGED UNION on a required
+ * `kind` field — never as one schema with conditional fields.
+ *
+ * The distinction the council insisted on is the whole design. Making the
+ * external card's checks (authoritative pointer, pointer resolution,
+ * git-ancestry across `source_version`s) *optional* would hide two contracts
+ * inside one nominal schema, which is the union-of-what-producers-send failure
+ * this repository refuses elsewhere. Making them **variant invariants** — they
+ * apply, in full, to `kind: external` and are not part of the `experience`
+ * variant at all — keeps one contract per variant and one directory.
+ *
+ * The reusable boundary the council left behind, recorded so the next proposal
+ * is measured against it rather than re-argued: *a new store is justified only
+ * when its records cannot share the existing carrier's identity, discovery path
+ * and consumer lifecycle — not merely because they have different provenance or
+ * validation rules.* Experience cards share all three, so they are a variant.
+ */
+
+/**
+ * How a card's statement was arrived at.
+ *
+ * The split is load-bearing rather than descriptive: `observed` and `derived`
+ * are FACTUAL — something happened, or follows from something that happened —
+ * while `inferred` and `hypothesized` are GENERATIVE. Only the factual pair may
+ * act as a hard filter; the generative pair may at most reduce ranking weight.
+ * Letting a hypothesis filter is how a guess becomes a rule without anyone
+ * deciding it should.
+ */
+export const EPISTEMIC_TYPES = ['observed', 'derived', 'inferred', 'hypothesized'] as const;
+export type EpistemicType = (typeof EPISTEMIC_TYPES)[number];
+
+/** Only a factual statement may exclude a candidate outright. */
+export function mayHardFilter(t: EpistemicType): boolean {
+    return t === 'observed' || t === 'derived';
+}
+
+/**
+ * The promotion ladder. A card starts at `session` and climbs one rung at a
+ * time; `repo` is the last rung reachable on the evidence that produced it.
+ */
+export const CARD_SCOPES = ['session', 'repo', 'workspace', 'organization', 'global'] as const;
+export type CardScope = (typeof CARD_SCOPES)[number];
+
+/** Where the evidence for a promotion came from. */
+export const EVIDENCE_POOLS = ['development', 'held-out', 'independent'] as const;
+export type EvidencePool = (typeof EVIDENCE_POOLS)[number];
+
+/**
+ * A card is admissible only from the mining gate or an explicit seed. Never
+ * invented, and never pre-seeded as a family of plausible-looking entries.
+ */
+export interface CardProvenance {
+    /**
+     * A pattern id from `extract_audit_patterns`, which mints a pattern only at
+     * count >= 2 across INDEPENDENT `work_id`s. One run repeating itself is not
+     * a pattern.
+     */
+    pattern_ref?: string;
+    /** An explicit `### SEED —` block a human wrote. */
+    seed_ref?: string;
+}
+
+export interface ExperienceCard {
+    kind: 'experience';
+    id: string;
+    scope: CardScope;
+    /** When this card applies. Id-shaped tokens, never prose. */
+    trigger_context: string[];
+    /** What to do. One compact statement. */
+    strategy: string;
+    /**
+     * What would show this card is wrong. REQUIRED, and the field that makes a
+     * card a claim rather than an opinion: a card with no falsifier can never
+     * be retired on evidence, only on taste.
+     */
+    falsifier: string;
+    confidence: 'low' | 'medium' | 'high';
+    /** Card ids this one contradicts. Recorded, never silently resolved. */
+    contradictions: string[];
+    /** Card ids this one replaces. */
+    supersedes: string[];
+    /**
+     * ISO date after which this card must be re-checked. REQUIRED: an
+     * unexpiring empirical claim outlives the conditions that produced it and
+     * nobody notices, because nothing ever asks.
+     */
+    expiry: string;
+    epistemic_type: EpistemicType;
+    provenance: CardProvenance;
+    /** Cases where the strategy failed. Narrows the card; never widens it. */
+    anti_patterns: string[];
+}
+
+export class CardContractError extends Error {}
+
+/** Admissible iff it carries a mining-gate pattern or a human seed. */
+export function isAdmissible(p: CardProvenance): boolean {
+    return (
+        (typeof p.pattern_ref === 'string' && p.pattern_ref.trim().length > 0) ||
+        (typeof p.seed_ref === 'string' && p.seed_ref.trim().length > 0)
+    );
+}
+
+/** Fields whose absence makes a card inadmissible, in the order a linter reports them. */
+export const REQUIRED_CARD_FIELDS = [
+    'id',
+    'scope',
+    'trigger_context',
+    'strategy',
+    'falsifier',
+    'confidence',
+    'contradictions',
+    'supersedes',
+    'expiry',
+    'epistemic_type',
+] as const;
+
+export interface CardFailure {
+    /** What went wrong, id-shaped. */
+    anti_pattern: string;
+    /**
+     * Present only when the failure is being used to argue the card applies
+     * MORE widely. That is the move this type exists to refuse.
+     */
+    widen_scope_to?: CardScope;
+}
+
+/**
+ * Fold a failure into a card.
+ *
+ * **A failure narrows; it never widens.** The temptation is real and specific:
+ * a card fails in a neighbouring context, and the natural-sounding repair is
+ * "so the card is really about the broader case". That reasoning turns every
+ * piece of disconfirming evidence into an expansion, which is the exact inverse
+ * of what evidence is for. A failure adds an anti-pattern and nothing else.
+ */
+export function applyFailure(card: ExperienceCard, failure: CardFailure): ExperienceCard {
+    if (failure.widen_scope_to !== undefined) {
+        throw new CardContractError(
+            `a failure may not widen scope (${card.scope} -> ${failure.widen_scope_to}). ` +
+                'A failure adds an anti-pattern; it never extends applicability. ' +
+                'Widening on disconfirming evidence is the inverse of what evidence is for.',
+        );
+    }
+    return { ...card, anti_patterns: [...card.anti_patterns, failure.anti_pattern] };
+}
+
+export interface PromotionEvidence {
+    pool: EvidencePool;
+}
+
+/**
+ * Promote one rung.
+ *
+ * Two refusals, and they answer the two ways a card gets over-promoted:
+ *
+ * 1. **One level at a time.** A two-level raise skips the rung where the card
+ *    would have been checked against a wider population.
+ * 2. **Past `repo` needs evidence the card did not produce.** The runs that
+ *    minted a card cannot also demonstrate it transfers — that is the same data
+ *    answering its own question. Above `repo`, the evidence must be held-out or
+ *    independent.
+ */
+export function promote(
+    card: ExperienceCard,
+    target: CardScope,
+    evidence: PromotionEvidence,
+): ExperienceCard {
+    const from = CARD_SCOPES.indexOf(card.scope);
+    const to = CARD_SCOPES.indexOf(target);
+    if (to - from !== 1) {
+        throw new CardContractError(
+            `promotion moves exactly one rung: ${card.scope} -> ${target} is ${to - from}. ` +
+                'A skipped rung is a population the card was never checked against.',
+        );
+    }
+    if (to > CARD_SCOPES.indexOf('repo') && evidence.pool === 'development') {
+        throw new CardContractError(
+            `raising past repo scope needs held-out or independent evidence; got '${evidence.pool}'. ` +
+                'The runs that produced a card cannot also show it transfers.',
+        );
+    }
+    return { ...card, scope: target };
+}
+
+// ---------------------------------------------------------------------------
+// Admission and duplicate checks — the linter's pure core
+// ---------------------------------------------------------------------------
+
+import { jaccardSimilarity } from './text_similarity.js';
+
+export interface CardViolation {
+    card_id: string;
+    code:
+        | 'not-admissible'
+        | 'missing-field'
+        | 'unknown-epistemic-type'
+        | 'unknown-scope'
+        | 'duplicates-rule';
+    detail: string;
+}
+
+/**
+ * Everything a card must satisfy to be admissible, in one pass.
+ *
+ * `rules` is a map of live rule id -> its text. Passed IN rather than read
+ * here: this stays pure so the duplicate threshold can be tested against
+ * synthetic text instead of against whatever the rule corpus happens to say
+ * today.
+ */
+export function checkCard(
+    card: Partial<ExperienceCard> & { id?: string },
+    rules: ReadonlyMap<string, string> = new Map(),
+    duplicateThreshold = DUPLICATE_THRESHOLD,
+): CardViolation[] {
+    const id = card.id ?? '<unnamed>';
+    const out: CardViolation[] = [];
+
+    for (const f of REQUIRED_CARD_FIELDS) {
+        const v = (card as Record<string, unknown>)[f];
+        const empty =
+            v === undefined ||
+            v === null ||
+            (typeof v === 'string' && v.trim().length === 0) ||
+            (Array.isArray(v) && f === 'trigger_context' && v.length === 0);
+        if (empty) out.push({ card_id: id, code: 'missing-field', detail: f });
+    }
+
+    if (card.epistemic_type !== undefined && !(EPISTEMIC_TYPES as readonly string[]).includes(card.epistemic_type)) {
+        out.push({ card_id: id, code: 'unknown-epistemic-type', detail: String(card.epistemic_type) });
+    }
+    if (card.scope !== undefined && !(CARD_SCOPES as readonly string[]).includes(card.scope)) {
+        out.push({ card_id: id, code: 'unknown-scope', detail: String(card.scope) });
+    }
+    if (card.provenance === undefined || !isAdmissible(card.provenance)) {
+        out.push({
+            card_id: id,
+            code: 'not-admissible',
+            detail: 'needs a pattern_ref from the mining gate or an explicit seed_ref — never invented',
+        });
+    }
+
+    // A card is not a rule: empirical, scoped and probabilistic versus
+    // normative. One that restates a live rule adds no knowledge and creates a
+    // second place the same instruction can drift.
+    const text = `${card.strategy ?? ''} ${(card.trigger_context ?? []).join(' ')}`.trim();
+    if (text.length > 0) {
+        for (const [ruleId, ruleText] of rules) {
+            if (jaccardSimilarity(text, ruleText) >= duplicateThreshold) {
+                out.push({
+                    card_id: id,
+                    code: 'duplicates-rule',
+                    detail: `restates the live rule '${ruleId}' — a card is not a rule`,
+                });
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Similarity at or above which a card is treated as restating a rule.
+ *
+ * Stated as a named constant rather than inlined so it is one number a reviewer
+ * can argue with, and so the tests exercise the same value the linter uses.
+ */
+export const DUPLICATE_THRESHOLD = 0.6;

package/src/scripts/_lib/experience_report.ts

@@ -0,0 +1,151 @@
+/**
+ * Per-asset effectiveness, aggregated over the audit stream. READ ONLY.
+ *
+ * The one rule that shapes every type here: **a missing signal counts as
+ * `unknown`, never as success.** An asset that appears in the stream and whose
+ * outcome cannot be classified contributes to `unknown` and to nothing else. It
+ * does not enter a win-rate numerator, and it does not enter the denominator
+ * either — because a rate computed over "everything we saw" silently answers a
+ * different question from a rate computed over "everything we could classify",
+ * and only the second one is about the asset.
+ *
+ * `win_rate` is therefore `null` — not `0` — when nothing classifiable was seen.
+ * Zero is a measurement meaning "it never worked"; null means "we do not know",
+ * and rendering the second as the first is the fabrication this module exists to
+ * prevent. A reader seeing `0.0` will act; a reader seeing `—` will ask.
+ *
+ * Nothing in any selection or routing path may import this module. That is step
+ * 6.3's constraint and it is checked by a test, not by convention.
+ */
+
+import { type BasisTag } from './evidence_basis.js';
+
+/** What kind of asset a row is about. */
+export type AssetKind = 'rule' | 'skill';
+
+export interface AssetRow {
+    kind: AssetKind;
+    id: string;
+    /** Outcomes classified as helpful. */
+    helpful: number;
+    /** Classified, and neither helpful nor harmful. */
+    neutral: number;
+    /** Classified as harmful. */
+    harmful: number;
+    /**
+     * Appearances that could not be classified. Its OWN share, reported
+     * alongside the rest and never folded into any of them.
+     */
+    unknown: number;
+    /** Consecutive most-recent helpful outcomes. */
+    streak: number;
+    /**
+     * `helpful / (helpful + neutral + harmful)`, or `null` when that
+     * denominator is zero. Never `0` in the no-data case.
+     */
+    win_rate: number | null;
+    /** How `win_rate` was arrived at. Every derived figure states its basis. */
+    win_rate_basis: BasisTag;
+}
+
+/** The audit-line shape this module reads. Deliberately narrow. */
+export interface AuditLineView {
+    outcome?: unknown;
+    rules_applied?: unknown;
+    skills_applied?: unknown;
+}
+
+/** Outcomes that count as helpful, and the ones that count against. */
+const HELPFUL = new Set(['success']);
+const HARMFUL = new Set(['error']);
+const NEUTRAL = new Set(['skipped', 'blocked']);
+
+interface Tally {
+    helpful: number;
+    neutral: number;
+    harmful: number;
+    unknown: number;
+    /** Most-recent-first classification history, for the streak. */
+    recent: ('helpful' | 'other' | 'unknown')[];
+}
+
+function emptyTally(): Tally {
+    return { helpful: 0, neutral: 0, harmful: 0, unknown: 0, recent: [] };
+}
+
+function classifyOutcome(outcome: unknown): 'helpful' | 'neutral' | 'harmful' | 'unknown' {
+    if (typeof outcome !== 'string') return 'unknown';
+    if (HELPFUL.has(outcome)) return 'helpful';
+    if (HARMFUL.has(outcome)) return 'harmful';
+    if (NEUTRAL.has(outcome)) return 'neutral';
+    return 'unknown';
+}
+
+function idsOf(v: unknown): string[] {
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : [];
+}
+
+/**
+ * Aggregate.
+ *
+ * The `skills_applied` half deserves a note, because it is where the
+ * absent-vs-empty distinction stops being philosophical. A line that OMITS
+ * `skills_applied` recorded nothing about skills, so it contributes no skill
+ * row at all — it is not evidence that no skill was applied. A line carrying
+ * `[]` recorded that none was applied, which is also no row, but for the
+ * opposite reason. Neither may invent an `unknown` against a skill nobody
+ * named; `unknown` is counted against an asset the line DID name and whose
+ * outcome could not be classified.
+ */
+export function aggregate(lines: readonly AuditLineView[]): AssetRow[] {
+    const tallies = new Map<string, { kind: AssetKind; id: string; t: Tally }>();
+
+    const bump = (kind: AssetKind, id: string, cls: ReturnType<typeof classifyOutcome>): void => {
+        const key = `${kind}:${id}`;
+        let entry = tallies.get(key);
+        if (entry === undefined) {
+            entry = { kind, id, t: emptyTally() };
+            tallies.set(key, entry);
+        }
+        entry.t[cls] += 1;
+        entry.t.recent.unshift(cls === 'helpful' ? 'helpful' : cls === 'unknown' ? 'unknown' : 'other');
+    };
+
+    for (const line of lines) {
+        const cls = classifyOutcome(line.outcome);
+        for (const id of idsOf(line.rules_applied)) bump('rule', id, cls);
+        for (const id of idsOf(line.skills_applied)) bump('skill', id, cls);
+    }
+
+    const rows: AssetRow[] = [];
+    for (const { kind, id, t } of tallies.values()) {
+        const classified = t.helpful + t.neutral + t.harmful;
+        // `null`, by construction, whenever nothing was classifiable. The
+        // ternary is the whole contract of this module.
+        const win_rate = classified === 0 ? null : t.helpful / classified;
+
+        let streak = 0;
+        for (const r of t.recent) {
+            if (r !== 'helpful') break;
+            streak += 1;
+        }
+
+        rows.push({
+            kind,
+            id,
+            helpful: t.helpful,
+            neutral: t.neutral,
+            harmful: t.harmful,
+            unknown: t.unknown,
+            streak,
+            win_rate,
+            // Not `measured`: the ratio is arithmetic over counted outcomes,
+            // never itself observed. The method travels with it so a reader can
+            // tell this apart from a figure derived some other way.
+            win_rate_basis: 'estimated:ratio-of-classified-audit-outcomes',
+        });
+    }
+
+    rows.sort((a, b) => (a.kind === b.kind ? a.id.localeCompare(b.id) : a.kind.localeCompare(b.kind)));
+    return rows;
+}

package/src/scripts/_lib/experiment_freeze.ts

@@ -0,0 +1,112 @@
+/**
+ * Freeze the five things a comparison must not change while it runs.
+ *
+ * A comparison whose evaluator, corpus, task definition, baseline or protected
+ * fixtures move mid-run has not compared two arms — it has compared two
+ * different experiments and reported the difference as an effect. The failure
+ * is silent by construction: every individual reading looks fine, and the
+ * corruption lives in the relationship between them.
+ *
+ * The design decision worth stating: `assertUnchanged` **throws**, and does not
+ * return a verdict. A verdict is a value a caller can log and step past, and a
+ * caller mid-comparison has every incentive to step past it — the run is already
+ * expensive and the drift usually looks small. An abort is the only shape that
+ * cannot be quietly absorbed, and "aborts the comparison rather than continuing
+ * it" is what the step asks for in those words.
+ *
+ * road-to-experience-loop-broadening step 9.5.
+ */
+
+import * as crypto from 'node:crypto';
+
+/**
+ * The five frozen elements.
+ *
+ * Every field is REQUIRED. An optional element is one a caller can omit and
+ * thereby freeze nothing, which is the failure mode a freeze exists to stop —
+ * so the type refuses a partial spec rather than hashing whatever it was given.
+ */
+export interface ExperimentSpec {
+    /** Identity of the evaluator: its id and version, never its output. */
+    evaluator: string;
+    /** Content hash or pinned id of the corpus partition. */
+    corpus: string;
+    /** The task definition the arms are scored against. */
+    task: string;
+    /** The baseline arm's identity. */
+    baseline: string;
+    /** Protected fixtures, order-insensitive. */
+    fixtures: readonly string[];
+}
+
+/** The five element names, so a caller can report WHICH one moved. */
+export const FROZEN_ELEMENTS = ['evaluator', 'corpus', 'task', 'baseline', 'fixtures'] as const;
+export type FrozenElement = (typeof FROZEN_ELEMENTS)[number];
+
+export class ExperimentDriftError extends Error {
+    constructor(
+        readonly changed: FrozenElement[],
+        readonly frozen: string,
+        readonly actual: string,
+    ) {
+        super(
+            `experiment drift: ${changed.join(', ')} changed mid-run. ` +
+                `Frozen ${frozen}, now ${actual}. The comparison is aborted rather than continued — ` +
+                'a run whose frozen set moved did not compare two arms, it compared two experiments.',
+        );
+        this.name = 'ExperimentDriftError';
+    }
+}
+
+function canonical(spec: ExperimentSpec): string {
+    // Fixtures are sorted: their ORDER is a property of how the caller happened
+    // to enumerate a directory, not of the experiment, and a freeze that broke
+    // on reordering would be abandoned the first time it fired spuriously.
+    return JSON.stringify({
+        evaluator: spec.evaluator,
+        corpus: spec.corpus,
+        task: spec.task,
+        baseline: spec.baseline,
+        fixtures: [...spec.fixtures].sort(),
+    });
+}
+
+/** The frozen digest. Record it with the run; it is what `assertUnchanged` compares against. */
+export function freeze(spec: ExperimentSpec): string {
+    return crypto.createHash('sha256').update(canonical(spec), 'utf-8').digest('hex').slice(0, 32);
+}
+
+/** Which of the five differ. Exported so a caller can report the cause without re-deriving it. */
+export function changedElements(a: ExperimentSpec, b: ExperimentSpec): FrozenElement[] {
+    const out: FrozenElement[] = [];
+    if (a.evaluator !== b.evaluator) out.push('evaluator');
+    if (a.corpus !== b.corpus) out.push('corpus');
+    if (a.task !== b.task) out.push('task');
+    if (a.baseline !== b.baseline) out.push('baseline');
+    if (JSON.stringify([...a.fixtures].sort()) !== JSON.stringify([...b.fixtures].sort())) {
+        out.push('fixtures');
+    }
+    return out;
+}
+
+/**
+ * Abort if the set moved.
+ *
+ * Takes the ORIGINAL spec as well as its digest so the error can name which
+ * element changed. A digest alone would abort correctly and tell the operator
+ * nothing about what to fix, and an abort nobody can act on gets suppressed.
+ */
+export function assertUnchanged(frozen: string, original: ExperimentSpec, now: ExperimentSpec): void {
+    const actual = freeze(now);
+    if (actual === frozen) return;
+    const changed = changedElements(original, now);
+    throw new ExperimentDriftError(
+        // A digest mismatch with no field difference means the ORIGINAL spec and
+        // the frozen digest disagree — the caller passed a spec that never
+        // produced that hash. That is a worse bug than drift, so it is named
+        // rather than reported as an empty change list.
+        changed.length > 0 ? changed : (['evaluator'] as FrozenElement[]),
+        frozen,
+        actual,
+    );
+}

package/src/scripts/_lib/generated_by.ts

@@ -0,0 +1,66 @@
+/**
+ * The attribution line a generated artifact carries.
+ *
+ * `road-to-consumer-repo-reality` Phase 1, step 1.4: "A generated file that
+ * names the script that wrote it becomes a lie the moment that script moves.
+ * Emit a stable, resolvable reference instead."
+ *
+ * IT ALREADY HAPPENED, which is why this module exists rather than a style
+ * note. Measured 2026-08-26 across `src/`, ten generated artifacts named their
+ * generator by literal path and **six of those paths did not resolve**:
+ *
+ *   scripts/audit_user_type_axis.py   scripts/adoption_report.py
+ *   scripts/skill_overlap.py          scripts/gen_discovery_baseline.py
+ *   scripts/generate_ownership_matrix.py
+ *   scripts/generate_pack_manifests.ts
+ *
+ * The first five were retired by the py2ts migration (ADR-200) and the sixth by
+ * the `scripts/` → `src/scripts/` move. Each artifact kept telling its reader to
+ * go look at a file that is not there — the same over-reporting failure Phase 1
+ * measures in consumer root instruction files, produced by this package's own
+ * generators.
+ *
+ * THE STABLE REFERENCE IS THE COMMAND, NOT THE PATH. A path is an
+ * implementation detail that a refactor moves; the command a human runs to
+ * regenerate is the thing that stays true, and it is also the only half of the
+ * attribution a reader can act on. Where no command exists, the generator's
+ * MODULE NAME is used — stable under a directory move, and greppable.
+ */
+
+/**
+ * `Generated by <ref>. Do not edit.` — with `ref` a command or a module name,
+ * never a path.
+ *
+ * @param ref     the regeneration command (`agent-config sync`, `task sync`) or
+ *                the generator's module name (`regenerate_index`). A value
+ *                containing a path separator is a bug this function refuses
+ *                rather than emits, because emitting it is exactly the defect.
+ * @param detail  optional trailing clause, e.g. a source description. No
+ *                timestamp: a regenerated timestamp makes every run a diff.
+ */
+export function generatedBy(ref: string, detail?: string): string {
+    if (ref.includes('/') || ref.includes('\\')) {
+        throw new Error(
+            `generatedBy: "${ref}" contains a path separator. The attribution must be a command or a ` +
+                'module name — a literal path becomes wrong the moment the file moves, which is the ' +
+                'defect this helper exists to prevent (road-to-consumer-repo-reality 1.4).',
+        );
+    }
+    const tail = detail === undefined || detail.trim() === '' ? '' : ` ${detail.trim()}`;
+    return `Generated by \`${ref}\`. Do not edit.${tail}`;
+}
+
+/** The same line as a markdown blockquote, the shape most emitters use. */
+export function generatedByQuote(ref: string, detail?: string): string {
+    return `> ${generatedBy(ref, detail)}`;
+}
+
+/** The same line as an italic footer, for artifacts that use one. */
+export function generatedByItalic(ref: string, detail?: string): string {
+    return `_${generatedBy(ref, detail)}_`;
+}
+
+/** The same line as a `#` comment, for YAML and INI-shaped output. */
+export function generatedByComment(ref: string, detail?: string): string {
+    return `# ${generatedBy(ref, detail)}`;
+}