opencode-matrixx-v2 0.0.0-stage → 1.1.0

package/dist/features/mission-state/storage.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Mission State Storage
+ *
+ * Handles reading/writing mission.json for active plan tracking.
+ */
+import type { MissionState, PlanProgress } from "./types";
+export declare function readMissionState(directory: string): MissionState | null;
+/**
+ * Normalize a parsed mission.json value in memory (no disk rewrite).
+ * Legacy files used a singular `session_id` string; modern files use
+ * `session_ids[]`. Missing or non-array values become `[]` unless a
+ * legacy `session_id` string is present, which becomes `[session_id]`.
+ */
+export declare function normalizeMissionState(parsed: unknown): MissionState | null;
+/**
+ * Rotate the mission when its active plan is complete: clear mission.json
+ * so the next start-work run auto-selects instead of zombie-resuming.
+ * Returns `{ rotated: true, state: null }` after clearing, otherwise the
+ * preserved state. Never rewrites an incomplete or missing mission.
+ */
+export declare function rotateMissionIfComplete(directory: string): {
+    rotated: boolean;
+    state: MissionState | null;
+};
+export declare function writeMissionState(directory: string, state: MissionState): boolean;
+export declare function appendSessionId(directory: string, sessionId: string): MissionState | null;
+export declare function clearMissionState(directory: string): boolean;
+/**
+ * Find Oracle plan files for this project.
+ * Oracle stores plans at: {project}/.matrixx/plans/{name}.md
+ */
+export declare function findOraclePlans(directory: string): string[];
+/**
+ * Count checkbox progress from plan content.
+ *
+ * Single content-level implementation behind getPlanProgress: numbered
+ * task lines (Oracle format) win when present, otherwise all top-level
+ * checkboxes count. Indented boxes never count. Do NOT inline checkbox
+ * regexes elsewhere — import the Task 2 constants instead.
+ */
+export declare function countPlanProgressFromContent(content: string): PlanProgress;
+/**
+ * Parse a plan file and count checkbox progress.
+ */
+export declare function getPlanProgress(planPath: string): PlanProgress;
+/**
+ * Extract plan name from file path.
+ */
+export declare function getPlanName(planPath: string): string;
+/**
+ * Create a new mission state for a plan.
+ */
+export declare function createMissionState(planPath: string, sessionId: string, agent?: string): MissionState;

package/dist/features/mission-state/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Mission State Types
+ *
+ * Manages the active work plan state for Morpheus orchestrator.
+ * Named after the Matrix mission - the eternal task that must be rolled.
+ */
+export interface MissionState {
+    /** Absolute path to the active plan file */
+    active_plan: string;
+    /** ISO timestamp when work started */
+    started_at: string;
+    /** Session IDs that have worked on this plan */
+    session_ids: string[];
+    /** Plan name derived from filename */
+    plan_name: string;
+    /** Agent type to use when resuming (e.g., 'niobe') */
+    agent?: string;
+}
+export interface PlanProgress {
+    /** Total number of checkboxes */
+    total: number;
+    /** Number of completed checkboxes */
+    completed: number;
+    /** Whether all tasks are done */
+    isComplete: boolean;
+    /**
+     * True when total is 0 (empty, prose-only, or missing plan).
+     * isComplete stays true by vacuity; callers should log/warn and
+     * route these plans to human triage instead of treating them as done.
+     */
+    needsTriage?: boolean;
+}
+/**
+ * Plan Persistence Types
+ * Machine-parseable metadata appended as HTML comment to plan files
+ */
+/** Machine-parseable metadata appended as HTML comment to plan files */
+export interface PlanMeta {
+    /** Plan file name without .md extension */
+    id: string;
+    /** ISO timestamp of last write */
+    updatedAt: string;
+    /** Session ID that triggered the last write */
+    sessionId: string;
+    /** Total todo count at time of write */
+    todoTotal: number;
+    /** Completed todo count at time of write */
+    todoCompleted: number;
+    /** Git HEAD at time of write (optional) */
+    gitHead?: {
+        sha: string;
+        branch?: string;
+    };
+}
+/** Events the plan-persister hook listens to */
+export type PlanPersistEvent = {
+    type: "session.idle";
+    sessionID: string;
+} | {
+    type: "session.compacted";
+    sessionID: string;
+};
+/** Return value of buildRehydrationContext */
+export interface RehydrationContext {
+    planName: string;
+    planPath: string;
+    content: string;
+    progress: {
+        total: number;
+        completed: number;
+    };
+    directive: string;
+}
+/** Options for the plan-persister hook */
+export interface PlanPersistenceOptions {
+    /** Project root directory */
+    directory: string;
+}

