@event4u/agent-config 8.11.0 → 8.12.0

package/src/scripts/_lib/knowledge_global.ts

@@ -58,6 +58,29 @@ export const TIERS: readonly string[] = ['public', 'vendor', 'proprietary'];
  */
 export const DEFAULT_ALLOWED_TIERS: readonly string[] = ['public'];
 
+/**
+ * Sensitivity axis (Phase 1, road-to-feedback-8.11 / successor note to
+ * ADR-119) — orthogonal to `TIERS` (origin) and layered on top of the
+ * existing tier + redaction gate. `tier` classifies WHERE a card came from;
+ * `sensitivity` classifies WHETHER it may ever leave the project at all.
+ *
+ *   * `prohibited` — contains redaction-class content; never leaves the
+ *     repo. Machine-derived from the redaction scan (a card is never
+ *     hand-labelled into this class — a positive hit forces it).
+ *   * `project` — DEFAULT. Stays project-local; promotion is refused
+ *     unless a human explicitly reclassifies the card to `shareable`.
+ *   * `shareable` — eligible for the global store; must pass redaction
+ *     AND carry full promotion provenance (see the G5 footer fields).
+ *
+ * Deliberately kept to three machine-anchored classes — a wider
+ * team/organization taxonomy is phantom for a single-maintainer install and
+ * would over-fit; revisit only once a real multi-tenant consumer exists.
+ */
+export const SENSITIVITIES: readonly string[] = ['prohibited', 'project', 'shareable'];
+
+/** Default sensitivity for a card with no explicit `sensitivity:` field. */
+export const DEFAULT_SENSITIVITY = 'project';
+
 /**
  * Hard defaults applied when the setting block is absent. Default is ON for
  * the safe tiers; turning sharing on never makes promotion automatic.
@@ -384,6 +407,14 @@ const _PROVENANCE_FIELDS: readonly string[] = [
     'last_verified',
     'tier',
     'seen_in',
+    // G5 promotion audit-trail fields (Phase 1, road-to-feedback-8.11):
+    // the more consistent home for these than frontmatter, since they sit
+    // alongside the other promotion-time facts above, not the card's own
+    // origin-tier/sensitivity classification (which lives in frontmatter).
+    'source_repo',
+    'owner',
+    'review_after',
+    'promotion_reason',
 ];
 
 /** Render the global-card provenance footer (the unversioned-store audit trail). */
