crewhaus 0.1.8 → 0.2.1

package/dist/permissions-suggest.js

@@ -0,0 +1,333 @@
+/**
+ * Item 16 — `crewhaus permissions suggest`: mine persisted ask/deny history
+ * into reviewable permission rules. The pure, side-effect-free half; all
+ * filesystem access + the interactive `--apply` confirm live in
+ * `apps/cli/src/index.ts` (mirrors `advise-rules.ts`).
+ *
+ * SIGNAL SHAPE (verified against `@crewhaus/event-log` + runtime-core's
+ * advisor subscriber): the durable `permission` line is
+ * `{ toolName, decision, askOutcome }` and carries NO tool input (the input
+ * lives only on the adjacent `tool_use` line `{ id, name, input }`). Both
+ * `permission.toolName` and `tool_use.name` are the RegisteredTool's
+ * PascalCase `.name` (`Read`, `Bash`), so the two correlate directly by name.
+ * We therefore aggregate asks by toolName and derive an OPTIONAL arg glob by
+ * sampling the operative field of the tool_use inputs seen for that tool.
+ *
+ * SAFETY: permissions are deliberately EXCLUDED from OPTIMIZABLE_PATHS — an
+ * optimizer must never widen its own permissions. This module only ever
+ * PROPOSES rules; nothing here writes, and the CLI's `--apply` is always an
+ * interactive human confirm (never eval-gated). Read-only tools get
+ * `alwaysAllow` proposals first (lowest blast radius); recurring DENIED asks
+ * get an `alwaysAsk` tightening (never a blanket `alwaysDeny` — a human
+ * denied THIS call, not necessarily every future one).
+ */
+import { OPERATIVE_ARG_FIELDS as MATCHER_OPERATIVE_ARG_FIELDS, escapeGlobLiteral, } from "@crewhaus/tool-permission-matcher";
+import { payloadOf } from "./advise-rules";
+/**
+ * The operative input field(s) per built-in tool — the one a permission
+ * arg-glob constrains. Re-exported from `@crewhaus/tool-permission-matcher`
+ * (the SINGLE source of truth) so a suggested pattern always targets the SAME
+ * field the matcher checks. This was hand-copied here (a silent-desync risk);
+ * now a matcher edit propagates automatically. Keyed by the PascalCase runtime
+ * `.name`.
+ */
+export const OPERATIVE_ARG_FIELDS = MATCHER_OPERATIVE_ARG_FIELDS;
+/** Max distinct operative-arg samples kept per tool (bounds report size). */
+export const MAX_ARG_SAMPLES = 5;
+function operativeValue(toolName, input) {
+    const fields = OPERATIVE_ARG_FIELDS[toolName];
+    if (fields === undefined || input === null || typeof input !== "object")
+        return undefined;
+    const record = input;
+    for (const f of fields) {
+        const v = record[f];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Fold sessions into per-tool ask aggregates. Reads `permission` lines for
+ * the ask counts and `tool_use` lines for the operative-arg samples. Pure;
+ * tolerant of old-vintage logs (no permission lines → empty result).
+ */
+export function aggregateAsks(sessions) {
+    const byTool = new Map();
+    const get = (toolName) => {
+        let agg = byTool.get(toolName);
+        if (agg === undefined) {
+            agg = { toolName, asks: 0, approved: 0, denied: 0, argSamples: [] };
+            byTool.set(toolName, agg);
+        }
+        return agg;
+    };
+    // First pass: tool_use inputs → operative-arg sample bank per tool.
+    for (const session of sessions) {
+        for (const obj of session.objects) {
+            const tu = payloadOf(obj, "tool_use");
+            if (tu === undefined || typeof tu["name"] !== "string")
+                continue;
+            const value = operativeValue(tu["name"], tu["input"]);
+            if (value === undefined)
+                continue;
+            const agg = get(tu["name"]);
+            if (agg.argSamples.length < MAX_ARG_SAMPLES && !agg.argSamples.includes(value)) {
+                agg.argSamples.push(value);
+            }
+        }
+    }
+    // Second pass: resolved permission asks → counts.
+    for (const session of sessions) {
+        for (const obj of session.objects) {
+            const perm = payloadOf(obj, "permission");
+            if (perm === undefined || typeof perm["toolName"] !== "string")
+                continue;
+            if (perm["decision"] !== "ask")
+                continue; // allow/deny were not human prompts
+            const agg = get(perm["toolName"]);
+            agg.asks += 1;
+            if (perm["askOutcome"] === "approved")
+                agg.approved += 1;
+            else if (perm["askOutcome"] === "denied")
+                agg.denied += 1;
+        }
+    }
+    // Drop tools that only contributed arg samples but never actually prompted.
+    for (const [name, agg] of byTool)
+        if (agg.asks === 0)
+            byTool.delete(name);
+    return byTool;
+}
+export const DEFAULT_SUGGEST_THRESHOLDS = Object.freeze({
+    minAsks: 3,
+    approveRate: 1.0, // only propose a grant when EVERY ask was approved
+    denyRate: 0.5,
+});
+/** Build a name → readOnly lookup from the resolvable tool map (keyed by the
+ *  RegisteredTool `.name`, which is what the ask aggregate is keyed by). */
+export function readOnlyByName(toolMap) {
+    const out = new Map();
+    for (const t of Object.values(toolMap))
+        out.set(t.name, t.readOnly);
+    return out;
+}
+/**
+ * Compile a permission pattern for a tool. When exactly one operative-arg
+ * value recurred we emit a tool+arg glob (`Bash(git status)`); a small set of
+ * distinct values stays a bare tool glob (a per-value rule set would be noise
+ * — the human can tighten). Tools with no operative field (or no samples) get
+ * the bare tool name.
+ *
+ * SAFETY (glob widening): the observed value is a LITERAL the human approved,
+ * not a glob the human authored. tool-permission-matcher treats `*`/`?` in an
+ * arg-glob as wildcards, so splicing a raw value that contains them would make
+ * the suggested rule match unapproved siblings (`Bash(npm run test:*)` matching
+ * `Bash(npm run test:PRODUCTION-DELETE)`). We `escapeGlobLiteral` the value so
+ * the rule matches ONLY the approved string. A value containing `(`/`)` cannot
+ * be represented in the matcher's `Tool(arg)` format (its paren split isn't
+ * escape-aware), so we fall back to a bare tool glob rather than emit a rule
+ * that misparses — the reviewer can hand-write a tighter one.
+ */
+export function patternFor(agg) {
+    if (agg.argSamples.length === 1 && OPERATIVE_ARG_FIELDS[agg.toolName] !== undefined) {
+        const value = agg.argSamples[0];
+        if (!value.includes("(") && !value.includes(")")) {
+            // A single recurring operative value → a precise glob for exactly it,
+            // with glob metacharacters neutralised so it matches only the literal.
+            return `${agg.toolName}(${escapeGlobLiteral(value)})`;
+        }
+    }
+    return agg.toolName;
+}
+/**
+ * Rank ask aggregates into reviewable permission suggestions. Deterministic:
+ *   - recurring-APPROVED tools (100% approved, ≥ minAsks) → `alwaysAllow`,
+ *     read-only tools FIRST (lowest blast radius), then by approval count;
+ *   - recurring-DENIED tools (deny rate ≥ denyRate) → `alwaysAsk` tightening
+ *     (NOT alwaysDeny — a human denied a specific call, not the whole tool),
+ *     by denial count.
+ * Read-only-ness comes from the tool map; an unknown tool defaults to false
+ * (treated as non-read-only ⇒ ranked after read-only grants).
+ */
+export function rankSuggestions(aggregates, readOnly, thresholds = DEFAULT_SUGGEST_THRESHOLDS) {
+    const grants = [];
+    const tightenings = [];
+    for (const agg of aggregates.values()) {
+        if (agg.asks < thresholds.minAsks)
+            continue;
+        const ro = readOnly.get(agg.toolName) ?? false;
+        const approveRate = agg.approved / agg.asks;
+        const denyRate = agg.denied / agg.asks;
+        const pattern = patternFor(agg);
+        if (agg.denied === 0 && approveRate >= thresholds.approveRate) {
+            grants.push({
+                rule: { type: "alwaysAllow", pattern, source: "settings" },
+                reason: "recurring-approved",
+                toolName: agg.toolName,
+                readOnly: ro,
+                weight: agg.approved,
+                evidence: [
+                    `${agg.approved}/${agg.asks} ${agg.toolName} asks approved, 0 denied (threshold: ≥${thresholds.minAsks} asks, 100% approved)`,
+                    ro
+                        ? "tool is read-only — lowest blast radius to auto-allow"
+                        : "tool is NOT read-only — review the effect before granting",
+                    ...(pattern.includes("(")
+                        ? [`derived from a single recurring input: ${pattern}`]
+                        : agg.argSamples.length > 1
+                            ? [`inputs varied (${agg.argSamples.length} distinct) — proposing a bare tool grant`]
+                            : []),
+                ],
+            });
+        }
+        else if (denyRate >= thresholds.denyRate) {
+            tightenings.push({
+                rule: { type: "alwaysAsk", pattern, source: "settings" },
+                reason: "recurring-denied",
+                toolName: agg.toolName,
+                readOnly: ro,
+                weight: agg.denied,
+                evidence: [
+                    `${agg.denied}/${agg.asks} ${agg.toolName} asks DENIED (${(denyRate * 100).toFixed(0)}%, threshold: ≥${(thresholds.denyRate * 100).toFixed(0)}%)`,
+                    "proposing alwaysAsk (keep prompting) — a human denied specific calls; alwaysDeny would over-reach",
+                ],
+            });
+        }
+    }
+    // Grants: read-only first, then approval count desc, then tool name.
+    grants.sort((a, b) => {
+        if (a.readOnly !== b.readOnly)
+            return a.readOnly ? -1 : 1;
+        if (b.weight !== a.weight)
+            return b.weight - a.weight;
+        return a.toolName.localeCompare(b.toolName);
+    });
+    // Tightenings: denial count desc, then tool name.
+    tightenings.sort((a, b) => {
+        if (b.weight !== a.weight)
+            return b.weight - a.weight;
+        return a.toolName.localeCompare(b.toolName);
+    });
+    return [...grants, ...tightenings];
+}
+/**
+ * Read the existing `permissions.rules` out of a parsed `.crewhaus/settings.json`
+ * root (the EXACT shape `buildRuleSet` in index.ts consumes). Tolerant of a
+ * missing/foreign file: anything that isn't the expected shape yields `[]`.
+ */
+export function existingSettingsRules(settingsRoot) {
+    if (settingsRoot === null || typeof settingsRoot !== "object")
+        return [];
+    const perms = settingsRoot.permissions;
+    if (perms === null || typeof perms !== "object")
+        return [];
+    const rules = perms.rules;
+    if (!Array.isArray(rules))
+        return [];
+    const out = [];
+    for (const r of rules) {
+        if (r === null || typeof r !== "object")
+            continue;
+        const type = r.type;
+        const pattern = r.pattern;
+        if ((type === "alwaysAllow" || type === "alwaysDeny" || type === "alwaysAsk") &&
+            typeof pattern === "string" &&
+            pattern.length > 0) {
+            out.push({ type, pattern });
+        }
+    }
+    return out;
+}
+/**
+ * Compute the additive diff between the existing settings rules and the
+ * ranked suggestions. A suggestion whose (type, pattern) already exists is
+ * reported as already-present, never duplicated. Order-preserving: existing
+ * rules first, then new additions in suggestion rank order.
+ */
+export function diffPermissions(existing, suggestions) {
+    const key = (r) => `${r.type} ${r.pattern}`;
+    const have = new Set(existing.map(key));
+    const additions = [];
+    const alreadyPresent = [];
+    const seen = new Set(have);
+    for (const s of suggestions) {
+        const r = { type: s.rule.type, pattern: s.rule.pattern };
+        if (have.has(key(r))) {
+            alreadyPresent.push(r);
+        }
+        else if (!seen.has(key(r))) {
+            additions.push(r);
+            seen.add(key(r));
+        }
+    }
+    return { additions, alreadyPresent, merged: [...existing, ...additions] };
+}
+/**
+ * Render the settings.json `permissions` block that `--apply` would write,
+ * MERGING into the existing settings root so unrelated top-level keys
+ * (`hooks`, skills, …) survive. Returns the full new root object; the CLI
+ * JSON-stringifies it. Pure — never touches disk.
+ */
+export function applyToSettingsRoot(settingsRoot, merged) {
+    const root = settingsRoot !== null && typeof settingsRoot === "object"
+        ? { ...settingsRoot }
+        : {};
+    const existingPerms = root["permissions"] !== null && typeof root["permissions"] === "object"
+        ? { ...root["permissions"] }
+        : {};
+    root["permissions"] = { ...existingPerms, rules: merged.map((r) => ({ ...r })) };
+    return root;
+}
+// -------- rendering --------
+/** Human-readable suggestion lines for the CLI text mode. */
+export function formatSuggestionLines(suggestions) {
+    const lines = [];
+    for (const s of suggestions) {
+        lines.push(`[${s.reason}] ${s.rule.type} ${s.rule.pattern}${s.readOnly ? " (read-only)" : ""}`);
+        for (const e of s.evidence)
+            lines.push(`  · ${e}`);
+    }
+    return lines;
+}
+/**
+ * A unified-diff-ish view of the settings.json permissions change: existing
+ * rules as context, additions as `+` lines. Purely for human review — this
+ * is NOT applied unless the user confirms `--apply` interactively.
+ */
+export function formatSettingsDiff(diff) {
+    const lines = [".crewhaus/settings.json → permissions.rules:"];
+    if (diff.merged.length === 0) {
+        lines.push("  (no rules — nothing to suggest)");
+        return lines;
+    }
+    const addKeys = new Set(diff.additions.map((r) => `${r.type} ${r.pattern}`));
+    for (const r of diff.merged) {
+        const isNew = addKeys.has(`${r.type} ${r.pattern}`);
+        // Flag any UNESCAPED wildcard still present — such a rule matches multiple
+        // values (an existing hand-authored broad rule or, defensively, a
+        // suggestion that somehow kept a wildcard). Suggested rules escape their
+        // literals in patternFor, so a `+` line should never trip this.
+        const warn = hasUnescapedWildcard(r.pattern) ? " (⚠ wildcard — matches multiple)" : "";
+        lines.push(`  ${isNew ? "+" : " "} { type: ${r.type}, pattern: ${JSON.stringify(r.pattern)} }${warn}`);
+    }
+    if (diff.additions.length === 0) {
+        lines.push("  (all suggestions already present — nothing to add)");
+    }
+    return lines;
+}
+/**
+ * True when a pattern contains a glob wildcard (`*`/`?`) that is NOT
+ * backslash-escaped — i.e. one the matcher will treat as widening. A `\\*`/`\\?`
+ * (a literal escaped by `escapeGlobLiteral`) does not count.
+ */
+export function hasUnescapedWildcard(pattern) {
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\") {
+            i++; // skip the escaped char — it's a literal, not a wildcard
+            continue;
+        }
+        if (ch === "*" || ch === "?")
+            return true;
+    }
+    return false;
+}