package/dist/features/plan-contract/appendix.d.ts

@@ -0,0 +1,11 @@
+export { collectNamedRegions, findNamedRegion, type NamedRegion, type RegionStart, type RegionStartPredicate, } from "./region";
+/**
+ * Return the ZERO-BASED line index of the first `## Appendix` H2, or `-1` when
+ * the plan has no appendix. "Normalized" means the heading text is trimmed.
+ *
+ * The value is UNCHANGED from the pre-generalization implementation, and this
+ * function is the ONLY place that converts the primitive's 1-based
+ * `startIndex` into a 0-based index — every other consumer works in 1-based
+ * line numbers, matching `PlanSectionIndexEntry`.
+ */
+export declare function findAppendixStart(content: string): number;

package/dist/features/plan-contract/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Plan Contract Constants
+ *
+ * Canonical structure of an Oracle work plan: the ordered H2 sections and the
+ * required per-task grammar. Checkbox regexes are the single source of truth in
+ * mission-state — re-exported here, never re-declared.
+ */
+export { NUMBERED_CHECKED_RE, NUMBERED_UNCHECKED_RE, TOP_CHECKED_RE, TOP_UNCHECKED_RE, } from "../../features/mission-state/constants";
+/** Ordered H2 section titles, exactly as emitted by the Oracle plan template. */
+export declare const CANONICAL_SECTIONS: readonly ["TL;DR", "Context", "Work Objectives", "Global Constraints", "Verification Strategy (MANDATORY)", "Execution Strategy", "Review Focus", "TODOs", "Commit Strategy", "Success Criteria"];
+/** Ordered labels that every TODO task block must declare. */
+export declare const REQUIRED_TASK_SUBFIELDS: readonly ["What to do", "Must NOT do", "Recommended Agent Profile", "Parallelization", "References", "Consumes", "Produces", "Acceptance Criteria", "Agent-Executed QA Scenarios"];
+/** Subfields the validator treats as optional: absence never warns. */
+export declare const OPTIONAL_TASK_SUBFIELDS: readonly ["Must NOT do", "Parallelization"];
+/** Canonical section title union derived from {@link CANONICAL_SECTIONS}. */
+export type PlanSection = (typeof CANONICAL_SECTIONS)[number];
+/** Canonical task subfield label union derived from {@link REQUIRED_TASK_SUBFIELDS}. */
+export type PlanTaskSubfield = (typeof REQUIRED_TASK_SUBFIELDS)[number];

