@entelligentsia/forgecli 1.0.14 → 1.0.21

package/dist/extensions/forgecli/context-governor-compaction.d.ts

@@ -0,0 +1,94 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+/**
+ * Structured Forge facts extracted from messagesToSummarize.
+ * All fields are arrays of strings for serialization into the compaction summary.
+ */
+export interface ForgeFactSummary {
+    /** FORGE-X-Y / FORGE-X-Y-TN patterns extracted from message text. */
+    storeIds: string[];
+    /** Lines containing [x] or [ ] checkbox patterns (Markdown task lists). */
+    acStateLines: string[];
+    /** Lines matching → <status> or update-status ... status <value>. */
+    transitionLines: string[];
+    /** File refs: engineering/, .forge/, *.ts/*.md/*.cjs/*.json paths. */
+    fileRefs: string[];
+    /** Text blocks containing [FRICTION] or type:friction. */
+    frictionBlocks: string[];
+}
+/**
+ * Options for buildForgeCompactionFactory.
+ */
+export interface ForgeCompactionOptions {
+    /**
+     * Absolute path to the project CWD (for warm-tier summary file lookup).
+     * When omitted, warm-tier merge is skipped unless summaryReader is provided.
+     */
+    cwd?: string;
+    /**
+     * Phase key for summary filename resolution (e.g. "architect/plan").
+     * When omitted, warm-tier merge is skipped.
+     */
+    phaseKey?: string;
+    /**
+     * Task/entity ID for summary path resolution (e.g. "FORGE-S30-T09").
+     * When omitted, warm-tier merge is skipped.
+     */
+    entityId?: string;
+    /**
+     * Sprint ID for summary path resolution (e.g. "FORGE-S30").
+     * When omitted, warm-tier merge is skipped.
+     */
+    sprintId?: string;
+    /**
+     * Injected summary reader (test seam). Receives the resolved summary
+     * file path (empty string when path resolution is skipped) and returns
+     * the raw JSON string or null. Defaults to fs.readFileSync.
+     * Must not throw — return null on any failure.
+     */
+    summaryReader?: (filePath: string) => string | null;
+}
+/**
+ * Extract structured Forge facts from an array of message-like objects.
+ *
+ * Pure function — no fs I/O, no LLM calls, provider-neutral.
+ * Accepts any array (unknown[]) to be safe against varying pi message shapes.
+ * Text content is extracted from `.content[].text` (assistant messages)
+ * and from direct string entries.
+ *
+ * @param messagesToSummarize  Array of message-like objects from preparation.
+ * @param extractOpts  Optional project-config parameters (FORGE-BUG-043 PR 2):
+ *                     prefix (store-ID prefix, default "FORGE") and
+ *                     engineeringPath (file-ref directory, default "engineering").
+ *                     Omitting them preserves the historical behaviour exactly.
+ * @returns ForgeFactSummary with all extracted patterns.
+ */
+export declare function extractForgeFacts(messagesToSummarize: unknown[], extractOpts?: {
+    prefix?: string;
+    engineeringPath?: string;
+}): ForgeFactSummary;
+/**
+ * Build an ExtensionFactory that registers a session_before_compact handler
+ * returning a deterministically-composed CompactionResult.
+ *
+ * The handler:
+ * 1. Validates that event.preparation is present and well-formed.
+ * 2. Extracts Forge facts from event.preparation.messagesToSummarize
+ *    (no LLM call, provider-neutral).
+ * 3. Reads the warm-tier {PHASE}-SUMMARY.json if opts provide path context,
+ *    or invokes opts.summaryReader("") as a test seam.
+ * 4. Assembles a compact structured summary string.
+ * 5. Returns { compaction: { summary, firstKeptEntryId, tokensBefore } }.
+ * 6. Returns undefined on any error (IL7 — lets pi compact normally).
+ *
+ * Pack 07: reads summary files but never writes .forge/store/.
+ * IL10: no pi-mono edits, no dispatch contract changes.
+ * Wired per-phase by run-task.ts via RunSubagentOptions.extensionFactories.
+ *
+ * Project config (store-ID prefix, paths.engineering) is loaded ONCE here at
+ * factory construction from `<opts.cwd>/.forge/config.json` — never per
+ * compaction event. Without cwd the historical defaults apply (FORGE-BUG-043 PR 2).
+ *
+ * @param opts  ForgeCompactionOptions (default: empty — no warm-tier).
+ * @returns ExtensionFactory for passing to DefaultResourceLoader.extensionFactories.
+ */
+export declare function buildForgeCompactionFactory(opts?: ForgeCompactionOptions): ExtensionFactory;