package/dist/pii-tune.d.ts

@@ -0,0 +1,107 @@
+import { type PiiPolicyFile } from "@crewhaus/pii-redactor";
+/**
+ * AUTOMATION-OPPORTUNITIES.md item 51 — `crewhaus pii tune` core: aggregate
+ * PII-redaction history across sessions to find (a) high-frequency FALSE-
+ * POSITIVE over-redaction candidates and (b) detector coverage gaps, and
+ * propose a reviewed `.crewhaus/pii-policy.json` the redactor consults
+ * additively. Side-effect-free so it is unit-testable (all filesystem access
+ * lives in index.ts), mirroring `advise-rules.ts` / `egress-triage.ts`.
+ *
+ * NO-RAW-PII INVARIANT (the whole point of item 51): this module NEVER stores,
+ * prints, or returns a raw PII value. Every value is reduced to
+ * `HMAC-SHA256(secret, value)` (via `@crewhaus/pii-redactor`'s `hmacValue` —
+ * the SAME digest the redactor's hash-mode marker and hashed allow-list use)
+ * the instant it is detected. Aggregation, the proposed policy, and every
+ * renderer carry only { kind, hash, count } — so a proposed allow entry can be
+ * matched by the redactor at runtime WITHOUT anyone ever seeing the value. The
+ * tests assert a known raw value never appears in any output.
+ *
+ * WHERE THE SIGNAL COMES FROM (durability, verified 2026-07): the pii-redactor
+ * has no runtime writer emitting durable redaction events, so `pii tune` re-
+ * derives the redaction history by running the detector over durable session
+ * `tool_result` + assistant content itself (the durable surface), hashing each
+ * hit immediately. It cross-references `.crewhaus/feedback` ratings: a PII
+ * (kind, hash) that recurs in the outputs of turns the human UP-RATED/accepted
+ * is an over-redaction candidate — the operator kept the answer that carried
+ * it, so redacting it may be too aggressive. Coverage gaps are kinds seen only
+ * via the classifier sentinel or at the detector's edges.
+ */
+export type HashedPiiKey = {
+    readonly kind: string;
+    readonly hash: string;
+};
+export type PiiAggregate = {
+    readonly kind: string;
+    readonly hash: string;
+    /** Total occurrences across scanned content. */
+    readonly count: number;
+    /** Occurrences in content from turns the human up-rated/accepted. */
+    readonly acceptedCount: number;
+};
+export type PiiTuneContext = {
+    /** Per (kind, hash) aggregate, ranked by acceptedCount then count. */
+    readonly aggregates: ReadonlyArray<PiiAggregate>;
+    /** Total PII hits detected across all scanned content. */
+    readonly totalHits: number;
+    /** Per-kind totals (coverage view). */
+    readonly byKind: Readonly<Record<string, number>>;
+    /** Content units scanned. */
+    readonly scanned: number;
+};
+/** A single unit of scanned content plus whether its turn was accepted. */
+export type ScanUnit = {
+    readonly content: string;
+    /** True when the human up-rated/accepted the turn this content belongs to. */
+    readonly accepted: boolean;
+};
+/**
+ * Fold scan units into the hashed aggregate. `secret` is the HMAC key (never
+ * stored); each detected value is hashed immediately and the raw value is
+ * dropped. Detectors default to the shipped `DEFAULT_PII_DETECTORS`.
+ */
+export declare function buildPiiTuneContext(units: ReadonlyArray<ScanUnit>, secret: string, detectors?: readonly import("@crewhaus/grader-safety-classifiers").PiiDetector[]): PiiTuneContext;
+export type PiiTuneThresholds = {
+    /** Occurrences in ACCEPTED outputs at/above which a (kind,hash) is a
+     *  false-positive over-redaction candidate. */
+    readonly acceptedMin: number;
+    /** Total occurrences at/above which a (kind,hash) is judged at all. */
+    readonly countMin: number;
+};
+export declare const DEFAULT_PII_TUNE_THRESHOLDS: PiiTuneThresholds;
+export type FalsePositiveCandidate = {
+    readonly kind: string;
+    readonly hash: string;
+    readonly count: number;
+    readonly acceptedCount: number;
+    /** acceptedCount / count — how consistently this value survived into kept
+     *  outputs (1.0 = every occurrence was in an accepted turn). */
+    readonly acceptedRatio: number;
+};
+/**
+ * Find false-positive over-redaction candidates: (kind, hash) pairs seen ≥
+ * countMin times whose occurrences land in ACCEPTED outputs ≥ acceptedMin
+ * times. These are values the human kept, so redacting them may be too
+ * aggressive — they become proposed hashed allow entries.
+ */
+export declare function findFalsePositives(ctx: PiiTuneContext, thresholds?: PiiTuneThresholds): FalsePositiveCandidate[];
+export type CoverageGap = {
+    readonly reason: string;
+    readonly detail: string;
+};
+/**
+ * Detect detector coverage gaps. Deliberately conservative and structural (no
+ * raw content): kinds present in the shipped detectors that produced ZERO hits
+ * over a non-trivial scan (either the content genuinely lacks them, or the
+ * detector under-fires) are surfaced as "verify coverage" notes, and a scan
+ * with hits but NO email/ssn/credit_card at all over many units is flagged as
+ * a possible high-value-PII blind spot worth a custom detector.
+ */
+export declare function findCoverageGaps(ctx: PiiTuneContext, detectorKinds?: ReadonlyArray<string>): CoverageGap[];
+/**
+ * Turn false-positive candidates into a reviewed `PiiPolicyFile`. Carries ONLY
+ * hashed allow entries — never raw PII — so it is safe to commit and the
+ * redactor can honour it additively via `createPiiRedactorWithPolicy`.
+ * Deterministic given the candidates.
+ */
+export declare function buildPiiPolicy(candidates: ReadonlyArray<FalsePositiveCandidate>): PiiPolicyFile;
+export declare function renderPiiTuneLines(ctx: PiiTuneContext, candidates: ReadonlyArray<FalsePositiveCandidate>, gaps: ReadonlyArray<CoverageGap>): ReadonlyArray<string>;