package/dist/features/plan-contract/front-matter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Plan Front-Matter
+ *
+ * Structured YAML front-matter (a leading `---` fenced block) for Oracle plan
+ * files, parsed with `js-yaml`.
+ *
+ * PRECEDENCE: when a front-matter block is present it is authoritative for
+ * `status` and `revision`. The legacy `<!-- plan-persister: {...} -->` comment
+ * (see mission-state `plan-storage.ts`) remains authoritative for `todoTotal`,
+ * `todoCompleted`, `updatedAt` and `sessionId`, and is NEVER removed. Front-matter
+ * is ADDITIVE over that comment, not a replacement.
+ *
+ * WRITE PATH: `status` (and all front-matter fields) is written through the
+ * `plan_update` tool. Ownership is enforced by TRANSITION ORDER, not caller
+ * identity (MatrixxContext carries no caller identity, so ownership by caller
+ * identity is unenforceable): forward transitions (pending -> in_progress ->
+ * completed) are legal, backward transitions are hard-rejected by
+ * `plan_update` with `status_transition_rejected` unless the explicit escape
+ * hatch `{ forceCompletion: true }` is passed. A `completed` status with
+ * unchecked boxes stays advisory-only (WARN), never a hard rejection, so
+ * `status` and checkbox state cannot diverge silently.
+ *
+ * TRANSITIONS (forward-only, see `schema.ts`):
+ * `pending -> in_progress -> completed`. A backward jump (e.g.
+ * `completed -> in_progress`) is rejected by `isPlanStatusTransitionAllowed`
+ * (via `extractStatusEdit` + `adjudicate` in
+ * `src/tools/plan/status-transition.ts`) with `status_transition_rejected`
+ * unless the caller passes the explicit `{ forceCompletion: true }` override.
+ * Same-status rewrites are idempotent and always allowed.
+ *
+ * AND-GATE vs OVERRIDE (completion rule): a plan counts as complete ONLY when
+ * (every numbered checkbox checked AND `status === \"completed\"`), evaluated
+ * by `isPlanComplete`. Any mismatch evaluates to false so the caller surfaces
+ * a WARN advisory instead of silently auto-completing. The explicit override
+ * flag `forceCompletion: true` overrides the gate (advisory records the
+ * override).
+ *
+ * Serialization is IDEMPOTENT: `parse(serialize(parse(content)))` equals
+ * `parse(content)`, and `serialize(parse(serialize(fm)))` equals
+ * `serialize(fm)`. On disagreement `status` comes from the front-matter while
+ * the legacy comment is left untouched.
+ */
+import type { PlanFrontMatter } from "./types";
+/**
+ * Parse the leading YAML front-matter block.
+ *
+ * Returns `null` when the block is absent, malformed, or fails the
+ * {@link PlanFrontMatter} shape (e.g. missing `status`/`revision` or an
+ * out-of-vocabulary status).
+ */
+export declare function parsePlanFrontMatter(content: string): PlanFrontMatter | null;
+/**
+ * Serialize front-matter to a `---` fenced YAML block.
+ *
+ * Optional fields are omitted when `undefined`; array fields are emitted even
+ * when empty. The returned block ends with a trailing newline so it can be
+ * prepended to plan content additively.
+ */
+export declare function serializePlanFrontMatter(fm: PlanFrontMatter): string;

package/dist/features/plan-contract/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plan Contract — barrel
+ *
+ * Foundation module for the plan contract: canonical sections, task grammar,
+ * and the Zod schema for the structured plan view.
+ */
+export { collectNamedRegions, findAppendixStart, findNamedRegion, type NamedRegion, type RegionStart, type RegionStartPredicate, } from "./appendix";
+export { CANONICAL_SECTIONS, NUMBERED_CHECKED_RE, NUMBERED_UNCHECKED_RE, OPTIONAL_TASK_SUBFIELDS, type PlanSection, type PlanTaskSubfield, REQUIRED_TASK_SUBFIELDS, TOP_CHECKED_RE, TOP_UNCHECKED_RE, } from "./constants";
+export { parsePlanFrontMatter, serializePlanFrontMatter } from "./front-matter";
+export { classifyPlanLifecycle, PLAN_LIFECYCLE_CODES, type PlanLifecycleCode, type PlanLifecycleReport, type PlanLifecycleState, type PlanSectionLifecycleResolution, resolveLifecycleSection, } from "./lifecycle";
+export { isGrandfathered, shouldMigrate } from "./migration";
+export { collectHeadings, type HashlineAnchors, type Heading, normalizeSectionTitle, parsePlanContract, parsePlanTasks, } from "./parse";
+export { isPlanComplete, isPlanStatusTransitionAllowed, PLAN_STATUS_ORDER, type PlanCompletionGateInput, type PlanContract, PlanContractSchema, type PlanStatusTransitionOptions } from "./schema";
+export { buildSectionRegistry, CONSENSUS_H3_SEEDS, extractHeadingLevel, extractHeadingText, H3_SECTION_REGISTRY, normalizeSectionKey, PLAN_SECTION_REGISTRY, resolveSectionSelector, SECTION_REGISTRY, type SectionLevel, type SectionRegistryEntry, type SectionRegistrySeed, type SectionResolution, type SectionResolutionKind, } from "./section-registry";
+export { renderPlanSkeleton } from "./skeleton";
+export type { PlanContractResult, PlanContractWarning, PlanFrontMatter, PlanStatus, PlanTask, } from "./types";
+export { validatePlanContract } from "./validate";

