@buildaharness/aielia 0.3.3 → 0.3.5

package/dist/goal-graph-store.d.ts

@@ -0,0 +1,485 @@
+import { z } from 'zod';
+import { MemoryAdapter } from '@buildaharness/runtime';
+import { PlanFsPersistence, PlanRecord } from './plan-store.js';
+export declare const GoalThreadStatusSchema: z.ZodEnum<["READY", "ACTIVE", "BLOCKED", "PAUSED", "DONE", "ABANDONED"]>;
+export type GoalThreadStatus = z.infer<typeof GoalThreadStatusSchema>;
+/**
+ * R3's two reasons for multiple root nodes, handled oppositely: `alternative` roots are competing
+ * guesses at one intent (resolving one abandons the others), `concurrent` roots are genuinely
+ * separate goals that coexist. Absent for a thread with no siblings needing disambiguation.
+ */
+export declare const SiblingRelationSchema: z.ZodEnum<["alternative", "concurrent"]>;
+export type SiblingRelation = z.infer<typeof SiblingRelationSchema>;
+declare const GoalTaskRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    depends_on: z.ZodArray<z.ZodString, "many">;
+    status: z.ZodEnum<["PENDING", "RUNNING", "COMPLETE", "FAILED", "BLOCKED", "HUMAN_REQUIRED"]>;
+    riskLevel: z.ZodOptional<z.ZodEnum<["LOW", "MEDIUM", "HIGH"]>>;
+    cancelled: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+    description: string;
+    depends_on: string[];
+    riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+    cancelled?: boolean | undefined;
+}, {
+    id: string;
+    status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+    description: string;
+    depends_on: string[];
+    riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+    cancelled?: boolean | undefined;
+}>;
+export type GoalTaskRecord = z.infer<typeof GoalTaskRecordSchema>;
+/**
+ * A persisted next-step suggestion (R7) — what next-step-proposer.ts's `proposeNextSteps()` yields
+ * for a thread that just reached DONE, minus `goalThreadId` (it lives on the thread that owns it).
+ * Advisory only: a suggestion is never a task on the thread and is never executed; the user acts on
+ * it, if at all, by simply asking. `promotion` records the confidence policy that admitted it
+ * (`auto` = high confidence, `pending_confirm` = medium); `session_only` (low confidence)
+ * suggestions are never persisted, so they don't appear here.
+ */
+export declare const ThreadSuggestionSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    rationale: z.ZodString;
+    confidence: z.ZodEnum<["high", "medium", "low"]>;
+    promotion: z.ZodEnum<["auto", "pending_confirm", "session_only"]>;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    rationale: string;
+    id: string;
+    confidence: "high" | "medium" | "low";
+    description: string;
+    createdAt: string;
+    promotion: "auto" | "pending_confirm" | "session_only";
+}, {
+    rationale: string;
+    id: string;
+    confidence: "high" | "medium" | "low";
+    description: string;
+    createdAt: string;
+    promotion: "auto" | "pending_confirm" | "session_only";
+}>;
+export type ThreadSuggestion = z.infer<typeof ThreadSuggestionSchema>;
+/**
+ * One node in the persisted goal DAG (R2). Absorbs PlanRecord's exact shape (Q1) — templateName
+ * through updatedAt below are unchanged in meaning from PlanRecord — plus the fields that make a
+ * thread schedulable: a stable `id` (PlanRecord had none, being a singleton), a scheduler-facing
+ * `status` distinct from `mode` (which is about this thread's own Tier-2 drafting/approval
+ * lifecycle, not whether the Scheduler may currently give it focus — see INV-40), and R3's sibling
+ * relation for when this thread is one of several roots.
+ */
+export declare const GoalThreadSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<["READY", "ACTIVE", "BLOCKED", "PAUSED", "DONE", "ABANDONED"]>;
+    relationToSiblings: z.ZodOptional<z.ZodEnum<["alternative", "concurrent"]>>;
+    /** Sibling GoalThread ids this one is grouped with as competing/concurrent roots (R3). */
+    siblingIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** templateName..updatedAt: absorbed from PlanRecord unchanged (Q1). */
+    templateName: z.ZodNullable<z.ZodString>;
+    successCriteria: z.ZodString;
+    rationale: z.ZodString;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        depends_on: z.ZodArray<z.ZodString, "many">;
+        status: z.ZodEnum<["PENDING", "RUNNING", "COMPLETE", "FAILED", "BLOCKED", "HUMAN_REQUIRED"]>;
+        riskLevel: z.ZodOptional<z.ZodEnum<["LOW", "MEDIUM", "HIGH"]>>;
+        cancelled: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+        description: string;
+        depends_on: string[];
+        riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+        cancelled?: boolean | undefined;
+    }, {
+        id: string;
+        status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+        description: string;
+        depends_on: string[];
+        riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+        cancelled?: boolean | undefined;
+    }>, "many">;
+    mode: z.ZodEnum<["drafting", "awaiting_approval", "active", "done", "abandoned"]>;
+    reviewNotes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    verifiedAt: z.ZodOptional<z.ZodString>;
+    executingOnPlan: z.ZodBoolean;
+    /** Advisory next steps proposed when this thread reached DONE — see ThreadSuggestionSchema. */
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        rationale: z.ZodString;
+        confidence: z.ZodEnum<["high", "medium", "low"]>;
+        promotion: z.ZodEnum<["auto", "pending_confirm", "session_only"]>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        rationale: string;
+        id: string;
+        confidence: "high" | "medium" | "low";
+        description: string;
+        createdAt: string;
+        promotion: "auto" | "pending_confirm" | "session_only";
+    }, {
+        rationale: string;
+        id: string;
+        confidence: "high" | "medium" | "low";
+        description: string;
+        createdAt: string;
+        promotion: "auto" | "pending_confirm" | "session_only";
+    }>, "many">>;
+    trustApprovedSteps: z.ZodOptional<z.ZodBoolean>;
+    planApprovalId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    rationale: string;
+    id: string;
+    status: "BLOCKED" | "READY" | "ACTIVE" | "PAUSED" | "DONE" | "ABANDONED";
+    tasks: {
+        id: string;
+        status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+        description: string;
+        depends_on: string[];
+        riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+        cancelled?: boolean | undefined;
+    }[];
+    successCriteria: string;
+    mode: "active" | "done" | "drafting" | "awaiting_approval" | "abandoned";
+    createdAt: string;
+    templateName: string | null;
+    executingOnPlan: boolean;
+    updatedAt: string;
+    relationToSiblings?: "alternative" | "concurrent" | undefined;
+    siblingIds?: string[] | undefined;
+    reviewNotes?: string[] | undefined;
+    verifiedAt?: string | undefined;
+    suggestions?: {
+        rationale: string;
+        id: string;
+        confidence: "high" | "medium" | "low";
+        description: string;
+        createdAt: string;
+        promotion: "auto" | "pending_confirm" | "session_only";
+    }[] | undefined;
+    trustApprovedSteps?: boolean | undefined;
+    planApprovalId?: string | undefined;
+}, {
+    rationale: string;
+    id: string;
+    status: "BLOCKED" | "READY" | "ACTIVE" | "PAUSED" | "DONE" | "ABANDONED";
+    tasks: {
+        id: string;
+        status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+        description: string;
+        depends_on: string[];
+        riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+        cancelled?: boolean | undefined;
+    }[];
+    successCriteria: string;
+    mode: "active" | "done" | "drafting" | "awaiting_approval" | "abandoned";
+    createdAt: string;
+    templateName: string | null;
+    executingOnPlan: boolean;
+    updatedAt: string;
+    relationToSiblings?: "alternative" | "concurrent" | undefined;
+    siblingIds?: string[] | undefined;
+    reviewNotes?: string[] | undefined;
+    verifiedAt?: string | undefined;
+    suggestions?: {
+        rationale: string;
+        id: string;
+        confidence: "high" | "medium" | "low";
+        description: string;
+        createdAt: string;
+        promotion: "auto" | "pending_confirm" | "session_only";
+    }[] | undefined;
+    trustApprovedSteps?: boolean | undefined;
+    planApprovalId?: string | undefined;
+}>;
+export type GoalThread = z.infer<typeof GoalThreadSchema>;
+/**
+ * The persisted DAG itself (R2): `threads` is the full set of goal threads known this session,
+ * `activeThreadId` is the O(1) current-focus pointer every downstream mechanism (classifier,
+ * Scheduler, next-step proposer, Tier-2 scoping) needs answerable without a graph traversal —
+ * see the "current-focus / task→goal linkage primitive" gap this plan's design brief calls out.
+ * INV-38/39 (at most one ACTIVE thread, Scheduler is the sole writer of this pointer) are enforced
+ * starting Phase 5, not here — this phase only defines the shape.
+ */
+export declare const GoalGraphRecordSchema: z.ZodObject<{
+    threads: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<["READY", "ACTIVE", "BLOCKED", "PAUSED", "DONE", "ABANDONED"]>;
+        relationToSiblings: z.ZodOptional<z.ZodEnum<["alternative", "concurrent"]>>;
+        /** Sibling GoalThread ids this one is grouped with as competing/concurrent roots (R3). */
+        siblingIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** templateName..updatedAt: absorbed from PlanRecord unchanged (Q1). */
+        templateName: z.ZodNullable<z.ZodString>;
+        successCriteria: z.ZodString;
+        rationale: z.ZodString;
+        tasks: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodString;
+            depends_on: z.ZodArray<z.ZodString, "many">;
+            status: z.ZodEnum<["PENDING", "RUNNING", "COMPLETE", "FAILED", "BLOCKED", "HUMAN_REQUIRED"]>;
+            riskLevel: z.ZodOptional<z.ZodEnum<["LOW", "MEDIUM", "HIGH"]>>;
+            cancelled: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+            description: string;
+            depends_on: string[];
+            riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+            cancelled?: boolean | undefined;
+        }, {
+            id: string;
+            status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+            description: string;
+            depends_on: string[];
+            riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+            cancelled?: boolean | undefined;
+        }>, "many">;
+        mode: z.ZodEnum<["drafting", "awaiting_approval", "active", "done", "abandoned"]>;
+        reviewNotes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        verifiedAt: z.ZodOptional<z.ZodString>;
+        executingOnPlan: z.ZodBoolean;
+        /** Advisory next steps proposed when this thread reached DONE — see ThreadSuggestionSchema. */
+        suggestions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodString;
+            rationale: z.ZodString;
+            confidence: z.ZodEnum<["high", "medium", "low"]>;
+            promotion: z.ZodEnum<["auto", "pending_confirm", "session_only"]>;
+            createdAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            rationale: string;
+            id: string;
+            confidence: "high" | "medium" | "low";
+            description: string;
+            createdAt: string;
+            promotion: "auto" | "pending_confirm" | "session_only";
+        }, {
+            rationale: string;
+            id: string;
+            confidence: "high" | "medium" | "low";
+            description: string;
+            createdAt: string;
+            promotion: "auto" | "pending_confirm" | "session_only";
+        }>, "many">>;
+        trustApprovedSteps: z.ZodOptional<z.ZodBoolean>;
+        planApprovalId: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        rationale: string;
+        id: string;
+        status: "BLOCKED" | "READY" | "ACTIVE" | "PAUSED" | "DONE" | "ABANDONED";
+        tasks: {
+            id: string;
+            status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+            description: string;
+            depends_on: string[];
+            riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+            cancelled?: boolean | undefined;
+        }[];
+        successCriteria: string;
+        mode: "active" | "done" | "drafting" | "awaiting_approval" | "abandoned";
+        createdAt: string;
+        templateName: string | null;
+        executingOnPlan: boolean;
+        updatedAt: string;
+        relationToSiblings?: "alternative" | "concurrent" | undefined;
+        siblingIds?: string[] | undefined;
+        reviewNotes?: string[] | undefined;
+        verifiedAt?: string | undefined;
+        suggestions?: {
+            rationale: string;
+            id: string;
+            confidence: "high" | "medium" | "low";
+            description: string;
+            createdAt: string;
+            promotion: "auto" | "pending_confirm" | "session_only";
+        }[] | undefined;
+        trustApprovedSteps?: boolean | undefined;
+        planApprovalId?: string | undefined;
+    }, {
+        rationale: string;
+        id: string;
+        status: "BLOCKED" | "READY" | "ACTIVE" | "PAUSED" | "DONE" | "ABANDONED";
+        tasks: {
+            id: string;
+            status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+            description: string;
+            depends_on: string[];
+            riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+            cancelled?: boolean | undefined;
+        }[];
+        successCriteria: string;
+        mode: "active" | "done" | "drafting" | "awaiting_approval" | "abandoned";
+        createdAt: string;
+        templateName: string | null;
+        executingOnPlan: boolean;
+        updatedAt: string;
+        relationToSiblings?: "alternative" | "concurrent" | undefined;
+        siblingIds?: string[] | undefined;
+        reviewNotes?: string[] | undefined;
+        verifiedAt?: string | undefined;
+        suggestions?: {
+            rationale: string;
+            id: string;
+            confidence: "high" | "medium" | "low";
+            description: string;
+            createdAt: string;
+            promotion: "auto" | "pending_confirm" | "session_only";
+        }[] | undefined;
+        trustApprovedSteps?: boolean | undefined;
+        planApprovalId?: string | undefined;
+    }>, "many">;
+    activeThreadId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    updatedAt: string;
+    threads: {
+        rationale: string;
+        id: string;
+        status: "BLOCKED" | "READY" | "ACTIVE" | "PAUSED" | "DONE" | "ABANDONED";
+        tasks: {
+            id: string;
+            status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+            description: string;
+            depends_on: string[];
+            riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+            cancelled?: boolean | undefined;
+        }[];
+        successCriteria: string;
+        mode: "active" | "done" | "drafting" | "awaiting_approval" | "abandoned";
+        createdAt: string;
+        templateName: string | null;
+        executingOnPlan: boolean;
+        updatedAt: string;
+        relationToSiblings?: "alternative" | "concurrent" | undefined;
+        siblingIds?: string[] | undefined;
+        reviewNotes?: string[] | undefined;
+        verifiedAt?: string | undefined;
+        suggestions?: {
+            rationale: string;
+            id: string;
+            confidence: "high" | "medium" | "low";
+            description: string;
+            createdAt: string;
+            promotion: "auto" | "pending_confirm" | "session_only";
+        }[] | undefined;
+        trustApprovedSteps?: boolean | undefined;
+        planApprovalId?: string | undefined;
+    }[];
+    activeThreadId: string | null;
+}, {
+    createdAt: string;
+    updatedAt: string;
+    threads: {
+        rationale: string;
+        id: string;
+        status: "BLOCKED" | "READY" | "ACTIVE" | "PAUSED" | "DONE" | "ABANDONED";
+        tasks: {
+            id: string;
+            status: "BLOCKED" | "HUMAN_REQUIRED" | "PENDING" | "RUNNING" | "COMPLETE" | "FAILED";
+            description: string;
+            depends_on: string[];
+            riskLevel?: "HIGH" | "MEDIUM" | "LOW" | undefined;
+            cancelled?: boolean | undefined;
+        }[];
+        successCriteria: string;
+        mode: "active" | "done" | "drafting" | "awaiting_approval" | "abandoned";
+        createdAt: string;
+        templateName: string | null;
+        executingOnPlan: boolean;
+        updatedAt: string;
+        relationToSiblings?: "alternative" | "concurrent" | undefined;
+        siblingIds?: string[] | undefined;
+        reviewNotes?: string[] | undefined;
+        verifiedAt?: string | undefined;
+        suggestions?: {
+            rationale: string;
+            id: string;
+            confidence: "high" | "medium" | "low";
+            description: string;
+            createdAt: string;
+            promotion: "auto" | "pending_confirm" | "session_only";
+        }[] | undefined;
+        trustApprovedSteps?: boolean | undefined;
+        planApprovalId?: string | undefined;
+    }[];
+    activeThreadId: string | null;
+}>;
+export type GoalGraphRecord = z.infer<typeof GoalGraphRecordSchema>;
+/** Same `{backend, workspaceRoot}` pair as PlanFsPersistence — a goal graph and its session's plan file live in the same workspace. */
+export type GoalGraphFsPersistence = PlanFsPersistence;
+/**
+ * Wraps an existing `PlanRecord` into the single `GoalThread` it becomes under Q1's "absorb, don't
+ * duplicate" resolution — nothing in `plan`'s own fields is dropped.
+ */
+export declare function createGoalThreadFromPlanRecord(plan: PlanRecord, id?: string): GoalThread;
+/** A fresh, empty goal graph — no threads, nothing active. */
+export declare function createEmptyGoalGraphRecord(): GoalGraphRecord;
+/** Wraps a single pre-existing `PlanRecord` into a one-thread `GoalGraphRecord` — the migration path's output shape. */
+export declare function createGoalGraphRecordFromPlanRecord(plan: PlanRecord): GoalGraphRecord;
+/**
+ * R2's O(1) locatability primitive, live as of Phase 4: the currently-focused thread, found by a
+ * direct field lookup (`activeThreadId`), never a graph traversal. Defensive about a transient
+ * inconsistency Phase 4 can produce (see goal-graph-reconcile.ts): a NEW_GOAL/CANCEL_CURRENT
+ * steering message can pause/abandon the thread `activeThreadId` still points at, ahead of Phase
+ * 5's Scheduler ever reassigning that pointer (INV-39 — only the Scheduler writes it) — so this
+ * only returns a thread whose own `status` is still genuinely `ACTIVE`, not just pointed-at.
+ */
+export declare function getActiveThread(record: GoalGraphRecord): GoalThread | null;
+/** R2's task→goal parent-link query — every task belonging to `goalId`, a direct field filter, never a traversal. */
+export declare function tasksForGoal(record: GoalGraphRecord, goalId: string): GoalTaskRecord[];
+/**
+ * Every thread the Scheduler could hand focus to right now (Phase 5): READY, and not mid-Tier-2
+ * drafting or awaiting approval (INV-40). A drafting thread's `status` is READY (see
+ * createGoalThreadFromPlanRecord / mintConcurrentReadyThread), so the exclusion has to look at
+ * `mode`, not just `status` — until 2026-09-23 this filtered on status alone, which quietly made
+ * INV-40 false: a thread minted by a NEW_GOAL steering message (mode 'drafting') was eligible for
+ * focus. The identity matcher (goal-thread-identity.ts) is what adopts such a thread, by matching
+ * a real turn to it and promoting its mode to 'active'.
+ */
+export declare function readyThreads(record: GoalGraphRecord): GoalThread[];
+/**
+ * R4's NEW_GOAL branch (both IMMEDIATE and DEFERRED collapse to this in Phase 4 — see
+ * check-caller-updates.ts's cancel_current sibling doc comment and the plan's resolved
+ * "ACTIVE-pointer write authority" decision: Tier-1 never writes `activeThreadId` itself, it only
+ * pauses the old thread and mints the new one READY; Phase 5's Scheduler decides what becomes
+ * ACTIVE next). `pauseThreadId`, when given and currently ACTIVE, transitions to PAUSED and is
+ * linked to the new thread as a `concurrent` sibling (R3) — never `alternative`, since a NEW_GOAL
+ * is a genuinely separate objective, not a competing guess at the same one.
+ */
+export declare function mintConcurrentReadyThread(record: GoalGraphRecord, description: string, pauseThreadId?: string | null): GoalGraphRecord;
+/** R4's CANCEL_CURRENT branch — marks a thread ABANDONED. Kept for audit trail, never removed from `threads`. */
+export declare function abandonThread(record: GoalGraphRecord, threadId: string): GoalGraphRecord;
+export declare function saveGoalGraphRecord(memory: MemoryAdapter, sessionId: string, record: GoalGraphRecord, fsPersistence?: GoalGraphFsPersistence): Promise<void>;
+/**
+ * Loads `sessionId`'s goal graph, migrating a pre-existing `PlanRecord` in place the first time
+ * this is called for a session that predates this mechanism (P5-equivalent non-destructive
+ * discipline — same as `migrateFact`/`migratePlanRecord`: the old record's data is never silently
+ * dropped, just re-shaped and persisted once under the new key). Every call after that first one
+ * finds the migrated `GoalGraphRecord` directly and never re-touches the legacy `PlanRecord`.
+ *
+ * When `fsPersistence` is configured and its goal-graph JSON file exists, that file wins over the
+ * Dexie/State-tier record, mirroring `loadPlanRecord`'s own fs-file-wins-then-reconcile behavior
+ * (INV-33's discipline, applied here too: the result is written back into `memory` so the two
+ * never stay silently split).
+ */
+export declare function loadGoalGraphRecord(memory: MemoryAdapter, sessionId: string, fsPersistence?: GoalGraphFsPersistence): Promise<GoalGraphRecord | null>;
+/**
+ * Appends advisory `suggestions` to `threadId`, skipping any whose description (case-insensitive,
+ * trimmed) the thread already carries — proposing again for the same DONE thread must not stack
+ * duplicates. `session_only` suggestions are dropped here (low confidence is advisory for the turn
+ * that produced it, never persisted). A `threadId` not present in `record.threads` is a no-op.
+ */
+export declare function addThreadSuggestions(record: GoalGraphRecord, threadId: string, suggestions: ThreadSuggestion[]): GoalGraphRecord;
+export {};

