@entelligentsia/forgecli 1.0.14 → 1.0.20

package/CHANGELOG.md

@@ -7,6 +7,148 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.20] — 2026-06-04
+
+Release roll-up of the post-S30 stabilization train (1.0.15–1.0.19) plus the
+dashboard/status-bar TUI pass. Pairs with forge plugin **v1.2.17**.
+
+### Fixed
+
+- **Status-bar/dashboard TUI pass** (Iron-Laws compliance follow-ups):
+  Focusable/theming/width-safety/timer guards and consolidated entry;
+  ↑/Esc deactivation via the input router with ○ focus indicator;
+  ○/● colour carries node status (accent=running, success=completed,
+  error=failed); spinner shows activity without a redundant node glyph.
+
+## [1.0.19] — 2026-06-04
+
+### Changed
+
+- **Halt-advisor model = the heavy model the runtime resolves point-in-time —
+  the `advisorModel` config entry is removed.** Supersedes the 1.0.18 advisor
+  resolution. There is no dedicated knob: "heavy" is the approve/architect
+  slot resolved through the existing routing cascade (L4 phase override →
+  project → user/global → default), exactly as the approve phase itself would
+  resolve; when the cascade bottoms out at inherit, the session's current
+  model (pi default) is used. This mirrors the Claude Code plugin route, where
+  the advisor runs on the opus-class session model. The `advisorModel` key is
+  dropped from `GlobalConfig`/`ProjectConfig`/`MergedConfig`, the config
+  merge, and `forge-cli-schema.json` (it was never exposed in `/forge:config`
+  and never set in practice).
+
+## [1.0.18] — 2026-06-04
+
+Coordinated release matching forge plugin **v1.2.17** (postflight-gate
+false-halt fixes). Bundles the dashboard Iron-Laws compliance pass
+(Focusable, theming, width-safety, timer guards, consolidated entry).
+
+### Fixed
+
+- **Halt advisor no longer runs on `anthropic/undefined`.** pi's
+  `ModelRegistry.getAvailable()` returns Model objects whose identifier is
+  `.id`, not `.model`; the blind `available[0] as PersonaModel` cast produced
+  `{ provider, model: undefined }` and the advisor dispatched against a
+  nonexistent model (observed on the CART-S03-T01 halt). `resolveAdvisorModel`
+  now maps both shapes, skips entries without a usable identifier, and —
+  before falling back to the registry at all — prefers the **session's
+  current model**, which is provider-neutral and known-good. Config
+  `advisorModel` slot still wins when set.
+
+## [1.0.17] — 2026-06-04
+
+### Fixed
+
+- **Context-governor dedup hardening — reads-only, error-aware, re-queryable.**
+  CART-S02-T04 transcripts surfaced three Rule-1 defects:
+  1. *Write masking (serious):* the dedup key carried no read/write
+     distinction, so a `forge_artifact` WRITE confirmation was replaced by a
+     pointer registered by an earlier READ of the same path — a failed write
+     would have been silently masked. Dedup now applies only to read-like
+     commands (`read`/`get*`/`list`/`describe`/`template`); every mutation
+     result passes through verbatim, and the command participates in the key
+     (read vs list never conflate).
+  2. *Impossible re-query:* the pointer said "re-query if needed", but every
+     re-query of the same key returned another pointer — agents responded by
+     switching to bash `cat` workarounds (wasted turns, path-guess errors).
+     Pointers now ALTERNATE: served at most once in a row, the immediately
+     repeated call is honoured with full (still trimmed/clamped) content.
+     Wording updated to "call again to re-fetch".
+  3. *Error interaction:* errored results were registered and replaced by
+     pointers. Error results now bypass all curation — never registered,
+     never replaced, always verbatim.
+
+## [1.0.16] — 2026-06-03
+
+Coordinated release matching forge plugin **v1.2.15**.
+
+### Fixed
+
+- **Zero-usage "husk" turns no longer corrupt phase telemetry.** Failed/retry
+  turns emit assistant messages with all-zero usage; the accumulator in
+  `forge-subagent.ts` counted them as turns and — because
+  `usage.totalTokens ?? prev` treats `0` as non-nullish — overwrote the
+  running `contextTokens` with 0, which is why every aborted phase transcript
+  reported `contextTokens: 0`. Husk turns are now excluded from `turns` and
+  the context figure only updates on a positive total.
+
+- **Incomplete (cancelled/failed) phase attempts now emit their billed
+  tokens.** The cancel and halt-on-failure branches in `run-task.ts` and
+  `fix-bug.ts` returned without emitting a phase event, so the provider-billed
+  tokens of aborted attempts never reached the store — collate's COST_REPORT
+  under-counted real spend (CART-S02-T03 baseline: 259,950 tokens invisible
+  across two aborted plan passes). New `emitIncompletePhaseEvent` helper emits
+  the canonical phase event with `verdict: "aborted"` (cancel) /
+  `"failed"` (halt) and the captured partial usage; zero-token attempts are
+  skipped (no husk noise). Pairs with forge plugin v1.2.15, whose COST_REPORT
+  gains an **Incomplete Passes** section.
+
+## [1.0.15] — 2026-06-03
+
+### Fixed
+
+- **forge-compress savings prints no longer corrupt the `/forge:dashboard`
+  TUI.** `compressWithTelemetry` (forge-tools.ts) and the `forge_artifact`
+  read path wrote dim `[forge-compress] N→M tok (X% saved)` lines straight to
+  stderr — raw ANSI under an active TUI overlay garbles the screen. The prints
+  were redundant: the same stats already flow through tool-result
+  `details.compression` → viewport-events → session-registry/orchestrator-tree
+  → the dashboard's aggregate `⇌Nt` savings suffix. Removed both stderr writes;
+  the dashboard remains the single surface for compression savings.
+
+- **Context governor was dormant in production — Mechanisms A–D never reached
+  phase subagent sessions.** Benchmarking CART-S02-T03 under
+  `FORGE_CTX_GOVERNOR=1` showed zero curation markers and no token reduction.
+  Three wiring defects, all in the FORGE-S30-T07 integration layer (the
+  mechanisms themselves were correct):
+  1. `registerHookDispatcher(pi, …, governor)` in `index.ts` only governs the
+     **parent** session; every phase runs in an isolated `createAgentSession`
+     subagent the parent's hooks never see.
+  2. `resolvePhaseKey` probed `ctx.persona`/`ctx.phase`, which pi never
+     populates (and `FORGE_PHASE_KEY` is read but never set) — so every phase
+     resolved the inert `default` policy.
+  3. The policy table only shipped `architect/plan` and `engineer/review`,
+     matching **no** real `${personaNoun}/${role}` pipeline key; and
+     `createGovernor` was constructed without `steerFn`/`summarySentinel`/
+     `compactFn`, leaving Mechanism B steer, Mechanism C shed, and the
+     Mechanism E proactive trigger unreachable.
+
+  Fix: new `buildGovernorFactory({ phaseKey, cwd })` (`context-governor.ts`)
+  is constructed **per phase** by `run-task.ts` — which knows the
+  `${personaNoun}/${role}` key — and injected into each subagent session via
+  `extensionFactories`, alongside a `buildForgeCompactionFactory` now carrying
+  warm-tier path opts (`cwd`/`phaseKey`/`entityId`/`sprintId` — previously
+  threaded from `index.ts` with no opts, so warm-tier merge was dead). The
+  factory wires `steerFn` → `pi.sendUserMessage(…, { deliverAs: "steer" })`,
+  `summarySentinel` → read-only `.forge/store/{tasks,bugs}/<id>.json`
+  `summaries[<phase>]` probe, and `compactFn` → `ctx.compact()`. The policy
+  table now ships entries for all six governed pipeline keys (`engineer/plan`,
+  `supervisor/review-plan`, `engineer/implement`, `supervisor/review-code`,
+  `qa-engineer/validate`, `architect/approve`) with `read` budgets kept more
+  generous than `bash` so file reads aren't over-clamped; `writeback`/`commit`
+  stay on `default`. Flag-gating is unchanged (`FORGE_CTX_GOVERNOR=1`), and
+  `registerRunTask`/`registerRunSprint` keep `extensionFactories` as a test
+  seam.
+
 ## [1.0.14] — 2026-06-03
 
 Coordinated release matching forge plugin **v1.2.14**.