package/dist/features/plan-contract/lifecycle.d.ts

@@ -0,0 +1,44 @@
+import { type SectionResolution } from "./section-registry";
+import type { PlanContractWarning } from "./types";
+/** Advisory diagnostic codes. NOT `PlanErrorCode` — see the module header. */
+export declare const PLAN_LIFECYCLE_CODES: {
+    /** Basename left the allowlist but the body is a legacy plan. Fix the key. */
+    readonly legacyPlanRenamed: "legacy_plan_renamed_off_allowlist";
+    /** No front-matter, no legacy metadata, not on the allowlist. */
+    readonly newPlanMissingFrontMatter: "new_plan_missing_front_matter";
+};
+export type PlanLifecycleCode = (typeof PLAN_LIFECYCLE_CODES)[keyof typeof PLAN_LIFECYCLE_CODES];
+/** Which lifecycle bucket a plan falls into, after the allowlist lookup. */
+export type PlanLifecycleState = "modern" | "grandfathered" | "legacy_renamed" | "new_plan_missing_front_matter";
+/** Advisory outcome of a lifecycle lookup. Never carries errors. */
+export interface PlanLifecycleReport {
+    state: PlanLifecycleState;
+    /** Plan basename without `.md` — the key the allowlist is matched on. */
+    planId: string;
+    /** Advisory diagnostics. Empty for `modern` and `grandfathered`. */
+    warnings: PlanContractWarning[];
+}
+/**
+ * Classify a plan's lifecycle and return its ADVISORY diagnostics.
+ *
+ * Rule 1: a missing front-matter block is a lifecycle fact, never an input to
+ * section resolution — this function does not resolve sections.
+ * Rule 4: nothing here writes. The allowlist stays frozen; a renamed plan is
+ * reported so a human can re-key it, never auto-re-adopted.
+ */
+export declare function classifyPlanLifecycle(filePath: string, content: string): PlanLifecycleReport;
+/** A section resolution paired with the lifecycle it was reached under. */
+export interface PlanSectionLifecycleResolution {
+    lifecycle: PlanLifecycleReport;
+    resolution: SectionResolution;
+}
+/**
+ * Resolve a section selector for a plan, identically for every lifecycle state.
+ *
+ * `content` never reaches the registry: sections derive from the BODY, so a
+ * modern plan and the same plan as a legacy file resolve to the same value
+ * (rules 1 and 2). The lifecycle is reported alongside so a caller can attach
+ * the ADVISORY without conflating it with the resolution outcome — a rename
+ * diagnostic never changes what a selector resolves to.
+ */
+export declare function resolveLifecycleSection(selector: string, filePath: string, content: string): PlanSectionLifecycleResolution;