package/dist/goal-graph-suggest-flag.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure logic backing the hierarchical-goal-tree mechanism's Tier 1.5 gate — the next-step
+ * proposer (Phase 6, `next-step-proposer.ts`) — see
+ * plans/hierarchical_goal_tree_and_steering_plan.html. Split out into its own file/flag rather
+ * than folded into `goal-graph-flag.ts`, matching this codebase's one-flag-per-file convention
+ * (`one-loop-flag.ts`/`ask-mode-flag.ts`/`plan-mode-flag.ts`/`goal-graph-flag.ts`) and the plan's
+ * own "Rollout discipline" resolution (2026-09-22): gated independently of `goalGraphMode` since a
+ * regression in the next-step proposer shouldn't block Tier 0/1 (the steering channel, classifier,
+ * persistent `GoalGraphRecord`).
+ *
+ * As of Phase 8, threaded through `AssistantConfig` exactly like `goal-graph-flag.ts`:
+ * `goalGraphSuggestMode` is a real config field with `/config set` support, a
+ * `VITE_ASSISTANT_GOAL_GRAPH_SUGGEST` build-time line in chat-ui's browser-config.ts, and
+ * flag-chain resolution tests (cli-config.test.ts, browser-config.test.ts) — resolved via
+ * `normalizeGoalGraphSuggestMode` below, mirroring `normalizeGoalGraphMode` exactly. No production
+ * call site reads `config.goalGraphSuggestMode` yet (`next-step-proposer.ts`'s
+ * `proposeNextSteps()` still takes its `suggestMode` argument directly from whichever caller wires
+ * it in, and no caller does that yet — see that file's own notes), so this remains inert beyond
+ * the config seam itself.
+ *
+ * Default OFF ('disabled'): `next-step-proposer.ts`'s `proposeNextSteps()` returns `[]` without
+ * making any LLM call, so a flag-off session sees zero behavior change (INV-43).
+ */
+export type GoalGraphSuggestMode = 'enabled' | 'disabled';
+export declare const DEFAULT_GOAL_GRAPH_SUGGEST_MODE: GoalGraphSuggestMode;
+/** See isGoalGraphEnabled (goal-graph-flag.ts) — same undefined-means-package-default rule. */
+export declare function isGoalGraphSuggestEnabled(mode: GoalGraphSuggestMode | undefined): boolean;
+/**
+ * Same signature/typo-tolerance-with-a-warning convention as `normalizeGoalGraphMode`: an unset or
+ * empty value falls back to the default silently, an unrecognized non-empty value falls back with
+ * a startup warning naming `varName`.
+ */
+export declare function normalizeGoalGraphSuggestMode(raw: string | undefined, varName?: string): GoalGraphSuggestMode;
+export declare function resolveGoalGraphSuggestMode(env: NodeJS.ProcessEnv): GoalGraphSuggestMode;

package/dist/goal-identity-matcher.d.ts

@@ -0,0 +1,21 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+export interface GoalCandidate {
+    id: string;
+    /** A short description of the goal's intent — e.g. a GoalThread's successCriteria/rationale — used as the identity anchor for matching, not its full task list. */
+    description: string;
+}
+export interface GoalIdentityMatchResult {
+    /** The existing candidate this message's intent matches, or null when nothing matches — including on ambiguity, see `ambiguous`. Always one of `candidates`' ids, never a dangling/unrecognized one. */
+    matchedGoalId: string | null;
+    /** True when more than one candidate plausibly matches and the model couldn't confidently pick a single one. matchedGoalId is always null in this case — never guess a specific attachment, same fail-safe direction as no-match at all. */
+    ambiguous: boolean;
+}
+/**
+ * One bounded LLM call per incoming steering message, only when there's at least one existing
+ * goal thread to match against. Falls back to "no match, treat as new" — the same fail-safe
+ * direction as an unrecognized/dangling id or genuine ambiguity — on any parse failure or LLM
+ * error, matching this codebase's other LLM-backed classifiers (classifyTurnIntent,
+ * checkForContradictions): a missed match costs nothing worse than spinning up an extra
+ * `concurrent` goal root, never a wrong attachment to the wrong thread.
+ */
+export declare function matchGoalIdentity(message: string, candidates: GoalCandidate[], llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<GoalIdentityMatchResult>;

package/dist/goal-thread-identity.d.ts

@@ -0,0 +1,32 @@
+import { ILLMClient, MemoryAdapter, TokenUsage } from '@buildaharness/runtime';
+import { GoalGraphFsPersistence } from './goal-graph-store.js';
+/**
+ * Cross-turn goal identity, wired into the turn (plans/hierarchical_goal_tree_and_steering_plan.html
+ * Phase 2's matcher, unused until now): decides which goal thread a full turn belongs to, so a
+ * message that continues an earlier goal gets that goal's thread back in focus (with its paused
+ * evidence intact) and a message about something new starts its own thread. This is what makes
+ * the graph fill in for ordinary conversation; before it, threads only came from a session plan or
+ * a NEW_GOAL steering message.
+ *
+ *  - candidates: every thread that is not finished (READY / ACTIVE / PAUSED / BLOCKED — including a
+ *    placeholder a NEW_GOAL steering message minted, which is how that deferred ask finds its
+ *    thread again when it runs as its own turn). DONE and ABANDONED goals are not reopened.
+ *  - matched → `focusThread` (the Scheduler's single write path, INV-39); a BLOCKED match keeps
+ *    its status but is still the thread this turn's evidence lands on.
+ *  - no match or ambiguous → `startThread`. Ambiguity is never guessed into an attachment
+ *    (same fail-safe as the matcher: a missed match costs an extra thread, a wrong one costs work
+ *    landing on the wrong goal).
+ *  - no candidates → `startThread` with no LLM call at all.
+ *
+ * Best-effort by construction: any failure (memory, matcher) resolves to "no thread" for this turn,
+ * exactly as if the goal graph were off. Returns the thread id this turn's evidence should land on.
+ */
+export declare function resolveTurnGoalThread(params: {
+    userMessage: string;
+    sessionId: string;
+    memory: MemoryAdapter;
+    llmClient: ILLMClient;
+    model?: string;
+    onUsage?: (usage: TokenUsage) => void;
+    fsPersistence?: GoalGraphFsPersistence;
+}): Promise<string | undefined>;

package/dist/goal-thread-scheduler.d.ts

@@ -0,0 +1,78 @@
+import { GoalGraphRecord, GoalThread } from './goal-graph-store.js';
+/**
+ * Phase 5 of plans/hierarchical_goal_tree_and_steering_plan.html — the Scheduler: the sole writer
+ * of `GoalGraphRecord.activeThreadId` (INV-39), enforcing single-focus v1 (INV-38 — at most one
+ * `ACTIVE` thread at a time) and READY-only selection that excludes anything mid-Tier-2-drafting
+ * (INV-40, via `readyThreads()`'s own `status`+`mode` filter).
+ *
+ * Per the plan's resolved "ACTIVE-pointer write authority" decision, IMMEDIATE and DEFERRED
+ * steering both call this *same* selection function with the *same* exclusion rules — the only
+ * difference is *when* a caller invokes it: `goal-graph-reconcile.ts`'s NEW_GOAL branch calls it
+ * synchronously, this same iteration, for IMMEDIATE; DEFERRED leaves it for the next natural pass
+ * (today, `assistant.ts`'s own per-turn call at turn-dispatch, gated on `options.steeringChannel`
+ * being present — the natural turn-scoped analog of "off a control_state BLOCKED trigger", since
+ * TaskGraph loading/swapping is itself a turn-scoped operation, not a mid-iteration one).
+ */
+export interface SchedulerSelectionResult {
+    record: GoalGraphRecord;
+    activeThreadId: string | null;
+    switched: boolean;
+}
+/**
+ * The Scheduler's one selection pass. If a thread is already genuinely `ACTIVE`
+ * (`getActiveThread` — defensively re-checks `status`, not just the pointer), it keeps focus:
+ * v1 is cooperative, not preemptive by default (Q6) — a still-workable ACTIVE thread is never
+ * bumped just because other READY threads exist. Only when there is *no* valid ACTIVE thread
+ * (null pointer, or the pointed-at thread's own status has moved on — PAUSED/BLOCKED/DONE/
+ * ABANDONED, e.g. after a NEW_GOAL/CANCEL_CURRENT steering event paused or abandoned it) does it
+ * pick the next eligible candidate, FIFO by `createdAt`. No eligible candidate leaves the pointer
+ * exactly as it was — never invents a switch out of thin air.
+ */
+export declare function selectActiveThread(record: GoalGraphRecord): SchedulerSelectionResult;
+/**
+ * IMMEDIATE steering's synchronous hook (see the header comment): forces `threadId` to become
+ * `ACTIVE` right now if — and only if — it's actually eligible (`READY`, not mid-drafting) per the
+ * exact same rules `selectActiveThread` itself enforces. An ineligible or unknown `threadId` (e.g.
+ * the just-minted thread is still `mode: 'drafting'`, per `mintConcurrentReadyThread` — real,
+ * common case: Tier-2 hasn't decomposed it into runnable tasks yet) falls back to the ordinary
+ * `selectActiveThread` pass rather than force-activating something not actually runnable —
+ * "same selection function, same exclusion rules either way" holds even for the forced path.
+ */
+export declare function forceActivateThread(record: GoalGraphRecord, threadId: string): SchedulerSelectionResult;
+/**
+ * Gives `threadId` focus for the turn that is about to run on it — the identity matcher's "this
+ * message continues that goal" outcome. Unlike `forceActivateThread` (which only ever activates a
+ * thread the Scheduler already considers eligible), this is the deliberate, user-driven switch:
+ * the message itself is the evidence, so a READY, PAUSED or still-drafting thread is promoted
+ * (a drafting thread — e.g. one a NEW_GOAL steering message minted — becomes `mode: 'active'`,
+ * because a real turn is now executing it) and whatever else was ACTIVE is paused with its
+ * evidence intact (INV-42). Still the Scheduler's single write path to the ACTIVE pointer (INV-39).
+ * A BLOCKED, DONE, ABANDONED or already-ACTIVE thread is left exactly as it is (`switched: false`):
+ * blocked work isn't silently unblocked by a mention, and finished work isn't reopened.
+ */
+export declare function focusThread(record: GoalGraphRecord, threadId: string): SchedulerSelectionResult;
+/**
+ * Starts a brand-new goal thread that takes focus immediately — the identity matcher's "this is a
+ * new goal" outcome (no existing thread matches, or it was ambiguous). The description is the
+ * message itself, kept to one short line. Any thread that was ACTIVE is paused and linked as a
+ * `concurrent` sibling (R3), never discarded (INV-42). `tasks` starts empty and is adopted from the
+ * harness's task graph once the turn runs (see syncThreadFromTaskGraph).
+ */
+export declare function startThread(record: GoalGraphRecord, description: string): SchedulerSelectionResult;
+/**
+ * INV-42 (Q3's resolution — "PAUSED preserves partial state/evidence — never silently discarded
+ * on preemption"): the per-thread analog of `plan-store.ts`'s `updatePlanFromRun`, mapping the
+ * harness's resulting task statuses back onto `threadId`'s own `tasks` list. Deliberately looked
+ * up **by id**, not via `getActiveThread` — the whole point is this still works for a thread the
+ * Scheduler has since moved to `PAUSED` (an in-flight tool call that was already running when a
+ * steering message preempted its thread runs to completion per Q3's "let it finish" default, and
+ * its result must still land on the now-PAUSED thread, not be silently dropped). A `threadId` not
+ * present in `record.threads` is a no-op — defensive, never throws on a stale id.
+ */
+export declare function syncThreadFromTaskGraph(record: GoalGraphRecord, threadId: string, taskGraphTasks: {
+    id: string;
+    status: GoalThread['tasks'][number]['status'];
+    description?: string;
+    depends_on?: string[];
+    risk_level?: 'LOW' | 'MEDIUM' | 'HIGH';
+}[]): GoalGraphRecord;