package/dist/pii-tune.js

@@ -0,0 +1,122 @@
+import { DEFAULT_PII_DETECTORS, detectPii, hmacValue, } from "@crewhaus/pii-redactor";
+/**
+ * Fold scan units into the hashed aggregate. `secret` is the HMAC key (never
+ * stored); each detected value is hashed immediately and the raw value is
+ * dropped. Detectors default to the shipped `DEFAULT_PII_DETECTORS`.
+ */
+export function buildPiiTuneContext(units, secret, detectors = DEFAULT_PII_DETECTORS) {
+    const byKey = new Map();
+    const byKind = new Map();
+    let totalHits = 0;
+    for (const unit of units) {
+        const hits = detectPii(unit.content, detectors);
+        for (const hit of hits) {
+            if (hit.value.length === 0)
+                continue; // classifier sentinel has no value
+            const hash = hmacValue(hit.value, secret);
+            const key = `${hit.kind}|${hash}`;
+            const acc = byKey.get(key) ?? { kind: hit.kind, hash, count: 0, acceptedCount: 0 };
+            acc.count += 1;
+            if (unit.accepted)
+                acc.acceptedCount += 1;
+            byKey.set(key, acc);
+            byKind.set(hit.kind, (byKind.get(hit.kind) ?? 0) + 1);
+            totalHits += 1;
+        }
+    }
+    const aggregates = [...byKey.values()]
+        .map((a) => ({ kind: a.kind, hash: a.hash, count: a.count, acceptedCount: a.acceptedCount }))
+        .sort((x, y) => y.acceptedCount - x.acceptedCount ||
+        y.count - x.count ||
+        x.kind.localeCompare(y.kind) ||
+        x.hash.localeCompare(y.hash));
+    return {
+        aggregates,
+        totalHits,
+        byKind: Object.fromEntries([...byKind.entries()].sort()),
+        scanned: units.length,
+    };
+}
+export const DEFAULT_PII_TUNE_THRESHOLDS = {
+    acceptedMin: 2,
+    countMin: 3,
+};
+/**
+ * Find false-positive over-redaction candidates: (kind, hash) pairs seen ≥
+ * countMin times whose occurrences land in ACCEPTED outputs ≥ acceptedMin
+ * times. These are values the human kept, so redacting them may be too
+ * aggressive — they become proposed hashed allow entries.
+ */
+export function findFalsePositives(ctx, thresholds = DEFAULT_PII_TUNE_THRESHOLDS) {
+    const out = [];
+    for (const a of ctx.aggregates) {
+        if (a.count < thresholds.countMin)
+            continue;
+        if (a.acceptedCount < thresholds.acceptedMin)
+            continue;
+        out.push({
+            kind: a.kind,
+            hash: a.hash,
+            count: a.count,
+            acceptedCount: a.acceptedCount,
+            acceptedRatio: a.count > 0 ? a.acceptedCount / a.count : 0,
+        });
+    }
+    // Highest acceptedRatio (then acceptedCount) first — the strongest FPs.
+    return out.sort((x, y) => y.acceptedRatio - x.acceptedRatio ||
+        y.acceptedCount - x.acceptedCount ||
+        x.kind.localeCompare(y.kind));
+}
+/**
+ * Detect detector coverage gaps. Deliberately conservative and structural (no
+ * raw content): kinds present in the shipped detectors that produced ZERO hits
+ * over a non-trivial scan (either the content genuinely lacks them, or the
+ * detector under-fires) are surfaced as "verify coverage" notes, and a scan
+ * with hits but NO email/ssn/credit_card at all over many units is flagged as
+ * a possible high-value-PII blind spot worth a custom detector.
+ */
+export function findCoverageGaps(ctx, detectorKinds = DEFAULT_PII_DETECTORS.map((d) => d.kind)) {
+    const gaps = [];
+    if (ctx.scanned < 5)
+        return gaps; // too little to judge coverage
+    const seen = new Set(Object.keys(ctx.byKind));
+    const missing = detectorKinds.filter((k) => !seen.has(k)).sort();
+    if (missing.length > 0) {
+        gaps.push({
+            reason: "detector-kinds-never-fired",
+            detail: `detector kinds with 0 hits over ${ctx.scanned} scanned unit(s): ${missing.join(", ")} — either the content lacks them or the pattern under-fires; verify against a known-positive sample before trusting coverage`,
+        });
+    }
+    return gaps;
+}
+// -------- policy file proposal --------
+/**
+ * Turn false-positive candidates into a reviewed `PiiPolicyFile`. Carries ONLY
+ * hashed allow entries — never raw PII — so it is safe to commit and the
+ * redactor can honour it additively via `createPiiRedactorWithPolicy`.
+ * Deterministic given the candidates.
+ */
+export function buildPiiPolicy(candidates) {
+    const allow = candidates
+        .map((c) => ({ kind: c.kind, hash: c.hash }))
+        .sort((a, b) => a.kind.localeCompare(b.kind) || a.hash.localeCompare(b.hash));
+    return { version: 1, allow };
+}
+// -------- renderers (hashes + counts ONLY, never raw values) --------
+export function renderPiiTuneLines(ctx, candidates, gaps) {
+    const lines = [];
+    lines.push(`scanned ${ctx.scanned} content unit(s): ${ctx.totalHits} PII hit(s) across ${Object.keys(ctx.byKind).length} kind(s)`);
+    const kindLine = Object.entries(ctx.byKind)
+        .map(([k, n]) => `${k}=${n}`)
+        .join(", ");
+    if (kindLine !== "")
+        lines.push(`  by kind: ${kindLine}`);
+    lines.push(`false-positive over-redaction candidates: ${candidates.length}`);
+    for (const c of candidates) {
+        // Hash + counts ONLY — the raw value is never available here.
+        lines.push(`  ~ ${c.kind}:${c.hash} — kept in ${c.acceptedCount}/${c.count} accepted output(s) (${(c.acceptedRatio * 100).toFixed(0)}% accepted) → propose allow`);
+    }
+    for (const g of gaps)
+        lines.push(`coverage: ${g.detail}`);
+    return lines;
+}