package/dist/features/plan-contract/migration-report.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Plan Contract — Migration Dry-Run Report (Task 4)
+ *
+ * LOCAL-ONLY SEMANTICS: `.matrixx/` is gitignored. Every path scanned and
+ * every recommendation below is local to this clone — nothing here is
+ * committed, pushed, or shared. Do not treat this report as a repo-wide
+ * migration plan.
+ *
+ * Explicit migration = apply-on-touch ONLY (lifecycle rule 4
+ * "Never auto-migrate"): front-matter is added on the next `plan_update`
+ * of a touched plan, never via a batch rewrite. This module performs
+ * ZERO writes: no `plan_update`, no `renameSync`, no `mkdirSync`, no
+ * metadata-comment stripping. It mirrors the `archiveStalePlans`
+ * dry-run + collision-skip + never-delete posture from
+ * `mission-state/reconcile.ts` — candidates are reported, never moved.
+ *
+ * dwfinance-class: a plan with zero numbered tasks (design doc /
+ * `tasks: []` divergence, `needsTriage`) routes to `archive-candidate`,
+ * NEVER to `complete`. Completion requires the Task 2 AND-gate
+ * (`isPlanComplete`); an empty plan cannot satisfy it.
+ */
+import { type PlanLifecycleState } from "./lifecycle";
+/** A recommendation this report is allowed to emit. `complete` is absent by design. */
+export type MigrationRecommendation = "apply-on-touch" | "archive-candidate" | "none";
+export interface PlanMigrationEntry {
+    plan: string;
+    state: PlanLifecycleState;
+    progress: {
+        total: number;
+        completed: number;
+    };
+    hasFrontMatter: boolean;
+    recommendation: MigrationRecommendation;
+}
+/**
+ * Recommend the next step for one scanned plan. Read-only and total.
+ * Zero-task plans are `archive-candidate` (dwfinance-class); plans that
+ * already carry front-matter need nothing (`none`); everything else waits
+ * for apply-on-touch. Never returns `complete`.
+ */
+export declare function recommendPlanMigration(filePath: string, content: string): Omit<PlanMigrationEntry, "plan">;
+/**
+ * Scan `<directory>/.matrixx/plans/*.md` (excluding `_archive/`, the
+ * designed archival path) and classify each plan via `classifyPlanLifecycle`
+ * + `countPlanProgressFromContent` + front-matter parse.
+ *
+ * DRY-RUN: performs zero writes — files are only read. Returns one entry
+ * per plan as a JSON-serializable array.
+ */
+export declare function dryRunMigrationReport(directory?: string): PlanMigrationEntry[];

package/dist/features/plan-contract/migration.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Plan Front-Matter Migration & Grandfathering
+ *
+ * Front-matter is ADDITIVE over the legacy `<!-- plan-persister: {...} -->`
+ * comment (`mission-state/plan-storage.ts`) — it does not replace it. Migration
+ * is apply-on-next-edit ONLY: no `plan_migrate` tool is shipped and no plan is
+ * rewritten automatically.
+ *
+ * Grandfathering protects the pre-existing plan corpus from retro-breaking: a
+ * plan that lacks front-matter is only exempt when its id is on the frozen
+ * {@link GRANDFATHER_ALLOWLIST}. A brand-new plan lacking front-matter is NOT
+ * grandfathered.
+ */
+/**
+ * Frozen allowlist of plan ids (filename without `.md`) that predate the
+ * front-matter requirement — captured from the live `.matrixx/plans` corpus
+ * (23 files) at planning time.
+ *
+ * Grandfathered plans never emit a front-matter warning and are exempt from any
+ * future FAIL-mode front-matter requirement. The exemption clears as soon as
+ * the plan gains a front-matter block.
+ *
+ * WHY THE ARCHIVED `p2.*` ENTRIES STAY (deliberate, not tidiness):
+ * `p2.1-trim-hooks`, `p2.2-generic-recovery-refactor` and `p2.3-evolution-gating`
+ * were MOVED to `.matrixx/plans/_archive/`, but they are NOT removed. Three
+ * code-grounded reasons to keep the keys:
+ *
+ * 1. The lookup is by BASENAME (`basename(filePath, ".md")` in `isGrandfathered`,
+ *    and `classifyPlanLifecycle` in `lifecycle.ts`), not by directory. Archival
+ *    relocates the file but does not change its id, so the key is still the
+ *    correct key for that plan wherever it lives.
+ * 2. The exemption is a property of the plan's HISTORY (it predates the
+ *    front-matter requirement), not of its current location. Archival is a
+ *    storage decision; it does not retroactively make a plan "new".
+ * 3. `src/tools/plan/types.ts` rejects subdirectory paths, so `_archive/` is
+ *    outside the plan-tool surface entirely — a key that resolves to an archived
+ *    file can never be reached through a tool call, and `lifecycle.ts` rule 5
+ *    states the registry deliberately does NOT special-case `_archive/`. Pruning
+ *    would therefore change NO reachable lifecycle state: it would only risk a
+ *    future un-archive (or a `reconcile.ts` archival move that a human later
+ *    reverses) silently demoting a legacy plan from `grandfathered` to
+ *    `legacy_renamed`.
+ *
+ * The list stays at its captured 23 ids. The known hazard is unchanged and
+ * documented in `lifecycle.ts`: a RENAME falls off this list silently and is
+ * surfaced as the advisory `legacy_plan_renamed_off_allowlist` rather than
+ * auto-re-adopted.
+ */
+export declare const GRANDFATHER_ALLOWLIST: readonly string[];
+/**
+ * True IFF the plan has no front-matter AND its id is on the frozen allowlist.
+ *
+ * This is deliberately narrower than "any plan lacking front-matter": a new
+ * non-allowlisted plan returns `false`.
+ */
+export declare function isGrandfathered(filePath: string, content: string): boolean;
+/**
+ * True IFF front-matter is absent, for ANY plan (grandfathered included),
+ * because injection is additive. Idempotent: once front-matter is present this
+ * returns `false`.
+ */
+export declare function shouldMigrate(content: string): boolean;