@@ -394,6 +425,10 @@ export function render_provenance_footer(args: {
     last_verified: string;
     tier: string;
     seen_in: string[];
+    source_repo: string;
+    owner: string;
+    review_after: string;
+    promotion_reason: string;
 }): string {
     return [
         PROVENANCE_START,
@@ -403,11 +438,20 @@ export function render_provenance_footer(args: {
         `- last_verified: ${args.last_verified}`,
         `- tier: ${args.tier}`,
         `- seen_in: ${args.seen_in.join(', ')}`,
+        `- source_repo: ${args.source_repo}`,
+        `- owner: ${args.owner}`,
+        `- review_after: ${args.review_after}`,
+        `- promotion_reason: ${_singleLine(args.promotion_reason)}`,
         PROVENANCE_END,
         '',
     ].join('\n');
 }
 
+/** Collapse a human-entered reason to one line — footer fields are line-based. */
+function _singleLine(s: string): string {
+    return s.replace(/\r\n|\r|\n/g, ' ').trim();
+}
+
 /** Extract the provenance footer fields as a flat dict (empty if absent). */
 export function parse_provenance_footer(text: string): Record<string, string> {
     if (!text.includes(PROVENANCE_START) || !text.includes(PROVENANCE_END)) {

package/src/scripts/_lib/knowledge_global_promote.ts

@@ -187,6 +187,156 @@ export function should_suggest(
     return len >= options.threshold;
 }
 
+// ---------------------------------------------------------------------------
+// Sensitivity gate (Phase 1, road-to-feedback-8.11 — successor note to
+// ADR-119). Layered ON TOP of the existing tier/redaction gate in
+// `knowledge_global_redaction.ts`: a card must clear tier + redaction FIRST,
+// then clear this gate before its write is allowed to proceed.
+// ---------------------------------------------------------------------------
+
+/** Outcome of the sensitivity gate for one promotion attempt. */
+export interface SensitivityGateResult {
+    readonly eligible: boolean;
+    readonly reason: string;
+    /** The EFFECTIVE sensitivity used for the decision (post auto-derivation). */
+    readonly sensitivity: string;
+}
+
+/**
+ * Resolve the effective sensitivity used for a promotion decision.
+ *
+ * A redaction hit always forces `prohibited`, overriding any declared value —
+ * this is independent of the tier gate's own `halt_on_trigger` setting, so a
+ * `prohibited` override never depends on that unrelated config flag. An
+ * unset / invalid declared value defaults to `project` (never `shareable` —
+ * `shareable` is never auto-assigned, only explicitly declared by a human).
+ */
+export function resolve_effective_sensitivity(declared: string, violations_present: boolean): string {
+    if (violations_present) {
+        return 'prohibited';
+    }
+    const d = (declared ?? '').trim();
+    return knowledge_global.SENSITIVITIES.includes(d) ? d : knowledge_global.DEFAULT_SENSITIVITY;
+}
+
+/**
+ * Gate a card for promotion on the sensitivity axis.
+ *
+ * Refuses anything whose effective sensitivity is not `shareable` (including
+ * the machine-derived `prohibited` override), and refuses a `shareable` card
+ * that has no human-entered `promotion_reason` — the auto-promote
+ * *suggestion* only ever leads to a write once a human states why the card
+ * is safe to share.
+ */
+export function gate_sensitivity_for_promotion(
+    declared_sensitivity: string,
+    options: { violations_present?: boolean; promotion_reason?: string } = {},
+): SensitivityGateResult {
+    const violations_present = options.violations_present ?? false;
+    const effective = resolve_effective_sensitivity(declared_sensitivity, violations_present);
+
+    if (effective === 'prohibited') {
+        return {
+            eligible: false,
+            sensitivity: effective,
+            reason:
+                'sensitivity: prohibited — redaction-class content, never leaves the repo',
+        };
+    }
+    if (effective !== 'shareable') {
+        return {
+            eligible: false,
+            sensitivity: effective,
+            reason:
+                `sensitivity '${effective}' — promotion refused unless a human explicitly ` +
+                "reclassifies the card to 'shareable'",
+        };
+    }
+    const reason = (options.promotion_reason ?? '').trim();
+    if (!reason) {
+        return {
+            eligible: false,
+            sensitivity: effective,
+            reason:
+                "sensitivity 'shareable' but no promotion_reason given — a human must state " +
+                'why this card is safe to share before it may be promoted',
+        };
+    }
+    return { eligible: true, sensitivity: effective, reason: 'sensitivity gate passed' };
+}
+
+// ---------------------------------------------------------------------------
+// Revocation ledger — append-only tombstone trail (Phase 1, road-to-feedback-8.11)
+// ---------------------------------------------------------------------------
+
+export const REVOCATIONS_FILENAME = '.revocations.jsonl';
+
+/** One append-only tombstone line: what was revoked, when, and why. */
+export interface RevocationEntry {
+    readonly revoked_at: string;
+    readonly card_id: string;
+    readonly reason: string;
+}
+
+function _revocations_path(env: knowledge_global.EnvMapType): string {
+    return path.join(knowledge_global.global_store_dir(env, { create: true }), REVOCATIONS_FILENAME);
+}
+
+/**
+ * Append one tombstone line to the revocation ledger — the caller MUST call
+ * this BEFORE deleting the card/usage entry it documents. Append-only (a
+ * single `fs.appendFileSync`, never rewritten): no `forget` / `forget --tier`
+ * / `purge` call ever removes a prior tombstone, so the ledger stays a
+ * durable audit trail across every deletion path — including `purge`, which
+ * deliberately spares this one file while wiping everything else.
+ */
+export function append_tombstone(
+    card_id: string,
+    reason: string,
+    options: { today?: string; env?: knowledge_global.EnvMapType } = {},
+): RevocationEntry {
+    const entry: RevocationEntry = {
+        revoked_at: options.today ?? '',
+        card_id,
+        reason: reason || 'no reason given',
+    };
+    fs.appendFileSync(_revocations_path(options.env ?? null), JSON.stringify(entry) + '\n', 'utf-8');
+    return entry;
+}
+
+/** Read the revocation ledger. Tolerant: missing file → []; malformed lines are skipped. */
+export function load_tombstones(env: knowledge_global.EnvMapType = null): RevocationEntry[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(
+            path.join(knowledge_global.global_store_dir(env), REVOCATIONS_FILENAME),
+            'utf-8',
+        );
+    } catch {
+        return [];
+    }
+    const out: RevocationEntry[] = [];
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.trim();
+        if (!line) {
+            continue;
+        }
+        try {
+            const obj: unknown = JSON.parse(line);
+            if (_isPlainObject(obj) && typeof obj['card_id'] === 'string') {
+                out.push({
+                    revoked_at: String(obj['revoked_at'] ?? ''),
+                    card_id: obj['card_id'],
+                    reason: String(obj['reason'] ?? ''),
+                });
+            }
+        } catch {
+            // corrupt line — skip; never let one bad line crash the ledger read
+        }
+    }
+    return out;
+}
+
 /**
  * List cards that warrant a promotion suggestion under the current config.
  *

package/src/scripts/ai_council/orchestrator.ts

@@ -65,7 +65,8 @@ import {
     synthesis_template,
     system_prompt_for,
 } from './prompts.js';
-import { render_vote_tally, tally_stances } from './stance_tally.js';
+import { count_dissenters, dissent_quota_met, is_near_duplicate } from './debate_gates.js';
+import { parse_stance_line, render_vote_tally, tally_stances } from './stance_tally.js';
 
 // ── Python-format / stdlib parity helpers ────────────────────────────────
 //
@@ -419,6 +420,14 @@ export interface ConsultOptions {
      * round's prompt is byte-identical to today.
      */
     stance_tally?: boolean;
+    /**
+     * Phase 1 stance-repair transport (2026-07-12 council policy): confirm per
+     * member in interactive runs; `null`/absent → a missing/unparseable stance
+     * stays a repair-marker in the tally, never an unplanned billable call.
+     */
+    on_stance_repair?: ((member: string) => boolean) | null;
+    /** Receives each stance-repair response so the caller can account its cost. */
+    on_stance_repair_result?: ((r: CouncilResponse) => void) | null;
 }
 
 /**
@@ -515,6 +524,46 @@ export function consult(
         }
     }
 
+    // Phase 1 stance repair: one bounded stance-line-only re-prompt per member
+    // whose final reply lacks a parseable STANCE line — dispatched only through
+    // the on_stance_repair transport, reusing _run_round (spend gate + ledger +
+    // stamping unchanged). The repaired stance line is APPENDED to the member's
+    // final text so the deterministic tally can read it.
+    const on_stance_repair = opts.on_stance_repair ?? null;
+    if (stance_tally && on_stance_repair !== null) {
+        for (let i = 0; i < last_results.length; i++) {
+            const r = last_results[i] as CouncilResponse;
+            if (r.error !== null || r.text.trim() === '' || parse_stance_line(r.text) !== null) {
+                continue;
+            }
+            const member = members[i];
+            if (member === undefined || !on_stance_repair(member.name)) {
+                continue;
+            }
+            const repairQ = new CouncilQuestion({
+                mode: question.mode,
+                user_prompt:
+                    `Your reply is missing the mandatory closing stance line. ` +
+                    `Reply with ONLY that single line for your final position.\n\n${STANCE_LINE_CONTRACT}`,
+                max_tokens: question.max_tokens,
+            });
+            const rr = _run_round([member], repairQ, resolvedBudget, spent, {
+                table,
+                on_overrun,
+                project,
+                original_ask,
+                advisor_plans,
+            });
+            const rep = rr[0];
+            if (rep !== undefined) {
+                opts.on_stance_repair_result?.(rep);
+                if (rep.error === null && parse_stance_line(rep.text) !== null) {
+                    r.text = `${r.text.trim()}\n\n${rep.text.trim()}`;
+                }
+            }
+        }
+    }
+
     return last_results;
 }
 
@@ -895,6 +944,90 @@ function _augment_for_debate_round(
     );
 }
 
+/**
+ * Phase 3 post-round enforcement (2026-07-12 council policy): deterministic
+ * detectors flag members whose round added nothing (novelty near-duplicate of
+ * their own prior round) or when the round collapsed toward agreement (dissent
+ * quota unmet → the most-recently-converged member). At most ONE bounded repair
+ * re-prompt per member per round, dispatched only through the `on_repair`
+ * transport (confirm-interactive / auto-fire under --auto-continue); the repair
+ * call reuses `_run_round`, so the projected-spend gate, ledger, and metadata
+ * stamping apply unchanged. A successful repair REPLACES the member's entry so
+ * downstream rounds/persistence see the repaired reply.
+ */
+function _run_debate_gate_repairs(
+    members: ExternalAIClient[],
+    results: CouncilResponse[],
+    prior: CouncilResponse[],
+    round_question: CouncilQuestion,
+    budget: CostBudget,
+    spent: Spent,
+    round_opts: {
+        table: PriceTable | null;
+        on_overrun: OnOverrunCallback | null;
+        project: ProjectContext | null;
+        original_ask: string;
+        advisor_plans: Map<string, AdvisorPlan> | null;
+    },
+    on_repair: ((member: string, reason: string) => boolean) | null,
+): CouncilResponse[] {
+    const flagged: Array<{ idx: number; reason: string }> = [];
+    const okText = (r: CouncilResponse | undefined): string =>
+        r !== undefined && r.error === null ? r.text : '';
+    for (let i = 0; i < results.length; i++) {
+        const curr = okText(results[i]);
+        const prev = okText(prior[i]);
+        if (curr !== '' && prev !== '' && is_near_duplicate(prev, curr)) {
+            flagged.push({ idx: i, reason: 'novelty: near-duplicate of your own prior round' });
+        }
+    }
+    const texts = results.map((r) => okText(r));
+    if (!dissent_quota_met(texts.filter((t) => t !== ''))) {
+        // Most-recently-converged heuristic: the LAST member with a real reply
+        // that carries no objection marker.
+        for (let i = results.length - 1; i >= 0; i--) {
+            const t = okText(results[i]);
+            if (t !== '' && count_dissenters([t]) === 0 && !flagged.some((f) => f.idx === i)) {
+                flagged.push({ idx: i, reason: 'dissent quota unmet: state a genuine objection or confirm with a named reason' });
+                break;
+            }
+        }
+    }
+    if (flagged.length === 0 || on_repair === null) {
+        return results;
+    }
+    const repaired = new Set<number>();
+    const out = [...results];
+    for (const f of flagged) {
+        if (repaired.has(f.idx)) {
+            continue; // hard cap: <= 1 repair per member per round
+        }
+        const member = members[f.idx];
+        if (member === undefined) {
+            continue;
+        }
+        if (!on_repair(member.name, f.reason)) {
+            continue;
+        }
+        repaired.add(f.idx);
+        const repairQ = new CouncilQuestion({
+            mode: round_question.mode,
+            user_prompt:
+                `${round_question.user_prompt}\n\n---\n\n` +
+                `REPAIR RE-PROMPT (${f.reason}). Your previous reply this round did not ` +
+                `advance the debate. Respond again: either a genuinely updated position ` +
+                `naming the specific flaw that moved you, or an explicit defense with NEW evidence.`,
+            max_tokens: round_question.max_tokens,
+        });
+        const rr = _run_round([member], repairQ, budget, spent, round_opts);
+        const r0 = rr[0];
+        if (r0 !== undefined && r0.error === null && r0.text.trim() !== '') {
+            out[f.idx] = r0;
+        }
+    }
+    return out;
+}
+
 export interface RunDebateOptions {
     budget?: CostBudget | null;
     table?: PriceTable | null;
@@ -914,6 +1047,22 @@ export interface RunDebateOptions {
      * prompt is byte-identical to today.
      */
     debate_gates?: boolean;
+    /**
+     * Phase 3 repair transport, per the 2026-07-12 council policy
+     * (`debate_gates.repair_action`): the CLI passes `() => true` under
+     * `--auto-continue` (auto-fire under the cap) or an interactive one-line
+     * confirm otherwise. `null`/absent → gates detect but never dispatch
+     * (no unplanned spend without an explicit transport).
+     */
+    on_repair?: ((member: string, reason: string) => boolean) | null;
+    /**
+     * Phase 3 restate pass (`ai_council.restate.enabled` / `--restate`): a
+     * pre-round-1 billable call per member collecting a <=50-word restatement
+     * + one alternative framing. Default off -> no extra calls, byte-identical.
+     */
+    restate?: boolean;
+    /** Receives the restate responses (rendering, divergence flags, cost). */
+    on_restate?: ((responses: CouncilResponse[]) => void) | null;
 }
 
 /**
@@ -975,6 +1124,27 @@ export function run_debate(
     const all_rounds: CouncilResponse[][] = [];
     let current_user_prompt = question.user_prompt;
 
+    // Phase 3 restate: one pre-round-1 call per member. Runs BEFORE any debate
+    // spend so a diverging restatement can be flagged before round-2 cost.
+    if (opts.restate === true) {
+        const restateQ = new CouncilQuestion({
+            mode: question.mode,
+            user_prompt:
+                `Before the debate begins: RESTATE the question below in at most 50 words, ` +
+                `then offer ONE alternative framing of it. Do not argue a position yet.\n\n---\n\n` +
+                `${question.user_prompt}`,
+            max_tokens: question.max_tokens,
+        });
+        const restated = _run_round(members, restateQ, budget, spent, {
+            table,
+            on_overrun,
+            project,
+            original_ask,
+            advisor_plans,
+        });
+        opts.on_restate?.(restated);
+    }
+
     for (let round_idx = 0; round_idx < max_rounds; round_idx++) {
         const round_number = round_idx + 1;
         let results: CouncilResponse[];
@@ -1000,6 +1170,23 @@ export function run_debate(
             });
         }
 
+        if (opts.debate_gates === true && round_idx > 0 && all_rounds.length > 0) {
+            results = _run_debate_gate_repairs(
+                members,
+                results,
+                all_rounds[all_rounds.length - 1] as CouncilResponse[],
+                // round_idx > 0 here, so current_user_prompt IS this round's prompt.
+                new CouncilQuestion({
+                    mode: question.mode,
+                    user_prompt: current_user_prompt,
+                    max_tokens: question.max_tokens,
+                }),
+                budget,
+                spent,
+                { table, on_overrun, project, original_ask, advisor_plans },
+                opts.on_repair ?? null,
+            );
+        }
         all_rounds.push(results);
         if (on_round_complete !== null) {
             on_round_complete(round_number, results);