package/dist/CHANGELOG-forge-plugin.md

@@ -5,6 +5,67 @@ Format: newest first. Breaking changes are marked **△ Breaking**.
 
 ---
 
+## [1.2.17] — 2026-06-04
+
+### Fixed
+
+- **Postflight output guard no longer false-halts every phase.** The S26-T19
+  guards were dormant until the v1.2.16 base-pack recompile activated them;
+  their first live firing halted CART-S03-T01's plan phase despite full
+  success. Two deterministic bugs in `postflight-gate.cjs`:
+  1. *Require predicates never resolved* — the outputs blocks use bare record
+     paths (`summaries.plan.verdict`) while the CLI passes
+     `state = { task: record }`; every bare require read `undefined` and
+     failed unconditionally. `readField` now falls back to the entity record
+     (`state.task` / `state.bug`) after the direct walk.
+  2. *Artifact paths missed the `sprints/` segment* — `{sprint}` was
+     substituted with the bare sprintId, probing
+     `<engineering>/<sprintId>/<taskId>` instead of the canonical
+     `<engineering>/sprints/<sprintId>/<taskId>`. New `buildSubstitutions()`
+     resolves `{sprint}` to the path segment under engineering
+     (`sprints/<id>` for tasks, `bugs` for bug records).
+
+---
+
+## [1.2.16] — 2026-06-04
+
+### Fixed
+
+- **Review/validate phases no longer self-limit on iteration count**
+  ([forge-engineering#34](https://github.com/Entelligentsia/forge-engineering/issues/34)).
+  The standalone-invocation fallback in `review_plan` / `review_code` /
+  `validate_task` read `maxReviewIterations` from `.forge/config.json` —
+  producing a *"Key not found"* error on every review phase and, worse,
+  duplicating a protection the orchestrator already owns. Loop budgeting and
+  termination are solely the orchestrator's job (`run-task` enforces
+  `maxIterations` deterministically; exhaustion escalates to a human), and a
+  deliberate human standalone re-run **is** the escape hatch for stuck items —
+  a phase consulting its own cap could refuse exactly that recovery. Workflows
+  now treat user-invoked runs as iteration 1 with no limit and never read an
+  iteration cap from config; orchestrated runs continue to take `N of M` from
+  the orchestrator-injected Review Loop Context block. Prompt-text only.
+
+---
+
+## [1.2.15] — 2026-06-03
+
+### Fixed
+
+- **COST_REPORT now accounts incomplete (aborted/failed) phase attempts.**
+  Cancelled and halted phase attempts bill real provider tokens, but their
+  events arrived as token-less husks — the CART-S02-T03 benchmark baseline
+  under-counted by exactly 259,950 tokens across two aborted plan passes.
+  forge-cli ≥1.0.16 now emits phase events with `verdict: "aborted"` (user
+  cancel) / `"failed"` (halt-on-failure) carrying the captured partial usage;
+  `collate.cjs` adds an **Incomplete Passes** section to COST_REPORT (task,
+  phase, outcome, tokens per attempt). Per-Task / Per-Role / Model-Split
+  totals sum verdict-agnostically, so the previously-invisible spend lands in
+  the totals automatically once events arrive. Report-layer only — no schema
+  change (`verdict` was already a free-string event field); older forge-cli
+  versions simply produce no incomplete-pass events.
+
+---
+
 ## [1.2.14] — 2026-06-03
 
 ### Fixed

package/dist/extensions/forgecli/config-layer.d.ts

@@ -28,33 +28,17 @@ export interface ForgeCliFeatureFlags {
 export interface GlobalConfig {
     "persona-models"?: PersonaModelsMap;
     forgeCli?: ForgeCliFeatureFlags;
-    /**
-     * FORGE-S26-T18: optional advisor model for halt-recovery advisory.
-     * When present, the halt advisor spawns on this model instead of
-     * falling back to modelRegistry.getAvailable()[0].
-     */
-    advisorModel?: PersonaModel;
 }
 export interface ProjectConfig {
     "persona-models"?: PersonaModelsMap;
     forgeCli?: ForgeCliFeatureFlags;
     pipelines?: Record<string, PipelineConfig>;
-    /**
-     * FORGE-S26-T18: optional per-project advisor model override.
-     * Project config (L2) wins over global config (L1).
-     */
-    advisorModel?: PersonaModel;
 }
 export interface MergedConfig {
     /** Shallow-merged persona-models (project wins on key collision). */
     "persona-models"?: PersonaModelsMap;
     /** Project-only pipelines (L3/L4 config lives here). */
     pipelines?: Record<string, PipelineConfig>;
-    /**
-     * Resolved advisor model (project wins over global; same L2>L1 precedence).
-     * Used by halt-recovery advisor (FORGE-S26-T18).
-     */
-    advisorModel?: PersonaModel;
     /** The raw global config for L1 lookups — null if absent or invalid. */
     _global: GlobalConfig | null;
     /** The raw project config for L2 lookups — null if absent or invalid. */

package/dist/extensions/forgecli/config-layer.js

@@ -67,11 +67,6 @@ export function loadLayeredConfig(cwd) {
     if (projectConfig?.pipelines) {
         merged.pipelines = projectConfig.pipelines;
     }
-    // advisorModel: project (L2) wins over global (L1)
-    const advisorModel = projectConfig?.advisorModel ?? globalConfig?.advisorModel;
-    if (advisorModel) {
-        merged.advisorModel = advisorModel;
-    }
     return { global: globalConfig, project: projectConfig, merged, errors };
 }
 //# sourceMappingURL=config-layer.js.map

package/dist/extensions/forgecli/config-layer.js.map

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

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

@@ -0,0 +1,83 @@
+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.
+ * @returns ForgeFactSummary with all extracted patterns.
+ */
+export declare function extractForgeFacts(messagesToSummarize: unknown[]): 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.
+ * NOT wired into index.ts/run-task.ts — deferred to T07 production integration.
+ *
+ * @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,302 @@
+// 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.
+//   - NOT wired into index.ts/run-task.ts yet — deferred to T07 production integration.
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Pattern constants (module-level compile-time constants)
+// ---------------------------------------------------------------------------
+/** Matches Forge store IDs in their standard forms:
+ *   FORGE-S30-T09   (sprint+task)
+ *   FORGE-S30       (sprint)
+ *   FORGE-BUG-042   (bug, with category letters + digit suffix)
+ * Pattern: FORGE- followed by alternating ALPHANUM segments separated by hyphens.
+ * Two variants ordered longest-first so overlapping (sprint+task before sprint) works. */
+const STORE_ID_RE = /FORGE-[A-Z]+\d*-(?:T?\d+|[A-Z]+\d*)|FORGE-[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;
+/** Matches file reference patterns. */
+const FILE_REF_RE = /(?:engineering\/[^\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.
+ * @returns ForgeFactSummary with all extracted patterns.
+ */
+export function extractForgeFacts(messagesToSummarize) {
+    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 — reset lastIndex before each matchAll
+            const storeMatches = text.matchAll(new RegExp(STORE_ID_RE.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(FILE_REF_RE.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;
+}
+// ---------------------------------------------------------------------------
+// Warm-tier helpers
+// ---------------------------------------------------------------------------
+/** Map phase key to canonical {PHASE}-SUMMARY.json filename. */
+function phaseSummaryFilename(phaseKey) {
+    const map = {
+        // Real run-task PHASE_PIPELINE keys (`${personaNoun}/${role}`):
+        "engineer/plan": "PLAN-SUMMARY.json",
+        "supervisor/review-plan": "REVIEW_PLAN-SUMMARY.json",
+        "engineer/implement": "IMPLEMENTATION-SUMMARY.json",
+        "supervisor/review-code": "CODE_REVIEW-SUMMARY.json",
+        "qa-engineer/validate": "VALIDATION-SUMMARY.json",
+        "architect/approve": "APPROVE-SUMMARY.json",
+        // Legacy design-time keys (test fixtures only):
+        "architect/plan": "PLAN-SUMMARY.json",
+        "engineer/review": "REVIEW-SUMMARY.json",
+        "engineer/code-review": "CODE_REVIEW-SUMMARY.json",
+    };
+    return map[phaseKey] ?? "{PHASE}-SUMMARY.json";
+}
+/** 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).
+ *
+ * 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) {
+    try {
+        let filePath;
+        const reader = opts.summaryReader ?? defaultSummaryReader;
+        if (opts.cwd && opts.phaseKey && opts.entityId && opts.sprintId) {
+            filePath = path.join(opts.cwd, "engineering", "sprints", opts.sprintId, opts.entityId, phaseSummaryFilename(opts.phaseKey));
+        }
+        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.
+ * NOT wired into index.ts/run-task.ts — deferred to T07 production integration.
+ *
+ * @param opts  ForgeCompactionOptions (default: empty — no warm-tier).
+ * @returns ExtensionFactory for passing to DefaultResourceLoader.extensionFactories.
+ */
+export function buildForgeCompactionFactory(opts = {}) {
+    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.
+                const msgs = Array.isArray(messagesToSummarize) ? messagesToSummarize : [];
+                const facts = extractForgeFacts(msgs);
+                // Read warm-tier summary (best-effort, IL7).
+                const warmTier = readWarmTierSummary(opts);
+                // 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