package/dist/features/plan-contract/parse.d.ts

@@ -0,0 +1,38 @@
+import type { PlanContract } from "./schema";
+import type { PlanTask } from "./types";
+/** Optional caller-supplied LINE#ID anchors keyed by 1-based line number. */
+export type HashlineAnchors = ReadonlyMap<number, string> | Readonly<Record<number, string>>;
+export interface Heading {
+    normalized: string;
+    line: number;
+    index: number;
+}
+export declare function normalizeSectionTitle(title: string): string;
+export declare function parsePlanTasks(content: string, hashlineAnchors?: HashlineAnchors): PlanTask[];
+export declare function collectHeadings(lines: string[]): Heading[];
+/**
+ * Assemble the structured view of a plan.
+ *
+ * `frontMatter` is populated from the leading YAML block via the SINGLE
+ * {@link parsePlanFrontMatter} implementation, so the declared
+ * {@link PlanContract} type and the runtime shape agree. A plan without a block
+ * (or with a malformed one) yields `undefined`, never a synthesized default.
+ */
+export declare function parsePlanContract(content: string): PlanContract;
+/**
+ * The largest TOP-LEVEL (H2) region in `content`, by {@link measurePlanBytes},
+ * or `null` when the plan has no H2 at all.
+ *
+ * Reuses `collectNamedRegions` — the same primitive the section index uses — so
+ * "where does a section end" cannot drift between the two. Bytes go through the
+ * one ruler (`measurePlanBytes`), never a raw `.length`.
+ *
+ * This is what makes the size-cap advisory ACTIONABLE: the total alone says
+ * "too big", the top-level region says "trim THIS one".
+ */
+export declare function largestSection(content: string): {
+    text: string;
+    bytes: number;
+} | null;
+/** True when `content` is at or beyond the advisory size threshold. */
+export declare function isApproachingSizeCap(content: string, cap?: number): boolean;

