@groundnuty/macf 0.2.36 → 0.2.38

package/dist/cli/propose/candidates.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure candidate-proposal pipeline for the auditor Plan membrane
+ * (groundnuty/macf#503, DR-026 G1). This is the Analyze→Plan half of the
+ * MAPE-K loop: turn F4's reflection signals into RATIFIABLE proposals.
+ *
+ * Everything here is deterministic CODE scaffolding. The LLM judgment (is this a
+ * real rule? is the text precise? is the tier right?) is NOT encoded — the code
+ * assembles the AGENT-AUTHORED signal content (`signal`/`proposed_tier`/
+ * `rationale` from `rule_evolution_signals`) into structured proposals and
+ * applies three LOAD-BEARING, mechanical safety gates:
+ *
+ *   GATE 1 — N>1 = distinct AGENTS, not occurrences. A candidate is promotable
+ *     only if it recurs across ≥ threshold DISTINCT `agent.name`s. Five hits from
+ *     ONE agent is N=1 → HELD (reflection ≠ verification). We count the set of
+ *     distinct agent names, never raw occurrences.
+ *
+ *   GATE 3 — no-auto-drop on invariant-touch. Step 4 SURFACES which protected
+ *     invariants a candidate touches + flags apparent-relaxations HIGH-RISK, but
+ *     NEVER drops/rejects in code. The amendment clause lets the auditor PROPOSE
+ *     an operator-ratified amendment, so auto-dropping would foreclose that path.
+ *     (GATE 2 — dry-run-by-default — lives in the orchestrator/command + writer
+ *     seam, not here.)
+ *
+ * The tier-router (step 3) groups by the `proposed_tier` HINT and marks
+ * `universal` candidates NEEDS-CONFIRMATION (never auto-route a universal
+ * promotion — it affects every deployment). The hint is a hint, not a decision.
+ */
+import type { ReflectionRecord } from '@groundnuty/macf-core';
+import { type InvariantTouch, type ProtectedInvariant } from './invariants.js';
+/** Default distinct-agent threshold for promotion (configurable). */
+export declare const DEFAULT_MIN_AGENTS = 2;
+/**
+ * The router routing decision for a candidate, derived from its `proposed_tier`
+ * HINT. `needs-confirmation` is the universal/canonical case (never auto-route);
+ * `project-draft` is the local-project-rule case; `review` is anything else (an
+ * unrecognised tier hint still surfaces, routed for plain operator review).
+ */
+export type RouteDecision = 'needs-confirmation' | 'project-draft' | 'review';
+/** A fully-assembled, ratifiable candidate proposal (a survivor of GATE 1). */
+export interface ProposalCandidate {
+    /** Dedup handle: the signal `key` when present, else the signal text. */
+    readonly handle: string;
+    /** Whether the grouping used an explicit `key` (vs falling back to text). */
+    readonly hasKey: boolean;
+    /** The agent-authored proposed tier HINT (verbatim). */
+    readonly proposedTier: string;
+    /** Representative agent-authored signal text. */
+    readonly signal: string;
+    /** All distinct agent-authored rationales contributing this candidate. */
+    readonly rationales: readonly string[];
+    /** Distinct agent names that corroborated this candidate (GATE 1 unit). */
+    readonly corroboratingAgents: readonly string[];
+    /** Distinct-agent count == corroboratingAgents.length (the GATE-1 number). */
+    readonly distinctAgents: number;
+    /** Raw occurrence count (records carrying this signal) — informational only. */
+    readonly occurrences: number;
+    /** Router decision from the tier hint. */
+    readonly route: RouteDecision;
+    /** Protected invariants this candidate plausibly touches (SURFACED, GATE 3). */
+    readonly invariantTouches: readonly InvariantTouch[];
+    /** True when the text reads like a relaxation → HIGH-RISK flag (GATE 3). */
+    readonly highRisk: boolean;
+}
+/** A candidate HELD below the distinct-agent threshold (reported, not dropped). */
+export interface HeldCandidate {
+    readonly handle: string;
+    readonly hasKey: boolean;
+    readonly proposedTier: string;
+    readonly signal: string;
+    readonly distinctAgents: number;
+    readonly occurrences: number;
+    /** Why it was held — always the N<threshold reason for v1. */
+    readonly reason: string;
+}
+/** The full pipeline output: survivors + held + the threshold used. */
+export interface CandidateSet {
+    readonly minAgents: number;
+    readonly promoted: readonly ProposalCandidate[];
+    readonly held: readonly HeldCandidate[];
+}
+/** Route a candidate from its tier hint (universal/canonical never auto-route). */
+export declare function routeForTier(proposedTier: string): RouteDecision;
+/**
+ * Run the full candidate pipeline over the reflection records.
+ *
+ * Steps (DR-026 G1 §The command):
+ *   1. Aggregate signals (distinct-agent grouping).
+ *   2. GATE 1 — keep candidates with distinctAgents ≥ minAgents; the rest go to
+ *      `held` (visible, never silently dropped).
+ *   3. Tier-router — universal/canonical → needs-confirmation; project → draft.
+ *   4. Subordination-check — surface touched invariants + HIGH-RISK relaxation
+ *      flag. NEVER drops (GATE 3).
+ */
+export declare function buildCandidates(records: readonly ReflectionRecord[], invariants: readonly ProtectedInvariant[], minAgents?: number): CandidateSet;
+//# sourceMappingURL=candidates.d.ts.map

package/dist/cli/propose/candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/cli/propose/candidates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAuB,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAEzB,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAKpC;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAAG,eAAe,GAAG,QAAQ,CAAC;AAE9E,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,EAAE,SAAS,cAAc,EAAE,CAAC;IACrD,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;CACzC;AA6DD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAKhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,SAAS,GAAE,MAA2B,GACrC,YAAY,CA2Dd"}

package/dist/cli/propose/candidates.js

@@ -0,0 +1,117 @@
+import { invariantsTouched, readsAsRelaxation, } from './invariants.js';
+/** Default distinct-agent threshold for promotion (configurable). */
+export const DEFAULT_MIN_AGENTS = 2;
+/** Tier values that must never auto-route (affect every deployment). */
+const UNIVERSAL_TIERS = new Set(['universal', 'canonical']);
+/** Group key: same handle proposed at two tiers → two distinct candidates. */
+function groupKey(tier, handle) {
+    return JSON.stringify([tier, handle]);
+}
+/**
+ * Group all reflection rule-evolution signals by (proposed_tier, handle),
+ * accumulating the SET OF DISTINCT AGENT NAMES (not occurrences) for GATE 1.
+ *
+ * This is the load-bearing distinction from F4's `aggregateSignals`, which
+ * counts occurrences. Five signals from one agent collapse to a single-agent
+ * set here; five from five agents collapse to a five-agent set.
+ */
+function groupSignals(records) {
+    const byKey = new Map();
+    for (const rec of records) {
+        const agentName = rec.agent.name;
+        for (const sig of rec.rule_evolution_signals) {
+            const hasKey = typeof sig.key === 'string' && sig.key.length > 0;
+            const handle = hasKey ? sig.key : sig.signal;
+            const k = groupKey(sig.proposed_tier, handle);
+            let g = byKey.get(k);
+            if (!g) {
+                g = {
+                    handle,
+                    hasKey,
+                    proposedTier: sig.proposed_tier,
+                    signal: sig.signal,
+                    agents: new Set(),
+                    rationales: [],
+                    occurrences: 0,
+                };
+                byKey.set(k, g);
+            }
+            g.agents.add(agentName);
+            g.occurrences += 1;
+            const rationale = sig.rationale.trim();
+            if (rationale.length > 0 && !g.rationales.includes(rationale)) {
+                g.rationales.push(rationale);
+            }
+        }
+    }
+    return [...byKey.values()];
+}
+/** Route a candidate from its tier hint (universal/canonical never auto-route). */
+export function routeForTier(proposedTier) {
+    const tier = proposedTier.trim().toLowerCase();
+    if (UNIVERSAL_TIERS.has(tier))
+        return 'needs-confirmation';
+    if (tier === 'project')
+        return 'project-draft';
+    return 'review';
+}
+/**
+ * Run the full candidate pipeline over the reflection records.
+ *
+ * Steps (DR-026 G1 §The command):
+ *   1. Aggregate signals (distinct-agent grouping).
+ *   2. GATE 1 — keep candidates with distinctAgents ≥ minAgents; the rest go to
+ *      `held` (visible, never silently dropped).
+ *   3. Tier-router — universal/canonical → needs-confirmation; project → draft.
+ *   4. Subordination-check — surface touched invariants + HIGH-RISK relaxation
+ *      flag. NEVER drops (GATE 3).
+ */
+export function buildCandidates(records, invariants, minAgents = DEFAULT_MIN_AGENTS) {
+    const threshold = Number.isFinite(minAgents) && minAgents >= 1 ? Math.floor(minAgents) : DEFAULT_MIN_AGENTS;
+    const groups = groupSignals(records);
+    const promoted = [];
+    const held = [];
+    for (const g of groups) {
+        const distinctAgents = g.agents.size;
+        if (distinctAgents < threshold) {
+            held.push({
+                handle: g.handle,
+                hasKey: g.hasKey,
+                proposedTier: g.proposedTier,
+                signal: g.signal,
+                distinctAgents,
+                occurrences: g.occurrences,
+                reason: `N=${distinctAgents} distinct agent(s) < threshold ${threshold} (reflection ≠ verification)`,
+            });
+            continue;
+        }
+        // Step 4 — subordination-check surfacing (GATE 3: surface, never drop).
+        const candidateText = [g.signal, ...g.rationales].join('\n');
+        const touches = invariantsTouched(candidateText, invariants);
+        const highRisk = readsAsRelaxation(candidateText) && touches.length > 0;
+        promoted.push({
+            handle: g.handle,
+            hasKey: g.hasKey,
+            proposedTier: g.proposedTier,
+            signal: g.signal,
+            rationales: g.rationales,
+            corroboratingAgents: [...g.agents].sort(),
+            distinctAgents,
+            occurrences: g.occurrences,
+            route: routeForTier(g.proposedTier),
+            invariantTouches: touches,
+            highRisk,
+        });
+    }
+    // Strongest corroboration first, then high-risk surfaced near the top so the
+    // operator sees the constitutional-scrutiny candidates early.
+    promoted.sort((a, b) => Number(b.highRisk) - Number(a.highRisk) ||
+        b.distinctAgents - a.distinctAgents ||
+        a.proposedTier.localeCompare(b.proposedTier) ||
+        a.handle.localeCompare(b.handle));
+    held.sort((a, b) => b.distinctAgents - a.distinctAgents ||
+        a.proposedTier.localeCompare(b.proposedTier) ||
+        a.handle.localeCompare(b.handle));
+    return { minAgents: threshold, promoted, held };
+}
+//# sourceMappingURL=candidates.js.map

package/dist/cli/propose/candidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.js","sourceRoot":"","sources":["../../../src/cli/propose/candidates.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,iBAAiB,EACjB,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC;AAEzB,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,wEAAwE;AACxE,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAqE5D,8EAA8E;AAC9E,SAAS,QAAQ,CAAC,IAAY,EAAE,MAAc;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,OAAoC;IACxD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,sBAAwD,EAAE,CAAC;YAC/E,MAAM,MAAM,GAAG,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;YAC9C,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;YAC9C,IAAI,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACrB,IAAI,CAAC,CAAC,EAAE,CAAC;gBACP,CAAC,GAAG;oBACF,MAAM;oBACN,MAAM;oBACN,YAAY,EAAE,GAAG,CAAC,aAAa;oBAC/B,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,MAAM,EAAE,IAAI,GAAG,EAAU;oBACzB,UAAU,EAAE,EAAE;oBACd,WAAW,EAAE,CAAC;iBACf,CAAC;gBACF,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;YACnB,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9D,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,YAAoB;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,oBAAoB,CAAC;IAC3D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC;IAC/C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAoC,EACpC,UAAyC,EACzC,YAAoB,kBAAkB;IAEtC,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAC5G,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QACrC,IAAI,cAAc,GAAG,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC;gBACR,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,YAAY,EAAE,CAAC,CAAC,YAAY;gBAC5B,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,cAAc;gBACd,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,MAAM,EAAE,KAAK,cAAc,kCAAkC,SAAS,8BAA8B;aACrG,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,wEAAwE;QACxE,MAAM,aAAa,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,iBAAiB,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QAExE,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,mBAAmB,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;YACzC,cAAc;YACd,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;YACnC,gBAAgB,EAAE,OAAO;YACzB,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CACX,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;QACvC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc;QACnC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CACnC,CAAC;IACF,IAAI,CAAC,IAAI,CACP,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc;QACnC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC;QAC5C,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CACnC,CAAC;IAEF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC"}

package/dist/cli/propose/invariants.d.ts

@@ -0,0 +1,49 @@
+/** One protected invariant, parsed from the ratified design doc. */
+export interface ProtectedInvariant {
+    /** 1-based ordinal as it appears in the doc. */
+    readonly index: number;
+    /** Short bold title (the text before the first period of the list item). */
+    readonly title: string;
+    /** The full list-item line (title + gloss + refs). */
+    readonly text: string;
+    /** Lowercased keyword tokens used for the heuristic touch-match. */
+    readonly keywords: readonly string[];
+}
+/** A surfaced touchpoint: which invariant a candidate plausibly touches. */
+export interface InvariantTouch {
+    readonly index: number;
+    readonly title: string;
+    /** Tokens that matched (for operator transparency). */
+    readonly matchedKeywords: readonly string[];
+}
+/**
+ * Parse the invariant list out of `protected-invariants.md`.
+ *
+ * The doc's invariants are an ordered Markdown list, each item shaped like:
+ *   `1. **Reporter-owns-closure accountability.** The agent who ... (refs)`
+ * We extract the bold title, the full line, and a keyword set (title words minus
+ * stopwords, plus the curated set for that ordinal).
+ */
+export declare function parseInvariants(markdown: string): readonly ProtectedInvariant[];
+/**
+ * Load the protected-invariant set from the repo's `design/protected-invariants.md`.
+ *
+ * `repoRoot` is the framework-source repo root (where `design/` lives). Returns
+ * `[]` (never throws) when the file is absent — the membrane still runs and the
+ * subordination-check simply surfaces nothing (loud-but-proceeds). A missing
+ * invariant file is surfaced separately by the caller.
+ */
+export declare function loadInvariants(repoRoot: string): readonly ProtectedInvariant[];
+/**
+ * For a candidate's combined text, return which invariants it plausibly touches.
+ *
+ * A touch is recorded when ANY of the invariant's keywords appears (as a
+ * substring) in the candidate text. Generous by design (see module header).
+ */
+export declare function invariantsTouched(candidateText: string, invariants: readonly ProtectedInvariant[]): readonly InvariantTouch[];
+/**
+ * Whether the candidate text reads like it RELAXES a guarantee. Heuristic only —
+ * a `true` here means "flag HIGH-RISK for operator scrutiny", NOT "drop".
+ */
+export declare function readsAsRelaxation(candidateText: string): boolean;
+//# sourceMappingURL=invariants.d.ts.map

package/dist/cli/propose/invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../../../src/cli/propose/invariants.ts"],"names":[],"mappings":"AAuBA,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAgCD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAmB/E;AAkCD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAU9E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,kBAAkB,EAAE,GACxC,SAAS,cAAc,EAAE,CAU3B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEhE"}

package/dist/cli/propose/invariants.js

@@ -0,0 +1,154 @@
+/**
+ * Protected-invariant loader + subordination-check heuristics for the auditor
+ * Plan membrane (groundnuty/macf#503, DR-026 G1).
+ *
+ * Loads `design/protected-invariants.md` (the ratified SECP guardrail core) and
+ * surfaces, for a given candidate's text, WHICH invariant(s) it plausibly
+ * touches and whether the text *reads like* a relaxation of one.
+ *
+ * CRITICAL — this module SURFACES; it never decides. `protected-invariants.md`
+ * carries an amendment clause: the auditor may *propose* an operator-ratified
+ * amendment to an invariant, so auto-dropping a candidate that touches one would
+ * foreclose that constitutional path. We therefore mark — never reject. The
+ * weaken-vs-amend call is the operator's (v1-manual) and, later, G3's.
+ *
+ * The match is a deliberately simple keyword/heuristic pass on the invariant
+ * titles + a small curated keyword set per invariant. It is intentionally
+ * generous (favours surfacing a touch over missing one): a false-positive
+ * "touches invariant N" is cheap (operator eyeballs it), a false-negative is the
+ * dangerous direction.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Per-invariant curated keyword sets. Keyed by the 1-based ordinal in
+ * `protected-invariants.md`. These augment the auto-extracted title words so the
+ * touch-match catches paraphrases the title alone would miss (e.g. "merge"
+ * mapping to the LGTM-gate invariant). Lowercase, matched as word-ish substrings.
+ */
+const CURATED_KEYWORDS = {
+    1: ['reporter', 'closure', 'close', 'owns', 'verify', 'verification'],
+    2: ['identity', 'attribution', 'attributed', 'bot', 'token', 'impersonat'],
+    3: ['merge', 'self-merge', 'lgtm', 'approve', 'approved', 'review', 'non-author'],
+    4: ['routing', 'route', 'mention', '@mention', 'recipient', 'false-route'],
+    5: ['auto-close', 'closes', 'fixes', 'resolves', 'refs', 'keyword'],
+    6: ['fail-loud', 'silent', 'fallback', 'result-invariant', 'exit code', 'assert'],
+    7: ['pr', 'pull request', 'artifact', 'rollback', 'review', 'ci'],
+    8: ['auditor', 'never-acts', 'propose', 'proposes', 'merge', 'close', 'implement', 'act'],
+    9: ['operator', 'ratifier', 'ratify', 'ratification', 'auto-applied', 'constitutional', 'human'],
+    10: ['universal', 'locally', 'local', 'mutable', 'patch', 'upstream', 'product rule'],
+};
+/** Words too generic to be a meaningful touch-signal on their own. */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'not', 'never', 'over', 'must', 'any',
+    'every', 'that', 'this', 'its', 'are', 'all', 'who', 'how', 'a', 'an',
+    'is', 'to', 'of', 'or', 'on', 'by', 'be', 'it', 'as', 'no',
+]);
+/** Phrases in candidate text that read like a *relaxation* of a guarantee. */
+const RELAXATION_HINT = /\b(?:relax|weaken|loosen|drop|remove|skip|bypass|disable|waive|exempt|optional(?:ly)?|allow(?:ed|s)?\s+(?:self|auto|without)|no\s+longer\s+(?:require|need)|without\s+(?:a\s+)?(?:review|approval|mention|token)|self-merge|auto-merge|auto-close)\b/i;
+/**
+ * Parse the invariant list out of `protected-invariants.md`.
+ *
+ * The doc's invariants are an ordered Markdown list, each item shaped like:
+ *   `1. **Reporter-owns-closure accountability.** The agent who ... (refs)`
+ * We extract the bold title, the full line, and a keyword set (title words minus
+ * stopwords, plus the curated set for that ordinal).
+ */
+export function parseInvariants(markdown) {
+    const out = [];
+    // Only parse list items under the "## The invariants" section, so the
+    // "## Amending this set" numbered list (1./2./3.) is not mistaken for invariants.
+    const section = sliceInvariantSection(markdown);
+    const itemRe = /^(\d+)\.\s+\*\*(.+?)\*\*\s*(.*)$/;
+    for (const rawLine of section.split('\n')) {
+        const line = rawLine.trim();
+        const m = itemRe.exec(line);
+        if (!m)
+            continue;
+        const index = Number(m[1]);
+        const title = (m[2] ?? '').replace(/\.$/, '').trim();
+        const text = line;
+        const titleTokens = tokenize(title);
+        const curated = CURATED_KEYWORDS[index] ?? [];
+        const keywords = [...new Set([...titleTokens, ...curated.map((k) => k.toLowerCase())])];
+        out.push({ index, title, text, keywords });
+    }
+    return out;
+}
+/**
+ * Slice the markdown to the "## The invariants" section only (up to the next
+ * `## ` heading). Falls back to the whole doc if the heading isn't found.
+ */
+function sliceInvariantSection(markdown) {
+    const lines = markdown.split('\n');
+    let start = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (/^##\s+The invariants\s*$/i.test(lines[i].trim())) {
+            start = i + 1;
+            break;
+        }
+    }
+    if (start < 0)
+        return markdown;
+    let end = lines.length;
+    for (let i = start; i < lines.length; i += 1) {
+        if (/^##\s+/.test(lines[i].trim())) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(start, end).join('\n');
+}
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+/**
+ * Load the protected-invariant set from the repo's `design/protected-invariants.md`.
+ *
+ * `repoRoot` is the framework-source repo root (where `design/` lives). Returns
+ * `[]` (never throws) when the file is absent — the membrane still runs and the
+ * subordination-check simply surfaces nothing (loud-but-proceeds). A missing
+ * invariant file is surfaced separately by the caller.
+ */
+export function loadInvariants(repoRoot) {
+    const path = join(repoRoot, 'design', 'protected-invariants.md');
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    return parseInvariants(raw);
+}
+/**
+ * For a candidate's combined text, return which invariants it plausibly touches.
+ *
+ * A touch is recorded when ANY of the invariant's keywords appears (as a
+ * substring) in the candidate text. Generous by design (see module header).
+ */
+export function invariantsTouched(candidateText, invariants) {
+    const hay = candidateText.toLowerCase();
+    const touches = [];
+    for (const inv of invariants) {
+        const matched = inv.keywords.filter((k) => hay.includes(k));
+        if (matched.length > 0) {
+            touches.push({ index: inv.index, title: inv.title, matchedKeywords: matched });
+        }
+    }
+    return touches;
+}
+/**
+ * Whether the candidate text reads like it RELAXES a guarantee. Heuristic only —
+ * a `true` here means "flag HIGH-RISK for operator scrutiny", NOT "drop".
+ */
+export function readsAsRelaxation(candidateText) {
+    return RELAXATION_HINT.test(candidateText);
+}
+//# sourceMappingURL=invariants.js.map

package/dist/cli/propose/invariants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.js","sourceRoot":"","sources":["../../../src/cli/propose/invariants.ts"],"names":[],"mappings":"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"}

package/dist/cli/propose/proposal-writer.d.ts

@@ -0,0 +1,33 @@
+/** The label every auditor-opened proposal issue carries (for filtering). */
+export declare const PROPOSAL_LABEL = "auditor-proposal";
+/** Input to open a single ratifiable proposal issue. */
+export interface ProposalIssueInput {
+    readonly repo: string;
+    readonly title: string;
+    /** The full Markdown proposal body (assembled from agent-authored content). */
+    readonly body: string;
+    /** Labels to apply on creation; always includes `auditor-proposal`. */
+    readonly labels: readonly string[];
+}
+/** Result of opening a proposal issue. */
+export interface ProposalIssueResult {
+    /** The created issue URL (or number) as returned by the creator. */
+    readonly url: string;
+}
+/**
+ * The create-only GitHub seam. Implementations MUST perform only issue
+ * CREATION. The membrane depends on this interface (not on `gh` directly) so
+ * tests can inject a fake + assert (a) zero creates in dry-run mode and (b)
+ * create-only behaviour under `--file`.
+ */
+export interface ProposalIssueWriter {
+    createProposalIssue(input: ProposalIssueInput): Promise<ProposalIssueResult>;
+}
+/**
+ * Production writer: shells out to `gh issue create` for a SINGLE issue per
+ * call. `token` is forwarded as `GH_TOKEN` in the subprocess env (canonical bot
+ * auth). This class has no merge/close/edit/comment path at all — issue creation
+ * is the only operation it can perform.
+ */
+export declare function createGhProposalWriter(token: string): ProposalIssueWriter;
+//# sourceMappingURL=proposal-writer.d.ts.map

package/dist/cli/propose/proposal-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-writer.d.ts","sourceRoot":"","sources":["../../../src/cli/propose/proposal-writer.ts"],"names":[],"mappings":"AA0BA,6EAA6E;AAC7E,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC9E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAwBzE"}

package/dist/cli/propose/proposal-writer.js

@@ -0,0 +1,53 @@
+/**
+ * Create-only GitHub seam for the auditor Plan membrane
+ * (groundnuty/macf#503, DR-026 G1).
+ *
+ * THE LOAD-BEARING INVARIANT (mirror of F4's read-only `GitHubReader`, inverted
+ * for creation): the Plan membrane may, under an explicit `--file` flag, OPEN
+ * ratifiable proposal artifacts — but it may do NOTHING else. This interface
+ * exposes ONLY `createProposalIssue`. There is deliberately NO merge / close /
+ * edit / comment / label-mutate / delete method on the seam, so any
+ * non-proposal mutation is *unrepresentable* through the type. This is invariant
+ * #8 (auditor-never-acts) enforced structurally at the type boundary: the
+ * auditor proposes, the operator ratifies — the auditor can never apply.
+ *
+ * The default implementation shells out to `gh issue create` via `execFile` (a
+ * single create per candidate, with the `auditor-proposal` label). The token is
+ * passed via `GH_TOKEN` in the subprocess env (the house bot-auth posture),
+ * never baked into a remote or used for any other op.
+ *
+ * Tests inject a fake implementation and assert it received CREATES only (and
+ * zero creates in the default dry-run mode).
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** The label every auditor-opened proposal issue carries (for filtering). */
+export const PROPOSAL_LABEL = 'auditor-proposal';
+/**
+ * Production writer: shells out to `gh issue create` for a SINGLE issue per
+ * call. `token` is forwarded as `GH_TOKEN` in the subprocess env (canonical bot
+ * auth). This class has no merge/close/edit/comment path at all — issue creation
+ * is the only operation it can perform.
+ */
+export function createGhProposalWriter(token) {
+    const env = { ...process.env, GH_TOKEN: token };
+    return {
+        async createProposalIssue(input) {
+            const labelArgs = [];
+            for (const label of input.labels) {
+                labelArgs.push('--label', label);
+            }
+            const { stdout } = await execFileAsync('gh', [
+                'issue', 'create',
+                '--repo', input.repo,
+                '--title', input.title,
+                '--body', input.body,
+                ...labelArgs,
+            ], { encoding: 'utf-8', env, maxBuffer: 8 * 1024 * 1024 });
+            // `gh issue create` prints the new issue URL on stdout.
+            return { url: stdout.trim() };
+        },
+    };
+}
+//# sourceMappingURL=proposal-writer.js.map

package/dist/cli/propose/proposal-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-writer.js","sourceRoot":"","sources":["../../../src/cli/propose/proposal-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AA4BjD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAEhD,OAAO;QACL,KAAK,CAAC,mBAAmB,CAAC,KAAyB;YACjD,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACjC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACnC,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CACpC,IAAI,EACJ;gBACE,OAAO,EAAE,QAAQ;gBACjB,QAAQ,EAAE,KAAK,CAAC,IAAI;gBACpB,SAAS,EAAE,KAAK,CAAC,KAAK;gBACtB,QAAQ,EAAE,KAAK,CAAC,IAAI;gBACpB,GAAG,SAAS;aACb,EACD,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CACvD,CAAC;YACF,wDAAwD;YACxD,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/propose/report.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure formatters for the auditor Plan membrane (groundnuty/macf#503, DR-026 G1).
+ *
+ * Two outputs, both deterministic (no I/O, no clock):
+ *   - `buildProposalBody` — the Markdown body of ONE ratifiable proposal issue,
+ *     assembled from the AGENT-AUTHORED signal content (signal text + rationales)
+ *     plus the mechanical metadata (tier, route, distinct-agent corroboration,
+ *     invariant touchpoints, HIGH-RISK flag).
+ *   - `buildReport` — the dry-run Markdown report printed to stdout/--output: the
+ *     promoted candidates (each rendered as a proposal preview) PLUS a separate,
+ *     visible "HELD (N<threshold)" section. The default mode opens NOTHING; this
+ *     report IS the default-mode artifact.
+ *
+ * Every proposal makes its non-actuation explicit: the operator ratifies; the
+ * auditor never merges/applies (invariants #8 + #9).
+ */
+import { type ProposalIssueInput } from './proposal-writer.js';
+import type { CandidateSet, ProposalCandidate } from './candidates.js';
+/** A short, stable proposal title from the candidate. */
+export declare function proposalTitle(c: ProposalCandidate): string;
+/**
+ * Build the Markdown body for one ratifiable proposal issue. Pure assembly of
+ * agent-authored content + mechanical metadata; no LLM judgment is encoded.
+ */
+export declare function buildProposalBody(c: ProposalCandidate): string;
+/** Build the full `ProposalIssueInput` (title + body + labels) for a candidate. */
+export declare function buildProposalIssueInput(repo: string, c: ProposalCandidate): ProposalIssueInput;
+export interface ReportInput {
+    readonly project: string;
+    readonly repo: string;
+    readonly candidates: CandidateSet;
+    /** True when `--file` was set (artifacts opened); false = dry-run report. */
+    readonly fileMode: boolean;
+    /** Whether `protected-invariants.md` was found + parsed (surfaced if not). */
+    readonly invariantsLoaded: boolean;
+    /** Count of reflection records read (for the summary line). */
+    readonly reflectionRecords: number;
+    /** Count of malformed reflection lines skipped (surfaced). */
+    readonly reflectionsSkipped: number;
+    /** Number of reflection ledger files read. */
+    readonly reflectionFiles: number;
+}
+/**
+ * Build the dry-run Markdown report. Promoted candidates render as previews; the
+ * HELD set renders in its own clearly-labelled section so a sub-threshold
+ * candidate is VISIBLE, never silently dropped.
+ */
+export declare function buildReport(input: ReportInput): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/cli/propose/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/propose/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAiB,MAAM,iBAAiB,CAAC;AActF,yDAAyD;AACzD,wBAAgB,aAAa,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAK1D;AAmCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CA0D9D;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,iBAAiB,GACnB,kBAAkB,CAUpB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AA4BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAqFtD"}