@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/ai_council/redact_low_impact_entry.ts

@@ -0,0 +1,291 @@
+/**
+ * Privacy floor for `agents/decisions/low-impact-decisions.md` (Phase 12).
+ *
+ * TypeScript twin of `src/scripts/ai_council/redact_low_impact_entry.py`
+ * (ADR-200 — Python→TS migration, Phase 1). Security-sensitive: the
+ * redaction regexes and refusal markers are matched byte-for-byte against
+ * the Python original.
+ *
+ * Non-bypassable redactor invoked on intake (write-side) AND on
+ * upstream (`/learn-low-impact`, leave-the-repo side). Both gates call
+ * {@link redact_low_impact_entry} and refuse to proceed when a forbidden
+ * pattern fires.
+ *
+ * Iron Law: nothing leaves the project repo until this redactor clears
+ * the entry. See `.augment/rules/low-impact-corpus-privacy-floor.md`.
+ *
+ * Forbidden-content classes (per Phase 12 § Step 4):
+ *
+ * 1. Secrets — raw-key prefixes mirrored from
+ *    `scripts.ai_council.config._RAW_KEY_PREFIXES`, plus a generic
+ *    `api[-_]?key:\s*<token>` shape.
+ * 2. Emails — RFC-5322-ish shape, deliberately permissive.
+ * 3. Project-rooted paths — anything starting `/Users/`, `/home/`,
+ *    `/opt/`, `/private/`, drive letters (`C:\`), or the configured repo
+ *    root from `.agent-settings.yml` when supplied.
+ * 4. Customer / tenant names — caller passes a name list (project
+ *    policy); generic placeholders `<customer>`, `<tenant>`, `<account>`,
+ *    `<user>` survive.
+ * 5. Internal hostnames — `*.internal`, `*.local`, plus any project-private
+ *    domain the caller supplies.
+ * 6. Monetary amounts — `$1,234` / `€500` / `USD 1000` shapes that look
+ *    like business figures.
+ * 7. Business-context SQL identifiers — caller-supplied table / column
+ *    allow-list. Default empty.
+ * 8. Inline code excerpts > 40 chars — any backtick-fenced run > 40.
+ */
+
+import { _RAW_KEY_PREFIXES } from './config.js';
+
+/**
+ * Code-point length, matching Python `len(str)`. JS `String.length`
+ * counts UTF-16 units, so an astral char would over-count; Python counts
+ * code points. `Array.from` iterates code points.
+ */
+function _pyLen(s: string): number {
+    let n = 0;
+    for (const _ of s) {
+        n += 1;
+    }
+    return n;
+}
+
+/**
+ * Slice the first `n` code points, matching Python `s[:n]`. JS
+ * `String.slice` is UTF-16-unit based; we slice by code point for parity.
+ */
+function _pySliceHead(s: string, n: number): string {
+    let out = '';
+    let i = 0;
+    for (const ch of s) {
+        if (i >= n) {
+            break;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}
+
+/** Python `str.strip()` — leading/trailing whitespace. */
+function _strip(s: string): string {
+    return s.trim();
+}
+
+/**
+ * Escape a string for literal use inside a `u`-flagged RegExp.
+ *
+ * Python `re.escape` backslash-escapes every non-word char; under the JS
+ * `u` flag an escape like `\-` is illegal, so we escape only the
+ * ECMAScript regex metacharacters. The *match behaviour* is identical
+ * (literal match of the input string) — only the pattern source differs,
+ * which is not observable.
+ */
+function _reEscape(s: string): string {
+    // `-` and `/` are NOT metacharacters outside a character class in
+    // ECMAScript; escaping `-` as `\-` is illegal under the `u` flag.
+    return s.replace(/[.*+?^${}()|[\]\\]/gu, (c) => '\\' + c);
+}
+
+/** Single forbidden-pattern hit. */
+export interface RedactionViolation {
+    readonly category: string;
+    readonly snippet: string;
+    readonly note: string;
+}
+
+function _violation(category: string, snippet: string, note = ''): RedactionViolation {
+    return { category, snippet, note };
+}
+
+/** Python repr() for a string: single-quoted (used by `summary()`). */
+function _pyRepr(s: string): string {
+    // Mirror Python repr for the snippet types this module produces
+    // (printable ASCII / unicode runs without embedded quotes-needing
+    // escapes beyond the wrapping). Python prefers single quotes unless
+    // the string contains a single quote and no double quote.
+    const hasSingle = s.includes("'");
+    const hasDouble = s.includes('"');
+    const quote = hasSingle && !hasDouble ? '"' : "'";
+    let body = s.replace(/\\/g, '\\\\');
+    body = body
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    if (quote === "'") {
+        body = body.replace(/'/g, "\\'");
+    } else {
+        body = body.replace(/"/g, '\\"');
+    }
+    return `${quote}${body}${quote}`;
+}
+
+/** Outcome of one redaction pass. */
+export class RedactionResult {
+    readonly ok: boolean;
+    readonly violations: readonly RedactionViolation[];
+
+    constructor(ok: boolean, violations: readonly RedactionViolation[] = []) {
+        this.ok = ok;
+        this.violations = violations;
+    }
+
+    summary(): string {
+        if (this.ok) {
+            return 'redaction: clean';
+        }
+        const parts = this.violations.map((v) => `${v.category}: ${_pyRepr(v.snippet)}`);
+        return 'redaction REFUSED — ' + parts.join('; ');
+    }
+}
+
+// ── regex patterns (Python `re` semantics replicated) ────────────────────
+// Python `\w`/`\b`/`\d` are Unicode by default. JS `\w`/`\b`/`\d` are
+// ASCII-only even with the `u` flag, so where Python uses them we replicate
+// the Unicode class explicitly.
+
+// Python: \b[\w.+-]+@[\w-]+\.[\w.-]+\b
+// Unicode \w == [\p{L}\p{N}_]. We emulate \b via lookarounds on the
+// Unicode word-char class.
+const _UWORD = '[\\p{L}\\p{N}_]';
+const _UNB_BEFORE = `(?<!${_UWORD})`;
+const _UNB_AFTER = `(?!${_UWORD})`;
+const _EMAIL_RE = new RegExp(
+    `${_UNB_BEFORE}[\\p{L}\\p{N}_.+-]+@[\\p{L}\\p{N}_-]+\\.[\\p{L}\\p{N}_.-]+${_UNB_AFTER}`,
+    'gu',
+);
+
+// Python: (?:^|[\s"'(]) (?:/Users/|/home/|/opt/|/private/|[A-Z]:\\) [\w.\-/\\]+
+// \s is Unicode in Python; \w Unicode. No \b here.
+const _PATH_RE = new RegExp(
+    '(?:^|[\\s"\'(])' +
+        '(?:/Users/|/home/|/opt/|/private/|[A-Z]:\\\\)' +
+        '[\\p{L}\\p{N}_.\\-/\\\\]+',
+    'gmu',
+);
+
+// Python: \b[a-zA-Z0-9][\w.-]*\.(?:internal|local)\b  (IGNORECASE)
+const _INTERNAL_HOST_RE = new RegExp(
+    `${_UNB_BEFORE}[a-zA-Z0-9][\\p{L}\\p{N}_.-]*\\.(?:internal|local)${_UNB_AFTER}`,
+    'giu',
+);
+
+// Python:
+//   (?:[\$€£¥]\s?\d{1,3}(?:[,.]\d{3})*(?:\.\d+)?
+//    |\b(?:USD|EUR|GBP|JPY)\s?\d+(?:[,.]\d+)?)
+// \d and \s Unicode in Python; \b Unicode (before the currency-code alt).
+const _UD = '[\\p{Nd}]';
+const _MONEY_RE = new RegExp(
+    `(?:[\\$€£¥]\\s?${_UD}{1,3}(?:[,.]${_UD}{3})*(?:\\.${_UD}+)?` +
+        `|${_UNB_BEFORE}(?:USD|EUR|GBP|JPY)\\s?${_UD}+(?:[,.]${_UD}+)?)`,
+    'gu',
+);
+
+// Python: (?i)\bapi[_-]?key\b\s*[:=]\s*[A-Za-z0-9+/=_\-]{12,}
+const _API_KEY_RE = new RegExp(
+    `${_UNB_BEFORE}api[_-]?key${_UNB_AFTER}\\s*[:=]\\s*[A-Za-z0-9+/=_\\-]{12,}`,
+    'giu',
+);
+
+// Python: `([^`]{41,})`
+const _CODE_FENCE_RE = /`([^`]{41,})`/gu;
+
+function _checkSecrets(text: string): RedactionViolation[] {
+    const hits: RedactionViolation[] = [];
+    for (const prefix of _RAW_KEY_PREFIXES) {
+        const pat = new RegExp(_reEscape(prefix) + '[A-Za-z0-9_\\-]{6,}', 'u');
+        const m = pat.exec(text);
+        if (m) {
+            hits.push(
+                _violation(
+                    'secret',
+                    _pySliceHead(m[0], 8) + '…',
+                    `raw-key prefix ${_pyRepr(prefix)}`,
+                ),
+            );
+        }
+    }
+    _API_KEY_RE.lastIndex = 0;
+    const m = _API_KEY_RE.exec(text);
+    if (m) {
+        hits.push(_violation('secret', _pySliceHead(m[0], 20) + '…', 'inline api_key'));
+    }
+    return hits;
+}
+
+function _checkPatterns(
+    text: string,
+    repoRoot: string | null,
+    privateDomains: Iterable<string>,
+    customerNames: Iterable<string>,
+    sqlIdentifiers: Iterable<string>,
+): RedactionViolation[] {
+    const hits: RedactionViolation[] = [];
+    for (const m of text.matchAll(_EMAIL_RE)) {
+        hits.push(_violation('email', m[0]));
+    }
+    for (const m of text.matchAll(_PATH_RE)) {
+        hits.push(_violation('project_path', _strip(m[0])));
+    }
+    if (repoRoot && text.includes(repoRoot)) {
+        hits.push(_violation('project_path', repoRoot, 'configured repo root'));
+    }
+    for (const m of text.matchAll(_INTERNAL_HOST_RE)) {
+        hits.push(_violation('internal_hostname', m[0]));
+    }
+    for (const dom of privateDomains) {
+        if (dom && text.includes(dom)) {
+            hits.push(_violation('internal_hostname', dom, 'configured private domain'));
+        }
+    }
+    for (const m of text.matchAll(_MONEY_RE)) {
+        hits.push(_violation('monetary_amount', m[0]));
+    }
+    for (const name of customerNames) {
+        // Python: re.search(rf"\b{re.escape(name)}\b", text, re.IGNORECASE)
+        if (name && new RegExp(`${_UNB_BEFORE}${_reEscape(name)}${_UNB_AFTER}`, 'iu').test(text)) {
+            hits.push(_violation('customer_name', name));
+        }
+    }
+    for (const ident of sqlIdentifiers) {
+        // Python: re.search(rf"\b{re.escape(ident)}\b", text)
+        if (ident && new RegExp(`${_UNB_BEFORE}${_reEscape(ident)}${_UNB_AFTER}`, 'u').test(text)) {
+            hits.push(_violation('sql_identifier', ident));
+        }
+    }
+    for (const m of text.matchAll(_CODE_FENCE_RE)) {
+        const inner = m[1] as string;
+        hits.push(
+            _violation('long_code_excerpt', _pySliceHead(inner, 40) + '…', `${_pyLen(inner)} chars`),
+        );
+    }
+    return hits;
+}
+
+export interface RedactOptions {
+    repoRoot?: string | null;
+    privateDomains?: Iterable<string>;
+    customerNames?: Iterable<string>;
+    sqlIdentifiers?: Iterable<string>;
+}
+
+/**
+ * Run the privacy floor over `text`. Returns clean or refused.
+ *
+ * The redactor never auto-rewrites the entry — that would be a soft
+ * privacy gate. It refuses + surfaces what to rephrase, which keeps the
+ * user in the loop and the audit trail honest.
+ */
+export function redact_low_impact_entry(text: string, opts: RedactOptions = {}): RedactionResult {
+    const repoRoot = opts.repoRoot ?? null;
+    const privateDomains = opts.privateDomains ?? [];
+    const customerNames = opts.customerNames ?? [];
+    const sqlIdentifiers = opts.sqlIdentifiers ?? [];
+
+    const violations: RedactionViolation[] = [];
+    violations.push(..._checkSecrets(text));
+    violations.push(
+        ..._checkPatterns(text, repoRoot, privateDomains, customerNames, sqlIdentifiers),
+    );
+    return new RedactionResult(violations.length === 0, violations);
+}

package/src/scripts/ai_council/replay.ts

@@ -0,0 +1,314 @@
+// Decision-replay artefact for council sessions (Phase 9) — TypeScript twin
+// (py2ts Phase 1).
+//
+// Produces a per-session `decision-replay.md` that surfaces the audit
+// trail GPT review of PR #148 called out as missing: for each top
+// finding, the consensus_strength, agreeing-members with their key
+// argument, dissenting-members with their counter-argument, the
+// evidence-quality verdict, and a final synthesis verdict line.
+//
+// The artefact is a pure projection of the consensus data plus the
+// per-member deliberation texts — no extra model calls. Schema is
+// documented in `docs/contracts/ai-council-config.md` under
+// "Decision-replay schema".
+//
+// Parity notes (ADR-200):
+// - `" ".join(text.split())` collapses any run of Unicode whitespace to a
+//   single space and drops leading/trailing whitespace — `_pyJoinSplit`
+//   mirrors Python `str.split()` (no-arg) + `" ".join(...)`.
+// - Truncation `flat[:N].rstrip() + "…"` slices by CODE POINT then strips
+//   trailing whitespace — `_pyTruncate` reproduces both.
+// - `f"{x:.2f}"` / `f"{x:.1f}"` → `_pyFixed` (round-half-to-even), matching
+//   CPython float formatting.
+// - `sorted(..., reverse=True)` is a STABLE sort in CPython; JS
+//   `Array.prototype.sort` is stable in modern engines, and the comparator
+//   is written to keep equal keys in input order.
+// - The trailing `"\n".join(lines).rstrip() + "\n"` is reproduced verbatim.
+
+import type { CouncilResponse } from './clients.js';
+import { ConsensusMetadata, type Finding, type FindingScore } from './consensus.js';
+
+/**
+ * Bundle accepted by {@link render_decision_replay}.
+ *
+ * `include_member_arguments` toggles the redacted-vs-full output. When
+ * `false` the artefact emits consensus + dissent COUNT only — no per-member
+ * arguments — for sharing without leaking which model framed which point.
+ */
+export class DecisionReplayInputs {
+    readonly findings: readonly Finding[];
+    readonly scores: readonly FindingScore[];
+    readonly metadata: Map<string, ConsensusMetadata> | Record<string, ConsensusMetadata>;
+    readonly deliberation: readonly CouncilResponse[]; // last-round per-member texts
+    readonly original_ask: string;
+    readonly include_member_arguments: boolean;
+
+    constructor(args: {
+        findings: readonly Finding[];
+        scores: readonly FindingScore[];
+        metadata: Map<string, ConsensusMetadata> | Record<string, ConsensusMetadata>;
+        deliberation: readonly CouncilResponse[];
+        original_ask?: string;
+        include_member_arguments?: boolean;
+    }) {
+        this.findings = args.findings;
+        this.scores = args.scores;
+        this.metadata = args.metadata;
+        this.deliberation = args.deliberation;
+        this.original_ask = args.original_ask ?? '';
+        this.include_member_arguments = args.include_member_arguments ?? true;
+    }
+}
+
+/** Mirror Python `len(str)` — code-point count, not UTF-16 unit count. */
+function _pyLen(s: string): number {
+    let n = 0;
+    for (const _ of s) {
+        n += 1;
+    }
+    return n;
+}
+
+/**
+ * Mirror Python `" ".join(text.split())` — split on runs of (Unicode)
+ * whitespace, drop empties, re-join with a single space.
+ */
+function _pyJoinSplit(text: string): string {
+    // Python str.split() with no args splits on any whitespace run and
+    // discards leading/trailing/empty tokens.
+    const parts = text.split(/\s+/u).filter((tok) => tok.length > 0);
+    return parts.join(' ');
+}
+
+/**
+ * Mirror Python `flat[:limit].rstrip() + "…"` — slice by CODE POINT (not
+ * UTF-16 unit), then strip trailing whitespace, then append the ellipsis.
+ */
+function _pyTruncate(flat: string, limit: number): string {
+    const sliced = [...flat].slice(0, limit).join('');
+    return _pyRStrip(sliced) + '…';
+}
+
+/** Mirror Python `str.rstrip()` — strip trailing whitespace. */
+function _pyRStrip(s: string): string {
+    return s.replace(/\s+$/u, '');
+}
+
+/** Mirror Python `str.strip()` — strip whitespace both ends. */
+function _pyStrip(s: string): string {
+    return s.trim();
+}
+
+/**
+ * Format `x` to `ndigits` decimals using round-half-to-even, matching
+ * CPython float formatting (`f"{x:.2f}"` / `f"{x:.1f}"`).
+ */
+function _pyFixed(x: number, ndigits: number): string {
+    if (!Number.isFinite(x)) {
+        return String(x);
+    }
+    const neg = x < 0 || Object.is(x, -0);
+    const abs = Math.abs(x);
+    const factor = Math.pow(10, ndigits);
+    const scaled = abs * factor;
+    const floor = Math.floor(scaled);
+    const frac = scaled - floor;
+    const tol = Math.max(Math.abs(scaled), 1) * 2 ** -40;
+    let rounded: number;
+    if (Math.abs(frac - 0.5) <= tol) {
+        rounded = floor % 2 === 0 ? floor : floor + 1;
+    } else {
+        rounded = Math.round(scaled);
+    }
+    let intStr = String(rounded);
+    let result: string;
+    if (ndigits === 0) {
+        result = intStr;
+    } else {
+        if (intStr.length <= ndigits) {
+            intStr = '0'.repeat(ndigits - intStr.length + 1) + intStr;
+        }
+        const whole = intStr.slice(0, intStr.length - ndigits);
+        const dec = intStr.slice(intStr.length - ndigits);
+        result = `${whole}.${dec}`;
+    }
+    return neg ? `-${result}` : result;
+}
+
+function _metaGet(
+    metadata: Map<string, ConsensusMetadata> | Record<string, ConsensusMetadata>,
+    id: string,
+): ConsensusMetadata | undefined {
+    if (metadata instanceof Map) {
+        return metadata.get(id);
+    }
+    return Object.prototype.hasOwnProperty.call(metadata, id) ? metadata[id] : undefined;
+}
+
+/** Single-word verdict band for a consensus_strength. */
+function _verdict(strength: number): string {
+    if (strength > 0.7) {
+        return 'Strong';
+    }
+    if (strength > 0.4) {
+        return 'Moderate';
+    }
+    return 'Weak';
+}
+
+/**
+ * Return the one-line key argument for `scorer` on a finding.
+ *
+ * Prefers the scorer's `reason` field (rich, contextual) and falls back to
+ * the truncated deliberation snippet so the audit trail never surfaces an
+ * empty argument.
+ */
+function _scorer_argument(
+    scorer: string,
+    member_texts: Map<string, string>,
+    score: FindingScore | null,
+): string {
+    if (score && score.reason) {
+        let flat = _pyJoinSplit(score.reason);
+        if (_pyLen(flat) > 200) {
+            flat = _pyTruncate(flat, 199);
+        }
+        return flat;
+    }
+    const snippet = member_texts.get(scorer) ?? '';
+    let flat = _pyJoinSplit(snippet);
+    if (!flat) {
+        return 'no argument captured';
+    }
+    if (_pyLen(flat) > 200) {
+        flat = _pyTruncate(flat, 199);
+    }
+    return flat;
+}
+
+function _scores_for_finding(
+    fid: string,
+    scores: Iterable<FindingScore>,
+): Map<string, FindingScore> {
+    const out = new Map<string, FindingScore>();
+    for (const s of scores) {
+        if (s.finding_id === fid) {
+            out.set(s.scorer, s);
+        }
+    }
+    return out;
+}
+
+/**
+ * Render the `decision-replay.md` body.
+ *
+ * Sections (in order): a leading H1 plus the original ask blockquote, one
+ * `## <finding-id> — <truncated text>` block per finding (ranked by
+ * consensus_strength desc), and a trailing footer with the toggle state so
+ * consumers can tell at a glance whether arguments were redacted.
+ */
+export function render_decision_replay(inputs: DecisionReplayInputs): string {
+    const member_texts = new Map<string, string>();
+    for (const r of inputs.deliberation) {
+        member_texts.set(`${r.provider}:${r.model}`, r.text || '');
+    }
+
+    // sorted(findings, key=consensus_strength, reverse=True). CPython sort
+    // is stable; preserve input order among equal keys by indexing.
+    const ranked = inputs.findings
+        .map((f, i) => ({ f, i }))
+        .sort((a, b) => {
+            const sa = (
+                _metaGet(inputs.metadata, a.f.id) ??
+                new ConsensusMetadata({
+                    finding_id: a.f.id,
+                    consensus_strength: 0.0,
+                    dissent_count: 0,
+                    scorers: [],
+                    mean_score: 0.0,
+                })
+            ).consensus_strength;
+            const sb = (
+                _metaGet(inputs.metadata, b.f.id) ??
+                new ConsensusMetadata({
+                    finding_id: b.f.id,
+                    consensus_strength: 0.0,
+                    dissent_count: 0,
+                    scorers: [],
+                    mean_score: 0.0,
+                })
+            ).consensus_strength;
+            if (sb !== sa) {
+                return sb - sa; // reverse=True (descending)
+            }
+            return a.i - b.i; // stable tie-break on input order
+        })
+        .map((e) => e.f);
+
+    const lines: string[] = ['# Decision Replay\n'];
+    if (_pyStrip(inputs.original_ask)) {
+        let ask = _pyJoinSplit(inputs.original_ask);
+        if (_pyLen(ask) > 400) {
+            ask = _pyTruncate(ask, 399);
+        }
+        lines.push(`> ${ask}\n`);
+    }
+    if (ranked.length === 0) {
+        lines.push('*No findings were extracted for this session.*\n');
+        return _pyRStrip(lines.join('\n')) + '\n';
+    }
+    for (const f of ranked) {
+        let m = _metaGet(inputs.metadata, f.id) ?? null;
+        if (m === null) {
+            m = new ConsensusMetadata({
+                finding_id: f.id,
+                consensus_strength: 0.0,
+                dissent_count: 0,
+                scorers: [],
+                mean_score: 0.0,
+            });
+        }
+        let title = _pyJoinSplit(f.text);
+        if (_pyLen(title) > 120) {
+            title = _pyTruncate(title, 119);
+        }
+        const verdict = _verdict(m.consensus_strength);
+        lines.push(`## ${f.id} — ${title}\n`);
+        lines.push(
+            `- **Consensus**: ${verdict} (${_pyFixed(m.consensus_strength, 2)})\n` +
+                `- **Evidence quality**: ${m.evidence_quality} ` +
+                `(mean ${_pyFixed(m.mean_score, 1)}/10)\n` +
+                `- **Agreement**: ${m.concur_count}/` +
+                `${m.concur_count + m.dissent_count} members concur, ` +
+                `${m.dissent_count} dissent\n`,
+        );
+        if (inputs.include_member_arguments) {
+            const score_map = _scores_for_finding(f.id, inputs.scores);
+            const agreeing = m.scorers.filter((s) => {
+                const sc = score_map.get(s);
+                return sc !== undefined && sc.agree;
+            });
+            const dissent = m.dissent_reasons.map((pair) => pair);
+            if (agreeing.length > 0) {
+                lines.push('**Agreeing members**:');
+                for (const scorer of agreeing) {
+                    const arg = _scorer_argument(scorer, member_texts, score_map.get(scorer) ?? null);
+                    lines.push(`- _${scorer}_ — ${arg}`);
+                }
+                lines.push('');
+            }
+            if (dissent.length > 0) {
+                lines.push('**Dissenting members**:');
+                for (const [scorer] of dissent) {
+                    const arg = _scorer_argument(scorer, member_texts, score_map.get(scorer) ?? null);
+                    lines.push(`- _${scorer}_ — ${arg}`);
+                }
+                lines.push('');
+            }
+        }
+        lines.push(`**Synthesis verdict**: ${verdict} consensus — ${f.source} sourced.\n`);
+    }
+    const mode_label = inputs.include_member_arguments ? 'full' : 'redacted (counts only)';
+    lines.push(`---\n\n_artefact mode: ${mode_label}_\n`);
+    return _pyRStrip(lines.join('\n')) + '\n';
+}