package/dist/features/plan-contract/region.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Plan Contract — named-region primitive.
+ *
+ * A "region" is a contiguous run of lines introduced by a heading and closed
+ * by the next heading of the SAME OR SHALLOWER level. This is the one place in
+ * `src/` that knows how to bound such a run; `validate.ts` (via `appendix.ts`)
+ * and `src/tools/plan/section-index.ts` are both consumers of it, so a plan
+ * cannot end up with two disagreeing notions of "region".
+ *
+ * INDEX CONVENTION: `startIndex` is 1-BASED and INCLUSIVE (the heading's own
+ * line number). `endIndex` is EXCLUSIVE — the 1-based line number of the next
+ * heading at level <= the region's own level, or `lines.length + 1` at EOF.
+ * A region therefore owns `[startIndex, endIndex)`. This is deliberately the
+ * SAME convention as `PlanSectionIndexEntry.endLine` in `src/tools/plan/types.ts`
+ * (documented there as "Exclusive") so the two can be compared without a
+ * conversion step; `findAppendixStart` converts to a 0-BASED index at its own
+ * boundary, which is the only place that conversion exists.
+ *
+ * DEPENDENCY DIRECTION IS ONE-WAY: consumers (the section index) import this
+ * module; this module imports NOTHING from the section registry. That is
+ * load-bearing. The registry exists so a heading miss can degrade to
+ * `kind:"custom"`, and a region locator exists so a span can be bounded — if
+ * the locator needed registry knowledge, then locating a region could fail the
+ * way a registry lookup fails, and the validator would be one registry change
+ * away from erroring on a perfectly well-formed plan. The registry must never
+ * interact with the validator; the arrow points from the registry's consumers
+ * toward the registry, never back into a primitive the validator depends on.
+ *
+ * Heading text is read from the ORIGINAL line, never from a re-serialized
+ * markdown AST: `mdast-util-to-markdown` is lossy (renumbers lists, reflows
+ * emphasis, drops entity escaping), so a round-tripped heading would not match
+ * the text the user actually wrote.
+ */
+/** Markdown heading depth this primitive can bound. H4+ is not a region root. */
+export type RegionLevel = 2 | 3;
+/**
+ * A bounded region of a plan. `startIndex` is inclusive, `endIndex` is
+ * exclusive; see the module header for the full convention.
+ */
+export interface NamedRegion {
+    /** Heading depth of the region's opening heading. */
+    level: RegionLevel;
+    /** Heading text exactly as it appears in the plan (trailing space trimmed). */
+    text: string;
+    /** 1-BASED, INCLUSIVE line number of the opening heading. */
+    startIndex: number;
+    /** EXCLUSIVE 1-based line number: the closing heading, or lines.length + 1. */
+    endIndex: number;
+}
+/** What a caller sees when deciding whether a heading opens the region it wants. */
+export type RegionStart = Omit<NamedRegion, "endIndex">;
+export type RegionStartPredicate = (heading: RegionStart) => boolean;
+/**
+ * Bound every H2/H3 region in `content`, in document order.
+ *
+ * This is the shared engine: {@link findNamedRegion} is a filter over it, and
+ * `buildSectionIndex` in `src/tools/plan/section-index.ts` maps it onto
+ * `PlanSectionIndexEntry`. One scan, one closing rule, no drift.
+ */
+export declare function collectNamedRegions(content: string): NamedRegion[];
+/**
+ * The first H2/H3 region whose opening heading satisfies `predicate`, or `null`
+ * when no heading matches. The scan is in document order, so a caller that
+ * matches a common word can get an earlier region than it expects — make the
+ * predicate specific when that matters.
+ */
+export declare function findNamedRegion(content: string, predicate: RegionStartPredicate): NamedRegion | null;