package/dist/extensions/forgecli/context-governor-compaction.js

@@ -0,0 +1,327 @@
+// context-governor-compaction.ts — Mechanism E: Forge-aware compaction handler.
+// FORGE-S30-T09
+//
+// Exports:
+//   ForgeFactSummary        — extracted Forge facts struct
+//   ForgeCompactionOptions  — options for the compaction factory
+//   extractForgeFacts(msgs) — pure extractor (no fs I/O)
+//   buildForgeCompactionFactory(opts) — ExtensionFactory builder
+//
+// Design:
+//   - Thin module separate from context-governor.ts so it can import ExtensionAPI
+//     types (which require the pi pkg) without polluting the pure-logic governor.
+//   - extractForgeFacts: line-level pattern matching — no LLM call, provider-neutral,
+//     lossless on structured facts.
+//   - Warm-tier merge: reads {PHASE}-SUMMARY.json via injected summaryReader
+//     (defaults to fs.readFileSync). Best-effort — absent/malformed files silently
+//     skipped (IL7).
+//   - IL7 fallback: entire session_before_compact handler wrapped in try/catch.
+//     On any error, returns undefined — lets pi compact normally with generateSummary.
+//   - IL10/Pack 07: only reads summary files, never writes .forge/store/ or summaries.
+//   - Wired per-phase by run-task.ts (FORGE_CTX_GOVERNOR=1) with cwd/phaseKey/
+//     entityId/sprintId opts; project config (prefix, paths.engineering) loads
+//     once at factory construction (FORGE-BUG-043 PR 2).
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadGovernorProjectConfig } from "./governor-config.js";
+import { summaryFilenameFor } from "./phase-vocab.js";
+// ---------------------------------------------------------------------------
+// Pattern builders (parameterized by project config — FORGE-BUG-043 PR 2)
+// ---------------------------------------------------------------------------
+/**
+ * Build the store-ID pattern for a project prefix. Standard forms:
+ *   <P>-S30-T09   (sprint+task)
+ *   <P>-S30       (sprint)
+ *   <P>-BUG-042   (bug, with category letters + digit suffix)
+ * Pattern: prefix followed by alternating ALPHANUM segments separated by
+ * hyphens; two variants ordered longest-first so overlapping (sprint+task
+ * before sprint) works.
+ *
+ * The prefix was previously the literal "FORGE", so any project with a
+ * different project.prefix (e.g. CART) extracted zero store IDs (FORGE-BUG-043).
+ * The prefix is identifier-validated by loadGovernorProjectConfig before it
+ * reaches this builder; escaping here is defence in depth.
+ */
+function buildStoreIdRe(prefix) {
+    const p = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`${p}-[A-Z]+\\d*-(?:T?\\d+|[A-Z]+\\d*)|${p}-[A-Z]+\\d*`, "g");
+}
+/** Matches Markdown checkbox lines. */
+const CHECKBOX_RE = /^\s*[-*]?\s*\[[ xX]\].*$/gm;
+/** Matches status transition patterns:
+ *   - Arrow: "→ implemented"
+ *   - store-cli: "update-status task FORGE-S30-T09 status implementing"
+ * Using a broad match to capture both forms reliably. */
+const TRANSITION_RE = /(?:→\s*[\w][\w-]*|update-status\s+\S+\s+\S+\s+status\s+[\w][\w-]*)/g;
+/**
+ * Build the file-reference pattern. The engineering directory segment comes
+ * from paths.engineering (default "engineering"); `.forge/` is the product's
+ * fixed instance directory (it hosts config.json itself) and stays literal.
+ */
+function buildFileRefRe(engineeringPath) {
+    const e = engineeringPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:${e}\\/[^\\s"'\`,;)]+|\\.forge\\/[^\\s"'\`,;)]+|\\b[\\w./\\-]+\\.(?:ts|md|cjs|json)\\b)`, "g");
+}
+// ---------------------------------------------------------------------------
+// extractForgeFacts — pure extractor
+// ---------------------------------------------------------------------------
+/**
+ * Extract structured Forge facts from an array of message-like objects.
+ *
+ * Pure function — no fs I/O, no LLM calls, provider-neutral.
+ * Accepts any array (unknown[]) to be safe against varying pi message shapes.
+ * Text content is extracted from `.content[].text` (assistant messages)
+ * and from direct string entries.
+ *
+ * @param messagesToSummarize  Array of message-like objects from preparation.
+ * @param extractOpts  Optional project-config parameters (FORGE-BUG-043 PR 2):
+ *                     prefix (store-ID prefix, default "FORGE") and
+ *                     engineeringPath (file-ref directory, default "engineering").
+ *                     Omitting them preserves the historical behaviour exactly.
+ * @returns ForgeFactSummary with all extracted patterns.
+ */
+export function extractForgeFacts(messagesToSummarize, extractOpts) {
+    const storeIdRe = buildStoreIdRe(extractOpts?.prefix ?? "FORGE");
+    const fileRefRe = buildFileRefRe(extractOpts?.engineeringPath ?? "engineering");
+    const storeIdSet = new Set();
+    const acStateLines = [];
+    const transitionLineSet = new Set();
+    const fileRefSet = new Set();
+    const frictionBlocks = [];
+    for (const msg of messagesToSummarize) {
+        const texts = extractTextContent(msg);
+        for (const text of texts) {
+            // Store IDs — fresh RegExp per text so lastIndex never leaks
+            const storeMatches = text.matchAll(new RegExp(storeIdRe.source, "g"));
+            for (const m of storeMatches) {
+                storeIdSet.add(m[0]);
+            }
+            // AC-state checkbox lines
+            const checkboxMatches = text.match(new RegExp(CHECKBOX_RE.source, "gm"));
+            if (checkboxMatches) {
+                for (const line of checkboxMatches) {
+                    acStateLines.push(line.trim());
+                }
+            }
+            // Transition lines
+            const transitionMatches = text.matchAll(new RegExp(TRANSITION_RE.source, "g"));
+            for (const m of transitionMatches) {
+                transitionLineSet.add(m[0].trim());
+            }
+            // File refs
+            const fileRefMatches = text.matchAll(new RegExp(fileRefRe.source, "g"));
+            for (const m of fileRefMatches) {
+                const ref = m[0].trim();
+                if (ref.length > 2) {
+                    fileRefSet.add(ref);
+                }
+            }
+            // FRICTION blocks — scan per line
+            for (const line of text.split("\n")) {
+                if (/\[FRICTION\]|type:friction/i.test(line)) {
+                    frictionBlocks.push(line.trim());
+                }
+            }
+        }
+    }
+    return {
+        storeIds: Array.from(storeIdSet),
+        acStateLines,
+        transitionLines: Array.from(transitionLineSet),
+        fileRefs: Array.from(fileRefSet),
+        frictionBlocks,
+    };
+}
+/**
+ * Extract text strings from a message-like object.
+ * Handles assistant messages (content[].text) and plain strings.
+ */
+function extractTextContent(msg) {
+    if (typeof msg === "string") {
+        return [msg];
+    }
+    if (typeof msg !== "object" || msg === null) {
+        return [];
+    }
+    const msgObj = msg;
+    const content = msgObj["content"];
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const texts = [];
+    for (const part of content) {
+        if (typeof part === "string") {
+            texts.push(part);
+        }
+        else if (typeof part === "object" && part !== null) {
+            const p = part;
+            if (p["type"] === "text" && typeof p["text"] === "string") {
+                texts.push(p["text"]);
+            }
+        }
+    }
+    return texts;
+}
+/** Default summaryReader: synchronous fs.readFileSync. Returns null on any error. */
+function defaultSummaryReader(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and parse the warm-tier {PHASE}-SUMMARY.json (synchronous).
+ * Returns the parsed object or null on any failure (IL7).
+ *
+ * The summary filename comes from phase-vocab (mirror of the plugin's
+ * artifact-kinds.cjs catalog — FORGE-BUG-043). Unknown phase keys and phases
+ * without a summary artifact skip the warm-tier read entirely; no placeholder
+ * paths are ever constructed.
+ *
+ * When summaryReader is provided but cwd/phaseKey/entityId/sprintId are not,
+ * calls summaryReader("") — enables test seams that don't need path resolution.
+ */
+function readWarmTierSummary(opts, engineeringPath) {
+    try {
+        let filePath;
+        const reader = opts.summaryReader ?? defaultSummaryReader;
+        if (opts.cwd && opts.phaseKey && opts.entityId && opts.sprintId) {
+            const filename = summaryFilenameFor(opts.phaseKey);
+            if (filename === null)
+                return null; // unknown key / no artifact — skip warm tier
+            filePath = path.join(opts.cwd, engineeringPath, "sprints", opts.sprintId, opts.entityId, filename);
+        }
+        else if (opts.summaryReader) {
+            // Test seam: summaryReader present but no path context — call with empty string.
+            filePath = "";
+        }
+        else {
+            return null;
+        }
+        const raw = reader(filePath);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Summary assembly
+// ---------------------------------------------------------------------------
+/**
+ * Assemble a compact structured summary string from extracted facts
+ * and an optional warm-tier summary.
+ */
+function assembleSummary(facts, warmTier) {
+    const parts = [];
+    // Warm-tier objective (highest information density — prepend).
+    if (warmTier?.objective) {
+        parts.push(`## Phase Objective\n${warmTier.objective}`);
+    }
+    // Warm-tier key changes.
+    if (warmTier?.key_changes && warmTier.key_changes.length > 0) {
+        parts.push(`## Key Changes\n${warmTier.key_changes.map((c) => `- ${c}`).join("\n")}`);
+    }
+    // Extracted store IDs.
+    if (facts.storeIds.length > 0) {
+        parts.push(`## Active Store IDs\n${facts.storeIds.join(", ")}`);
+    }
+    // AC state (checkboxes — capped at 10).
+    if (facts.acStateLines.length > 0) {
+        const sample = facts.acStateLines.slice(0, 10);
+        parts.push(`## Acceptance Criteria State\n${sample.join("\n")}`);
+    }
+    // Transitions (capped at 5).
+    if (facts.transitionLines.length > 0) {
+        const sample = facts.transitionLines.slice(0, 5);
+        parts.push(`## Status Transitions\n${sample.join("\n")}`);
+    }
+    // File refs (capped at 10).
+    if (facts.fileRefs.length > 0) {
+        const sample = facts.fileRefs.slice(0, 10);
+        parts.push(`## File References\n${sample.join("\n")}`);
+    }
+    // FRICTION blocks.
+    if (facts.frictionBlocks.length > 0) {
+        parts.push(`## FRICTION\n${facts.frictionBlocks.join("\n")}`);
+    }
+    if (parts.length === 0) {
+        return "[Forge context governor — compaction summary — no structured facts extracted]";
+    }
+    return `[Forge context governor — compaction summary]\n\n${parts.join("\n\n")}`;
+}
+// ---------------------------------------------------------------------------
+// buildForgeCompactionFactory — ExtensionFactory builder
+// ---------------------------------------------------------------------------
+/**
+ * Build an ExtensionFactory that registers a session_before_compact handler
+ * returning a deterministically-composed CompactionResult.
+ *
+ * The handler:
+ * 1. Validates that event.preparation is present and well-formed.
+ * 2. Extracts Forge facts from event.preparation.messagesToSummarize
+ *    (no LLM call, provider-neutral).
+ * 3. Reads the warm-tier {PHASE}-SUMMARY.json if opts provide path context,
+ *    or invokes opts.summaryReader("") as a test seam.
+ * 4. Assembles a compact structured summary string.
+ * 5. Returns { compaction: { summary, firstKeptEntryId, tokensBefore } }.
+ * 6. Returns undefined on any error (IL7 — lets pi compact normally).
+ *
+ * Pack 07: reads summary files but never writes .forge/store/.
+ * IL10: no pi-mono edits, no dispatch contract changes.
+ * Wired per-phase by run-task.ts via RunSubagentOptions.extensionFactories.
+ *
+ * Project config (store-ID prefix, paths.engineering) is loaded ONCE here at
+ * factory construction from `<opts.cwd>/.forge/config.json` — never per
+ * compaction event. Without cwd the historical defaults apply (FORGE-BUG-043 PR 2).
+ *
+ * @param opts  ForgeCompactionOptions (default: empty — no warm-tier).
+ * @returns ExtensionFactory for passing to DefaultResourceLoader.extensionFactories.
+ */
+export function buildForgeCompactionFactory(opts = {}) {
+    const projectConfig = loadGovernorProjectConfig(opts.cwd);
+    return (pi) => {
+        pi.on("session_before_compact", (event) => {
+            try {
+                // Validate preparation is present and has the required pass-through fields.
+                const prep = event?.preparation;
+                if (!prep || typeof prep !== "object") {
+                    return undefined; // IL7 — malformed preparation
+                }
+                const { firstKeptEntryId, tokensBefore, messagesToSummarize } = prep;
+                if (typeof firstKeptEntryId !== "string" || typeof tokensBefore !== "number") {
+                    return undefined; // IL7 — malformed preparation fields
+                }
+                // Extract Forge facts from message history (patterns built from
+                // the project config loaded at factory construction).
+                const msgs = Array.isArray(messagesToSummarize) ? messagesToSummarize : [];
+                const facts = extractForgeFacts(msgs, {
+                    prefix: projectConfig.prefix,
+                    engineeringPath: projectConfig.engineeringPath,
+                });
+                // Read warm-tier summary (best-effort, IL7).
+                const warmTier = readWarmTierSummary(opts, projectConfig.engineeringPath);
+                // Assemble summary string.
+                const summary = assembleSummary(facts, warmTier);
+                const compaction = {
+                    summary,
+                    firstKeptEntryId,
+                    tokensBefore,
+                };
+                return { compaction };
+            }
+            catch {
+                // IL7: unexpected error → return undefined, let pi compact normally.
+                return undefined;
+            }
+        });
+    };
+}
+//# sourceMappingURL=context-governor-compaction.js.map

package/dist/extensions/forgecli/context-governor-compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-governor-compaction.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/context-governor-compaction.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/context-governor.d.ts

@@ -0,0 +1,169 @@
+import type { ExtensionContext, ExtensionFactory, ToolCallEvent, ToolCallEventResult, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+/**
+ * Return type for tool_result pi handlers — matches ToolResultEventResult from
+ * @earendil-works/pi-coding-agent (not exported from the package root).
+ * Structural equivalence is sufficient for TypeScript assignability.
+ */
+export interface ToolResultEventResult {
+    content?: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        source: unknown;
+    }>;
+    details?: unknown;
+    isError?: boolean;
+}
+/**
+ * Policy for a single persona/phase combination.
+ *
+ * residentFields — names of task/sprint record fields that are always retained
+ *   in context (not trimmed by Mechanism A).
+ * toolBudgets    — per-tool soft token budget caps (keyed by tool name).
+ *   T04 reads these when deciding how aggressively to trim tool_result content.
+ * steerThreshold — fraction of contextWindow at which Mechanism B fires a
+ *   budget-steer note (0–1; e.g. 0.80 = steer when 80% of window is used).
+ */
+export interface PhasePolicy {
+    residentFields: string[];
+    toolBudgets: Record<string, number>;
+    steerThreshold: number;
+}
+/**
+ * Lookup table keyed by `"${persona}/${phase}"` (e.g. `"architect/plan"`,
+ * `"engineer/review"`) plus a `"default"` entry for unknown combinations.
+ */
+export type PhasePolicyTable = Record<string, PhasePolicy>;
+/**
+ * Governor interface wired into hook-dispatcher.ts.
+ * T03: both methods return undefined/void (no-op). T04 supplies live curation
+ * logic via createGovernor.
+ *
+ * MUST NOT throw — IL7. Any internal failure must return undefined silently.
+ */
+export interface ContextGovernor {
+    /**
+     * Called after the triage-error block in the tool_result handler.
+     * Return a ToolResultEventResult to replace the event content, or undefined
+     * to pass through unchanged.
+     */
+    applyToolResult(event: ToolResultEvent, ctx: ExtensionContext): ToolResultEventResult | undefined;
+    /**
+     * Called at the tail of the tool_call handler (after all existing guards).
+     * Return a ToolCallEventResult to block or modify the call, or undefined/void
+     * to pass through unchanged.
+     */
+    applyToolCall(event: ToolCallEvent, ctx: ExtensionContext): ToolCallEventResult | void;
+}
+/**
+ * Returns a ContextGovernor whose methods are pure pass-throughs.
+ * Used as the default in registerHookDispatcher so existing callers that do
+ * not pass a governor see zero behavioural change.
+ */
+export declare function createNoOpGovernor(): ContextGovernor;
+/**
+ * Create a governor backed by the given policy table and model registry.
+ *
+ * Implements Mechanism A curation rules (T04):
+ *   Rule 1 — Dedup/reference-ize
+ *   Rule 2 — Schema-trim (forge_store results)
+ *   Rule 3 — Span-clamp (bash/grep/find/read results)
+ *
+ * Implements Mechanism B (T05):
+ *   Budget meter: per-turn ctx.getContextUsage() → ctx.ui.setStatus("forge:ctx-budget", ...)
+ *   Steer: one-shot note at policy.steerThreshold, injected via steerFn
+ *
+ * Implements Mechanism C (T06):
+ *   Checkpoint-and-shed: forge_store results for summarized entities are evicted
+ *   and replaced with an eviction pointer; unsummarized material is retained.
+ *   Shed criterion: summarySentinel(phaseKey, entityId) returns true.
+ *
+ * @param table     Phase-policy table (keyed by "persona/phase").
+ * @param _modelRegistry  Model registry (fallback contextWindow resolution only).
+ * @param steerFn   Optional callback injected at construction by registerHookDispatcher.
+ *                  Receives the steer message string; called at most once per governor
+ *                  instance (single-fire invariant). Callers that omit this see no steer.
+ * @param summarySentinel  Optional read-only probe injected at construction (Mechanism C / T06).
+ *                  Receives (phaseKey, entityId); returns true when a {PHASE}-SUMMARY.json
+ *                  has been durably written for that entity. When true, the forge_store result
+ *                  is replaced with an eviction pointer. Callers that omit this param see no
+ *                  shedding (backwards-compatible; undefined default).
+ *                  The sentinel MUST NOT write to .forge/store/ or the summary itself (Pack 07).
+ *                  Errors inside the sentinel are silently caught and cause retain, not eviction (IL7).
+ *
+ * contextWindow resolution (provider-neutral): usage.contextWindow from
+ * ctx.getContextUsage(), used directly when available; otherwise the budget
+ * meter is cleared for the turn and no steer/compact decision is made.
+ * @param compactFn  opt callback injected at construction (Mechanism E / T09).
+ *                  Called proactively once when fraction >= policy.steerThreshold,
+ *                  via a single-fire `compactFired` flag distinct from `steerFired`.
+ *                  Callers pass `compactFn = () => session.compact()`. Errors inside
+ *                  compactFn are caught and written to stderr (IL7). Omitting this
+ *                  param is backwards-compatible — no compact trigger fires.
+ * @param phaseKey  opt construction-time phase key override ("persona/role").
+ *                  Production paths MUST pass this (via buildGovernorFactory) —
+ *                  pi never populates persona/phase on ExtensionContext, so the
+ *                  ctx probe always resolves "default" at runtime. Omitting it
+ *                  preserves the legacy ctx-probe behaviour (test harnesses).
+ */
+export declare function createGovernor(table: PhasePolicyTable, _modelRegistry: ModelRegistry, steerFn?: (message: string) => void, summarySentinel?: (phaseKey: string, entityId: string) => boolean, compactFn?: () => void, phaseKey?: string): ContextGovernor;
+/**
+ * Load the built-in phase-policy table.
+ *
+ * Ships an entry for every governed run-task PHASE_PIPELINE key
+ * (`${personaNoun}/${role}` — engineer/plan, supervisor/review-plan,
+ * engineer/implement, supervisor/review-code, qa-engineer/validate,
+ * architect/approve) plus "default" for any unlisted persona/phase.
+ * writeback/commit intentionally stay on "default" — small phases whose
+ * git/store output must not be clamped.
+ *
+ * `read` budgets are deliberately more generous than `bash` — clamping file
+ * reads too tightly degrades implement/review quality (the agent cannot see
+ * whole files), while bash output (store-cli reads, test logs, greps) is the
+ * dominant context bloat observed in the CART-S02-T03 baseline.
+ *
+ * Legacy design-time keys ("architect/plan", "engineer/review") are retained
+ * for existing test fixtures; the pipeline never produces them.
+ *
+ * Values are conservative design-time decisions; a future task can promote
+ * specific fields to project config once per-project tuning evidence exists.
+ */
+export declare function loadDefaultPolicyTable(): PhasePolicyTable;
+/** Options for buildGovernorFactory. */
+export interface GovernorFactoryOptions {
+    /**
+     * Pipeline phase key, `${personaNoun}/${role}` (e.g. "supervisor/review-code").
+     * Known to run-task.ts at dispatch time; injected here because pi never
+     * populates persona/phase on ExtensionContext.
+     */
+    phaseKey: string;
+    /** Project cwd — root containing `.forge/store/` (sentinel reads only). */
+    cwd: string;
+}
+/**
+ * Build an ExtensionFactory that registers a fully-wired context governor in a
+ * subagent session. Constructed per-phase by run-task.ts (which knows the
+ * persona/role) and passed via RunSubagentOptions.extensionFactories —
+ * the same injection channel as buildForgeCompactionFactory (Mechanism E).
+ *
+ * This is the production wiring the original FORGE-S30-T07 integration missed:
+ * registerHookDispatcher(pi, …, governor) in index.ts only governs the PARENT
+ * session, while every phase runs in an isolated createAgentSession subagent
+ * that the parent's hooks never see. The CART-S02-T03 benchmark confirmed the
+ * result: zero curation markers across a full FORGE_CTX_GOVERNOR=1 phase.
+ *
+ * Wiring supplied here:
+ *   phaseKey        — construction-time (Mechanism D policies finally reachable)
+ *   steerFn         — pi.sendUserMessage(msg, { deliverAs: "steer" }) (Mechanism B)
+ *   summarySentinel — storeSummarySentinel against .forge/store/ (Mechanism C)
+ *   compactFn       — ctx.compact() proactive trigger (Mechanism E)
+ *
+ * steer uses the session-scoped ExtensionAPI directly; compact rides the
+ * ExtensionContext captured at the start of each handler invocation — it only
+ * fires synchronously inside applyToolResult, so the captured ctx is always
+ * the live one. All callbacks are guarded: failures fall through silently
+ * (IL7); the factory never writes to .forge/store/ (Pack 07).
+ */
+export declare function buildGovernorFactory(opts: GovernorFactoryOptions): ExtensionFactory;