package/dist/propose.d.ts

@@ -0,0 +1,117 @@
+import { type SpecDiffEntry } from "@crewhaus/spec-patch";
+/** Thrown for operational failures (unreadable spec, no change, driver
+ *  failure). The CLI routes the message through `die()`; tests assert on
+ *  `.message`. */
+export declare class ProposeError extends Error {
+    readonly name = "ProposeError";
+}
+/** Where a proposal's review bundle lands within the repo. */
+export declare const PROPOSALS_RELDIR = ".crewhaus/proposals";
+export type ProposeSource = "optimize" | "advise" | "model-scan" | "manual";
+/** sha256 hex of a spec's bytes — the patch identity carried into provenance. */
+export declare function specContentHash(yaml: string): string;
+export type EvalDelta = {
+    readonly scoreBefore: number;
+    readonly scoreAfter: number;
+    readonly datasetName?: string;
+};
+export type ProposalProvenance = {
+    readonly source: ProposeSource;
+    readonly specName: string;
+    /** sha256 of the proposed spec bytes. */
+    readonly patchHash: string;
+    /** The optimize/advise run id, when the proposal came from one. */
+    readonly runId?: string;
+    readonly generatedAt: string;
+};
+/** The machine-readable half of the review bundle (`patch.json`). */
+export type ProposalPatch = {
+    readonly specName: string;
+    readonly diff: ReadonlyArray<SpecDiffEntry>;
+    readonly provenance: ProposalProvenance;
+    readonly evalDelta?: EvalDelta;
+};
+export type AssembleProposalOptions = {
+    readonly specName: string;
+    readonly currentYaml: string;
+    readonly proposedYaml: string;
+    readonly source: ProposeSource;
+    readonly runId?: string;
+    readonly evalDelta?: EvalDelta;
+    /** Optimize run dir whose provenance the changelog entry folds in. */
+    readonly optimizeRootDir?: string;
+    readonly patchJsonPath?: string;
+    readonly proposedVersion: string;
+    readonly now?: () => Date;
+};
+export type AssembledProposal = {
+    readonly patch: ProposalPatch;
+    /** `patch.json` text. */
+    readonly patchJson: string;
+    /** The rendered CHANGELOG entry for the proposed version. */
+    readonly changelogEntry: string;
+    readonly prTitle: string;
+    readonly prBody: string;
+    /** Whether the proposed spec differs structurally from the current one. */
+    readonly hasStructuralChange: boolean;
+};
+/**
+ * Assemble the review bundle from current + proposed spec YAML. Pure — no
+ * filesystem, no git. Throws when the proposed spec is byte-identical to the
+ * current one (nothing to propose); a structurally-empty-but-reformatted
+ * change is allowed through with a note (comments matter to reviewers).
+ */
+export declare function assembleProposal(opts: AssembleProposalOptions): AssembledProposal;
+/** The write-and-open plan the driver executes: which files to write, the
+ *  branch, and the PR title/body. Assembled purely; the driver is the only
+ *  side-effect surface. */
+export type ProposalPrPlan = {
+    readonly branch: string;
+    readonly title: string;
+    readonly body: string;
+    /** repo-relative path → contents to write on the branch. */
+    readonly files: Readonly<Record<string, string>>;
+    /** Commit message for the single proposal commit. */
+    readonly commitMessage: string;
+};
+/** Slug-safe proposal id: `<spec>-<version>-<shorthash>-<stamp>`. */
+export declare function proposalId(specName: string, version: string, patchHash: string, now: Date): string;
+export type BuildPrPlanOptions = {
+    readonly assembled: AssembledProposal;
+    /** The proposed spec YAML — written to the harness's spec file on the branch. */
+    readonly proposedYaml: string;
+    /** Repo-relative path of the harness spec file (e.g. "crewhaus.yaml"). */
+    readonly specRelPath: string;
+    readonly proposedVersion: string;
+    readonly now?: () => Date;
+};
+/** Assemble the branch/commit/PR plan + the review-bundle files. Pure. */
+export declare function buildProposalPrPlan(opts: BuildPrPlanOptions): {
+    readonly plan: ProposalPrPlan;
+    readonly proposalId: string;
+};
+/**
+ * Driver seam: execute a `ProposalPrPlan` against a real repo (branch → write
+ * files → commit → push → `gh pr create`) and resolve to the opened PR. The
+ * CLI wires this to git + gh (through `GITHUB_TOKEN`); tests inject a stub
+ * that records the plan and returns a fixed PR ref. The driver MUST NOT
+ * auto-merge.
+ */
+export type GitPrDriver = (plan: ProposalPrPlan) => Promise<OpenedPr>;
+export type OpenedPr = {
+    readonly prNumber?: number;
+    readonly url: string;
+    readonly branch: string;
+};
+export type GovernanceProposalPayload = {
+    readonly source: ProposeSource;
+    readonly specName: string;
+    readonly patchHash: string;
+    readonly proposedVersion: string;
+    readonly evalDelta?: EvalDelta;
+    readonly prNumber?: number;
+    readonly prUrl?: string;
+    readonly branch: string;
+    readonly ts: number;
+};
+export declare function buildProposalAuditPayload(assembled: AssembledProposal, opened: OpenedPr, proposedVersion: string, now: () => number): GovernanceProposalPayload;