package/dist/features/plan-contract/schema.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Plan Contract Schema
+ *
+ * Zod v4 schema for the STRUCTURED view of an Oracle plan. The Markdown grammar
+ * itself is parsed elsewhere; this validates the parsed shape.
+ */
+import { z } from "zod";
+/**
+ * The contract shape, plus the two invariants the parser guarantees and a bare
+ * `z.array(z.string())` could not express.
+ *
+ * 1. `sections` entries are non-empty. A heading whose title normalizes away to
+ *    nothing (e.g. a bare `## (MANDATORY)`) is a PARSER artefact, not a
+ *    section, and silently accepting one would let a malformed heading reach
+ *    every section-addressed consumer as a nameless target.
+ * 2. `tasks` are in ASCENDING document order. `parsePlanTasks` is a single
+ *    top-down scan, so ordering is a real invariant; enforcing it here catches a
+ *    future re-implementation that sorts or filters tasks.
+ *
+ * `title` is deliberately NOT constrained to be non-empty: the live corpus
+ * contains real numbered tasks written as `- [x] 11.` with no title text
+ * (`plan-section-addressing.md`), and a plan is not wrong just because a task
+ * line is terse. Constraining it would be tightening the schema against
+ * reality rather than describing it.
+ *
+ * Both invariants were verified against every plan in `.matrixx/plans/` before
+ * being added (0 violations across 36 plans / 289 tasks).
+ */
+export declare const PlanContractSchema: z.ZodObject<{
+    frontMatter: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            in_progress: "in_progress";
+        }>;
+        revision: z.ZodNumber;
+        phase: z.ZodOptional<z.ZodString>;
+        wave: z.ZodOptional<z.ZodString>;
+        deps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        blockedBy: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    sections: z.ZodArray<z.ZodString>;
+    tasks: z.ZodArray<z.ZodObject<{
+        n: z.ZodNumber;
+        title: z.ZodString;
+        checked: z.ZodBoolean;
+        line: z.ZodNumber;
+        anchor: z.ZodString;
+    }, z.core.$strip>>;
+    dod: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** Parsed, validated structured view of a plan. */
+export type PlanContract = z.infer<typeof PlanContractSchema>;
+/**
+ * Canonical forward order of {@link PlanStatus}. Frozen: pending (0) ->
+ * in_progress (1) -> completed (2). A transition is forward when its target
+ * index is >= its source index (identity rewrites are idempotent, not jumps).
+ */
+export declare const PLAN_STATUS_ORDER: readonly ["pending", "in_progress", "completed"];
+/**
+ * Transition options for {@link isPlanStatusTransitionAllowed}.
+ *
+ * Consumed on the `plan_update` write path via
+ * `src/tools/plan/status-transition.ts`: `extractStatusEdit` extracts the
+ * intended before/after pair and `adjudicate` forwards these options through
+ * to this helper. The write-path argument contract is `ForceCompletionOptions`
+ * in `status-transition.ts`, structurally identical to this interface, so it
+ * passes straight through to `isPlanStatusTransitionAllowed`. A backward jump
+ * rejected here surfaces as `status_transition_rejected` (see
+ * `PLAN_ERROR_CODES` in `src/tools/plan/error-codes.ts`).
+ */
+export interface PlanStatusTransitionOptions {
+    /** When true, a backward jump is honored instead of rejected. */
+    forceCompletion?: boolean;
+}
+/**
+ * Forward-only transition rule (enforced on the `plan_update` write path).
+ *
+ * Consumed by `adjudicate` in `src/tools/plan/status-transition.ts` after
+ * `extractStatusEdit` extracts the before/after pair; a rejection surfaces as
+ * `status_transition_rejected`. Returns true when moving from `from` to `to`
+ * is allowed: same-status or forward steps always pass; a backward step passes
+ * ONLY with `{ forceCompletion: true }` (the `ForceCompletionOptions` escape
+ * hatch). Unknown statuses (outside the enum) return false — the schema
+ * rejects them at parse time and this guard rejects them at transition time.
+ */
+export declare function isPlanStatusTransitionAllowed(from: string, to: string, options?: PlanStatusTransitionOptions): boolean;
+/** Inputs to the completion AND-gate (checkbox state + front-matter status). */
+export interface PlanCompletionGateInput {
+    /** True when every numbered checkbox in the plan body is checked. */
+    allChecked: boolean;
+    /** Authoritative front-matter `status` value. */
+    status: string;
+    /** Explicit override; when true the gate passes regardless. */
+    forceCompletion?: boolean;
+}
+/**
+ * AND-gate vs override rule for plan completion.
+ *
+ * A plan counts as complete ONLY when (all checkboxes checked AND
+ * `status === \"completed\"`). Any mismatch (checked but status lagging, or
+ * status completed while boxes remain open) evaluates to false so the caller
+ * can surface a WARN advisory — never silently auto-complete. The explicit
+ * override flag `{ forceCompletion: true }` overrides the gate and returns true.
+ */
+export declare function isPlanComplete(input: PlanCompletionGateInput): boolean;

package/dist/features/plan-contract/section-registry-h3.d.ts

@@ -0,0 +1,14 @@
+/**
+ * H3 consensus seeds — the 14 empirically-common H3 headings across the
+ * 35-plan corpus. Held in their own module purely for the 200-LOC budget;
+ * the ids are DERIVED by `buildSectionRegistry` in `section-registry.ts`,
+ * never hand-written here.
+ *
+ * WHY EXACT SPELLINGS: each string is the canonical text the plan skeleton
+ * emits (`skeleton.ts` section bodies), so an id derived here is the same id
+ * a real plan produces. Do NOT add aliases for `### If TDD Enabled` or
+ * `### Agent-Executed QA Scenarios (MANDATORY — ALL tasks)` — those are
+ * deliberately unregistered and land in the `custom` escape hatch.
+ */
+import type { SectionRegistrySeed } from "./section-registry";
+export declare const CONSENSUS_H3_SEEDS: readonly SectionRegistrySeed[];