@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/ai_council/jury_aggregate.ts

@@ -27,6 +27,7 @@
  * inferring it from a method name.
  */
 
+import { cohensKappa } from '../check_quality_regression.js';
 import {
     judgeBothOrders,
     positionConsistency,
@@ -45,7 +46,20 @@ export interface JuryScore {
 }
 
 /** Why a panel produced no aggregate. Each value is a REFUSAL, not an error. */
-export type JuryAbsentReason = 'no_scores' | 'single_family' | 'non_finite_score';
+export type JuryAbsentReason = 'no_scores' | 'single_family' | 'non_finite_score' | 'panel_over_cap';
+
+/**
+ * K10: past five judges the effective number of independent votes stops
+ * growing, so a sixth seat adds cost and correlated agreement, not evidence.
+ * Different architectures beat more seats.
+ */
+export const MAX_JURY_JUDGES = 5;
+
+function _overCap(n: number): string | null {
+    return n > MAX_JURY_JUDGES
+        ? `${String(n)} judges exceed the cap of ${String(MAX_JURY_JUDGES)}; past five, more judges add correlated agreement, not independence`
+        : null;
+}
 
 export type JuryResult =
     | {
@@ -75,6 +89,10 @@ export function juryAggregate(scores: readonly JuryScore[]): JuryResult {
     if (scores.length === 0) {
         return { present: false, absentReason: 'no_scores', reason: 'no jury scores supplied' };
     }
+    const overCap = _overCap(scores.length);
+    if (overCap !== null) {
+        return { present: false, absentReason: 'panel_over_cap', reason: overCap };
+    }
     for (const s of scores) {
         if (!Number.isFinite(s.score)) {
             return {
@@ -146,6 +164,17 @@ export function juryPairwise(
     judges: readonly JuryPairwiseJudge[],
 ): JuryPairwiseResult {
     const families = [...new Set(judges.map((j) => j.family))].sort();
+    const overCap = _overCap(judges.length);
+    if (overCap !== null) {
+        return {
+            present: false,
+            absentReason: 'panel_over_cap',
+            reason: overCap,
+            resolution: null,
+            observations: [],
+            consistency: [],
+        };
+    }
     if (judges.length === 0 || families.length < 2) {
         return {
             present: false,
@@ -176,3 +205,128 @@ export function juryPairwise(
     }
     return { present: true, absentReason: null, reason: null, resolution, observations, consistency };
 }
+
+/** One seat on a jury. `billing` is carried, never consulted: a free seat may judge. */
+export interface JurorSeat {
+    readonly judge: string;
+    readonly family: string;
+    readonly billing?: string | null;
+}
+
+/** A panel description, validated: every judge named once, at most five. */
+export function validateJuryPanel(raw: unknown): { panel: JurorSeat[] } | { error: string } {
+    const judges = (raw as { judges?: unknown } | null)?.judges;
+    if (!Array.isArray(judges) || judges.length === 0) return { error: 'a jury panel needs a non-empty `judges` list' };
+    const overCap = _overCap(judges.length);
+    if (overCap !== null) return { error: overCap };
+    const panel: JurorSeat[] = [];
+    for (const j of judges as unknown[]) {
+        const o = j as Partial<JurorSeat> | null;
+        if (typeof o?.judge !== 'string' || typeof o.family !== 'string') {
+            return { error: `every judge needs a string \`judge\` and \`family\` (got ${JSON.stringify(j)})` };
+        }
+        if (panel.some((p) => p.judge === o.judge)) return { error: `judge ${o.judge} is listed twice` };
+        panel.push({ judge: o.judge, family: o.family, billing: o.billing ?? null });
+    }
+    return { panel };
+}
+
+/**
+ * The prompt every juror receives. It takes the task and the item and nothing
+ * else, so no juror can be shown another juror's answer by construction.
+ */
+export function jurorPrompt(task: string, item: string): string {
+    return `${task}\n\n---\n\n${item}`;
+}
+
+export interface BlindJuryResult {
+    /** Why nothing was dispatched, or null. */
+    readonly refused: string | null;
+    readonly answers: ReadonlyArray<{ readonly judge: string; readonly family: string; readonly answer: string }>;
+}
+
+/**
+ * Ask every juror at once with the same prompt. All calls start before any
+ * answer is awaited, so no answer can reach another juror before synthesis.
+ */
+export async function dispatchJuryBlind(
+    task: string,
+    item: string,
+    jurors: readonly JurorSeat[],
+    ask: (juror: JurorSeat, prompt: string) => Promise<string>,
+): Promise<BlindJuryResult> {
+    const overCap = _overCap(jurors.length);
+    if (overCap !== null) return { refused: overCap, answers: [] };
+    const prompt = jurorPrompt(task, item);
+    const pending = jurors.map((j) => ask(j, prompt));
+    const answers = await Promise.all(pending);
+    return { refused: null, answers: jurors.map((j, i) => ({ judge: j.judge, family: j.family, answer: answers[i] as string })) };
+}
+
+export interface JuryIndependence {
+    readonly k: number;
+    readonly items: number;
+    /** Each judge's Cohen's κ against the ground truth — the claim's own statistic, unchanged. */
+    readonly kappa: ReadonlyArray<{ readonly judge: string; readonly kappa: number }>;
+    /** Pairwise φ over error indicators; null where a judge's errors do not vary. */
+    readonly phi: ReadonlyArray<{ readonly a: string; readonly b: string; readonly phi: number | null }>;
+    readonly undefinedPairs: number;
+    /** Mean of the defined φ values, or null when none is defined. */
+    readonly phiBar: number | null;
+    /** Kish effective n = k / (1 + (k−1)·φ̄), with φ̄ floored at 0 so n_eff never exceeds k. */
+    readonly nEff: number | null;
+    readonly nEffRatio: number | null;
+}
+
+function _phi(x: readonly boolean[], y: readonly boolean[]): number | null {
+    let n11 = 0;
+    let n10 = 0;
+    let n01 = 0;
+    let n00 = 0;
+    x.forEach((xi, i) => {
+        const yi = y[i] === true;
+        if (xi && yi) n11 += 1;
+        else if (xi) n10 += 1;
+        else if (yi) n01 += 1;
+        else n00 += 1;
+    });
+    const den = (n11 + n10) * (n01 + n00) * (n11 + n01) * (n10 + n00);
+    return den === 0 ? null : (n11 * n00 - n10 * n01) / Math.sqrt(den);
+}
+
+/**
+ * Family count is a proxy for independence; correlated errors are the thing
+ * itself. A judge's error on item i is `labels[i] !== gold[i]`; φ is the
+ * Pearson correlation of two judges' error vectors, and n_eff is reported
+ * beside κ rather than in place of it.
+ */
+export function juryIndependence(
+    gold: readonly string[],
+    judges: ReadonlyArray<{ readonly judge: string; readonly labels: readonly string[] }>,
+): JuryIndependence {
+    const errors = judges.map((j) => gold.map((g, i) => j.labels[i] !== g));
+    const phi: Array<{ a: string; b: string; phi: number | null }> = [];
+    for (let i = 0; i < judges.length; i += 1) {
+        for (let k = i + 1; k < judges.length; k += 1) {
+            phi.push({
+                a: (judges[i] as { judge: string }).judge,
+                b: (judges[k] as { judge: string }).judge,
+                phi: _phi(errors[i] as boolean[], errors[k] as boolean[]),
+            });
+        }
+    }
+    const defined = phi.map((p) => p.phi).filter((v): v is number => v !== null);
+    const phiBar = defined.length === 0 ? null : defined.reduce((a, v) => a + v, 0) / defined.length;
+    const k = judges.length;
+    const nEff = phiBar === null ? null : k / (1 + (k - 1) * Math.max(0, phiBar));
+    return {
+        k,
+        items: gold.length,
+        kappa: judges.map((j) => ({ judge: j.judge, kappa: cohensKappa(gold, j.labels) })),
+        phi,
+        undefinedPairs: phi.length - defined.length,
+        phiBar,
+        nEff,
+        nEffRatio: nEff === null || k === 0 ? null : nEff / k,
+    };
+}

package/src/scripts/ai_council/kind_flip.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Per-kind flip of typed hands to the free route (free-hands 6.3).
+ *
+ * A kind is served by a free route only after the shadow ledger clears both
+ * pre-registered bars for it: `free-hands-quality-held` (free failure rate at
+ * most the paid rate + 5 pp, and below the 0.3 escalation kill) and
+ * `free-hands-limit-relief` (paid tokens avoided minus the head's verify tokens
+ * above zero in every shadow week). Missing or underpowered data is "not
+ * ready" — never a flip.
+ *
+ * A flipped kind whose free-routed asks reach the kill reverts on its own and
+ * stays reverted: the same shadow data that was outvoted by live data does not
+ * flip it back, so a re-flip needs the record cleared by a person. Every flip
+ * and every reversion is an event in gitignored runtime state, with one line a
+ * claim row can cite. This module never edits `docs/CLAIMS.md`.
+ *
+ * Usage: ./scripts-run src/scripts/ai_council/kind_flip [--apply] [--audit-dir <dir>]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { readShadowLedger, shadowReport, SHADOW_CALL_CAP, type KindShadowStats } from './free_hand_shadow.js';
+import { HAND_KINDS, isHandKind, isUnpaid, ROUTE_BILLINGS, type HandKind, type RouteBilling, type VerifyVerdict } from '../_lib/hand_kinds.js';
+
+/** The escalation kill registered on `ask_economy`; the quality claim's second half. */
+export const ESCALATION_KILL = 0.3;
+export const QUALITY_MARGIN = 0.05;
+/** The A5 cap shared evenly across the kinds; below it a kind's rates settle nothing. */
+export const MIN_SHADOW_PER_KIND = Math.floor(SHADOW_CALL_CAP / HAND_KINDS.length);
+/** Free-routed asks a flipped kind needs before its live rate may revert it. */
+export const REVERT_MIN_SAMPLE = 30;
+
+import { isKindFlipped, KIND_FLIPS_RELPATH } from './kind_flip_state.js';
+export { isKindFlipped, KIND_FLIPS_RELPATH } from './kind_flip_state.js';
+
+export interface FlipVerdict {
+    readonly ready: boolean;
+    readonly reasons: string[];
+}
+
+export function flipVerdict(s: KindShadowStats | undefined): FlipVerdict {
+    if (s === undefined) return { ready: false, reasons: ['no shadow data'] };
+    const reasons: string[] = [];
+    if (s.n < MIN_SHADOW_PER_KIND) reasons.push(`underpowered: ${String(s.n)} of ${String(MIN_SHADOW_PER_KIND)} shadow calls`);
+    if (s.free_rate > s.paid_rate + QUALITY_MARGIN) {
+        reasons.push(`quality margin: free ${s.free_rate.toFixed(3)} > paid ${s.paid_rate.toFixed(3)} + ${String(QUALITY_MARGIN)}`);
+    }
+    if (s.free_rate >= ESCALATION_KILL) reasons.push(`kill: free ${s.free_rate.toFixed(3)} >= ${String(ESCALATION_KILL)}`);
+    if (s.weeks.length === 0 || s.weeks.some((w) => w.net <= 0)) reasons.push('relief: a shadow week without net relief after verify tokens');
+    return { ready: reasons.length === 0, reasons };
+}
+
+/** One free-routed typed ask after a flip, as the head recorded its verify. */
+export interface FreeObservation {
+    readonly kind: HandKind;
+    readonly verified: VerifyVerdict;
+    readonly ts: string;
+}
+
+const _BILLINGS: ReadonlySet<string> = new Set<string>(ROUTE_BILLINGS);
+
+/** The free-routed asks among orchestration audit lines. */
+export function observationsFromAuditLines(lines: readonly Record<string, unknown>[]): FreeObservation[] {
+    const out: FreeObservation[] = [];
+    for (const l of lines) {
+        const o = (l['orchestration'] ?? {}) as Record<string, unknown>;
+        const billing = o['route_billing'];
+        const verified = o['verified'];
+        if (o['route_taken'] !== 'ask' || !isHandKind(o['hand_kind']) || typeof l['ts'] !== 'string') continue;
+        if (typeof billing !== 'string' || !_BILLINGS.has(billing) || !isUnpaid(billing as RouteBilling)) continue;
+        if (verified !== 'pass' && verified !== 'fail' && verified !== 'skipped') continue;
+        out.push({ kind: o['hand_kind'] as HandKind, verified, ts: l['ts'] });
+    }
+    return out;
+}
+
+export interface FlipEvent {
+    readonly ts: string;
+    readonly kind: HandKind;
+    readonly to: 'free' | 'paid';
+    readonly n: number;
+    readonly free_rate: number;
+    readonly line: string;
+}
+
+interface KindState {
+    readonly route: 'free' | 'paid';
+    readonly since: string;
+    readonly reverted?: true;
+}
+
+interface Store {
+    kinds: Partial<Record<HandKind, KindState>>;
+    events: FlipEvent[];
+}
+
+function _path(stateRoot: string): string {
+    return path.join(stateRoot, KIND_FLIPS_RELPATH);
+}
+
+function _read(stateRoot: string): Store {
+    try {
+        const raw = JSON.parse(fs.readFileSync(_path(stateRoot), 'utf8')) as Partial<Store>;
+        return { kinds: raw.kinds ?? {}, events: Array.isArray(raw.events) ? raw.events : [] };
+    } catch {
+        return { kinds: {}, events: [] };
+    }
+}
+
+function _write(stateRoot: string, store: Store): void {
+    const target = _path(stateRoot);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, target);
+}
+
+
+function _flipLine(kind: HandKind, day: string, s: KindShadowStats): string {
+    return (
+        `free-hands-quality-held: ${kind} flipped to the free route on ${day} — shadow n=${String(s.n)}, ` +
+        `free ${s.free_rate.toFixed(3)} vs paid ${s.paid_rate.toFixed(3)}, net relief ${String(s.net)} tokens`
+    );
+}
+
+function _revertLine(kind: HandKind, day: string, n: number, rate: number): string {
+    return (
+        `free-hands-quality-held: ${kind} reverted to the paid route on ${day} — free failure rate ` +
+        `${rate.toFixed(3)} over ${String(n)} free-routed asks >= kill ${String(ESCALATION_KILL)}`
+    );
+}
+
+/** The live breach that reverts a flipped kind: free-routed asks since the flip, at or above the kill. */
+function _revertOf(kind: HandKind, state: KindState, live: readonly FreeObservation[]): { n: number; rate: number } | null {
+    const since = live.filter((o) => o.kind === kind && o.ts >= state.since);
+    if (since.length < REVERT_MIN_SAMPLE) return null;
+    // A `skipped` verify on a free return counts as an escalation, as in the claim.
+    const rate = since.filter((o) => o.verified !== 'pass').length / since.length;
+    return rate >= ESCALATION_KILL ? { n: since.length, rate } : null;
+}
+
+export interface ApplyInput {
+    readonly shadow: readonly KindShadowStats[];
+    readonly live: readonly FreeObservation[];
+    readonly now?: Date;
+}
+
+/** Flip the ready kinds, revert the breaching ones; returns this pass's events. */
+export function applyFlips(stateRoot: string, input: ApplyInput): FlipEvent[] {
+    const store = _read(stateRoot);
+    const now = input.now ?? new Date();
+    const ts = now.toISOString();
+    const day = ts.slice(0, 10);
+    const events: FlipEvent[] = [];
+    for (const kind of HAND_KINDS) {
+        const state = store.kinds[kind];
+        if (state?.route === 'free') {
+            const breach = _revertOf(kind, state, input.live);
+            if (breach === null) continue;
+            store.kinds[kind] = { route: 'paid', since: ts, reverted: true };
+            events.push({ ts, kind, to: 'paid', n: breach.n, free_rate: breach.rate, line: _revertLine(kind, day, breach.n, breach.rate) });
+            continue;
+        }
+        if (state?.reverted === true) continue;
+        const s = input.shadow.find((x) => x.kind === kind);
+        if (s === undefined || !flipVerdict(s).ready) continue;
+        store.kinds[kind] = { route: 'free', since: ts };
+        events.push({ ts, kind, to: 'free', n: s.n, free_rate: s.free_rate, line: _flipLine(kind, day, s) });
+    }
+    if (events.length > 0) {
+        store.events.push(...events);
+        _write(stateRoot, store);
+    }
+    return events;
+}
+
+function _auditLines(dir: string): Record<string, unknown>[] {
+    let files: string[];
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    } catch {
+        return [];
+    }
+    const out: Record<string, unknown>[] = [];
+    for (const f of files) {
+        for (const line of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+            if (line.trim() === '') continue;
+            try {
+                out.push(JSON.parse(line) as Record<string, unknown>);
+            } catch {
+                /* a torn line is skipped */
+            }
+        }
+    }
+    return out;
+}
+
+export async function main(argv: readonly string[], cwd: string = process.cwd()): Promise<number> {
+    const i = argv.indexOf('--audit-dir');
+    const { DEFAULT_DIR } = await import('../orchestration_record.js');
+    const auditDir = i >= 0 && argv[i + 1] !== undefined ? argv[i + 1]! : path.join(cwd, DEFAULT_DIR);
+    const shadow = shadowReport(readShadowLedger(cwd));
+    if (argv.includes('--apply')) {
+        for (const e of applyFlips(cwd, { shadow, live: observationsFromAuditLines(_auditLines(auditDir)) })) {
+            process.stdout.write(`${e.line}\n`);
+        }
+    }
+    for (const kind of HAND_KINDS) {
+        const v = flipVerdict(shadow.find((s) => s.kind === kind));
+        const route = isKindFlipped(cwd, kind) ? 'free' : 'paid';
+        process.stdout.write(`  ${kind}: ${route}${v.ready ? '' : ` · not ready: ${v.reasons.join('; ')}`}\n`);
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/src/scripts/ai_council/kind_flip_state.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a hand kind's flip is stored, and the one read the per-prompt nudge
+ * needs. Apart from `kind_flip.ts`, whose shadow-report imports would put the
+ * whole measurement path into the hook bundle.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const KIND_FLIPS_RELPATH = path.join('agents', 'runtime', 'state', 'hand-kind-flips.json');
+
+/** Unreadable or absent state is "not flipped". */
+export function isKindFlipped(stateRoot: string, kind: string): boolean {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(stateRoot, KIND_FLIPS_RELPATH), 'utf8')) as { kinds?: Record<string, { route?: unknown }> };
+        return raw.kinds?.[kind]?.route === 'free';
+    } catch {
+        return false;
+    }
+}

package/src/scripts/ai_council/learn_low_impact_preview.ts

@@ -4,14 +4,15 @@
  * Ported from the retired Python `src/scripts/ai_council/learn_low_impact_preview.py`
  * (ADR-200 — Python→TS migration, Phase 1).
  *
- * Default invocation is `--preview`: build a structured plan describing
- * which Validated entries would be upstreamed to the package seed without
- * opening a PR. `--apply` (handled by the agent, not this module) is the
- * explicit opt-in that triggers the actual upstream-contribute PR flow.
+ * The command is read-only: it builds a structured plan describing which
+ * Validated entries would be worth upstreaming, and opens nothing. The
+ * `--apply` flag that once drove an upstream PR from here was retired on
+ * 2026-10-13 — it wrote into a package seed file that is not in the tree,
+ * and a second outward route would be a second set of guarantees. The one
+ * gated outward step is `self-repair:release`.
  *
  * The module is import-light by design — pure parsing + redaction + diff
- * rendering. PR creation lives in the `upstream-contribute` skill;
- * this module only hands the agent the material to surface.
+ * rendering. It hands the agent the material to surface and nothing else.
  */
 
 import * as fs from 'node:fs';
@@ -22,6 +23,24 @@ import {
     redact_low_impact_entry,
 } from './redact_low_impact_entry.js';
 
+/**
+ * The package-side seed the preview diffs against — the one place a CALLER
+ * reads this literal from, so no caller restates it. The privacy floor names
+ * the same path for its own purpose, which is a lock rather than a second
+ * source: the rule has to name what it locks.
+ *
+ * The file is deliberately NOT in the tree: the package ships no seed
+ * corpus, `_readSeedPhrases` treats a missing seed as an empty set, and the
+ * preview therefore diffs against an empty baseline. The path is still
+ * named here, and locked by `low-impact-corpus-privacy-floor`, so that a
+ * seed reappearing arrives already under the privacy floor.
+ *
+ * It is RELATIVE. A caller resolves it against the package root; resolving it
+ * against an arbitrary cwd would let a same-named file in a consumer project
+ * mark entries `already_seeded` and suppress them silently.
+ */
+export const PACKAGE_SEED_PATH = 'data/low-impact-decisions-seed.md';
+
 // Python: re.compile(r"^last-upstreamed:\s*([0-9a-f]{6,40}|0+)\s*$",
 //                     re.IGNORECASE | re.MULTILINE)
 // \s is Unicode in Python; emulate via the explicit Unicode whitespace class.
@@ -57,10 +76,10 @@ export class RefusedEntry {
 }
 
 /**
- * Structured preview for `/memory learn-low-impact --preview`.
+ * Structured preview for `/memory learn-low-impact`.
  *
- * Consumed by the agent which renders the human-facing preview block,
- * then waits for explicit `--apply` before invoking `upstream-contribute`.
+ * Consumed by the agent which renders the human-facing preview block. The
+ * command ends there: it opens nothing and sends nothing.
  */
 export class LearnLowImpactPreview {
     readonly promoted: readonly PreviewEntry[];
@@ -97,10 +116,14 @@ export class LearnLowImpactPreview {
     }
 
     /**
-     * True when `--apply` would actually open a PR.
+     * True when the promoted set is both non-empty and wholly clean — the
+     * shape an upstream contribution would need. Nothing here acts on it;
+     * `render()` reads it to decide which closing line to print.
      *
-     * Iron Law: any redactor refusal blocks the PR — the author must
-     * rephrase or drop the offending entry locally and re-run.
+     * The name predates the retirement of `--apply` and is kept because it
+     * is the published accessor; what changed is that no caller opens
+     * anything. Iron Law, unchanged: any redactor refusal blocks promotion —
+     * the author rephrases or drops the offending entry locally and re-runs.
      */
     get would_open_pr(): boolean {
         return this.promoted.length > 0 && this.refused.length === 0;
@@ -148,13 +171,17 @@ export class LearnLowImpactPreview {
         }
         if (this.refused.length > 0) {
             lines.push(
-                '> Refusals block the PR. Rephrase the entries locally' +
+                '> Refusals block promotion. Rephrase the entries locally' +
                     ' (or drop them) and re-run.',
             );
         } else if (this.promoted.length > 0) {
             lines.push(
-                '> Re-run with `--apply` to open the draft PR via' +
-                    ' `upstream-contribute`.',
+                // Deliberately no onward pointer. The outward ladder releases
+                // a RECORDED defect and nothing here opens a record, so a
+                // corpus entry cannot ride it today; naming a route the
+                // reader cannot take is worse than naming none.
+                '> This command sends nothing. Promoting an entry upstream is' +
+                    ' a separate, explicitly authorised decision.',
             );
         }
         // Python: "\n".join(lines).rstrip() + "\n"
@@ -162,11 +189,11 @@ export class LearnLowImpactPreview {
     }
 
     /**
-     * Source-project-stripped diff that `--apply` would propose.
+     * Source-project-stripped diff the preview proposes for a reader.
      *
      * Emits unified-diff-style `+` lines for each promoted phrase under the
-     * seed file's `## Validated` section. The agent uses this as the
-     * `upstream-contribute` patch body.
+     * seed file's `## Validated` section — material for a reader to judge,
+     * not a patch this command applies anywhere.
      */
     render_diff(): string {
         if (this.promoted.length === 0) {
@@ -187,7 +214,7 @@ export class LearnLowImpactPreview {
         const bodyLines: string[] = [
             `# ${title}`,
             '',
-            'Upstream from `/memory learn-low-impact --apply`.',
+            'Prepared from `/memory learn-low-impact`, which sends nothing.',
             '',
             '## Entries',
             '',
@@ -223,9 +250,10 @@ function _rstrip(s: string): string {
 /**
  * Return the set of normalised phrases already in the seed file.
  *
- * Missing seed file is not an error — it returns an empty set so the
- * first-ever upstream PR can seed the whole corpus. Reuses the strict
- * parser so the seed itself is contract-validated.
+ * Missing seed file is not an error — it returns an empty set, which is the
+ * standing case rather than an edge one: the package ships no seed, so every
+ * preview diffs against an empty baseline (see `PACKAGE_SEED_PATH`). Reuses
+ * the strict parser so a seed that does appear is contract-validated.
  */
 function _readSeedPhrases(seedPath: string): Set<string> {
     if (!fs.existsSync(seedPath)) {