@buildaharness/aielia 0.3.0

package/dist/plan-drafting-service.d.ts

@@ -0,0 +1,87 @@
+import { ILLMClient, TokenUsage, MemoryAdapter } from '@buildaharness/runtime';
+import { AskResponse } from '@buildaharness/harness';
+import { AssistantSession } from './assistant-session.js';
+import { PlanService } from './plan-service.js';
+import { PlanApprovalService } from './plan-approval-service.js';
+import { AssistantTurnResult } from './assistant-types.js';
+import { TraceEvent } from './trace-events.js';
+import { AgentLoop } from './agent-loop.js';
+/**
+ * `{ fallThrough: true }` only ever comes from a *fresh, auto-triggered* entry (`seed` set —
+ * assistant.ts's P3 auto-trigger, never PersonalAssistant.enterPlanMode's manual/test entry point)
+ * whose very first drafting call failed (malformed/insufficient LLM output, or a thrown error —
+ * draftPlanRevision's own try/catch already normalizes both to `null`) — this phase's Validation
+ * requires falling back to *not entering plan mode at all* rather than staging a broken draft or
+ * getting the user stuck in a "couldn't update the draft" loop they never asked to enter (same
+ * "null means fall through" convention `buildPlanFromTemplate` already used). Mirrors
+ * `PlanApprovalOutcome`'s exact shape/discipline. A manual `enterPlanMode` entry with no `seed`
+ * keeps today's pre-P3 behavior on a failed first draft: stay in drafting, ask the user to
+ * rephrase — that path is an explicit, already-active choice to draft, not a guess the system
+ * made on the user's behalf.
+ */
+export type PlanDraftOutcome = {
+    fallThrough: true;
+} | AssistantTurnResult;
+/**
+ * P3 of plans/ask_question_and_plan_mode_plan.html — how `assistant.ts`'s auto-trigger tells
+ * `draftTurn` what to seed a *fresh* draft with (ignored on every later revision of an
+ * already-drafting plan). `templateName` set means a template matched — the draft starts from
+ * that template's own skeleton (today's personalization behavior, reused, not discarded — see
+ * `buildPlanFromTemplate`'s doc comment — except the drafting call itself, not a separate
+ * personalization call, does the adapting, so it's free to add/remove/split/reorder relative to
+ * the skeleton rather than preserving it 1:1). `grounded: true` (only meaningful when
+ * `templateName` is null) means ground the from-scratch draft in real repo state via a bounded
+ * read_file/list_directory walk before drafting.
+ */
+export interface PlanDraftSeed {
+    templateName: string | null;
+    grounded: boolean;
+}
+/**
+ * Owns plan mode's P1 exclusive drafting loop: while `AssistantSession.getPlanModeState(sessionId)`
+ * is `active`, `assistant.ts`'s runTurn routes every message here instead of TurnInterpreter's
+ * normal classify/tool-loop pipeline (INV-30 — no tool other than this call itself executes for
+ * that session while drafting is active). Two designed exits: an explicit cancel/abort phrase
+ * (handled entirely here), and P2's approval response once a draft is staged for
+ * `awaiting_approval` (handed off to `PlanApprovalService.stageAndRespond` below the moment a
+ * revision's `readyForApproval` is true — resolved via `turn(message, { planApprovalId,
+ * planDecision })`, checked earlier in `assistant.ts`'s runTurn than this drafting path at all).
+ *
+ * The drafting call itself (plan-drafting.ts's draftPlanRevision) has no tool access of its own —
+ * P3 grounds a from-scratch draft by running a separate, bounded read_file/list_directory
+ * investigation walk first (see the `seed?.grounded` branch in `draftTurn` below) and feeding its
+ * findings in as extra context, rather than giving the drafting call itself live tool-calling.
+ * P3 also wired the automatic judgment-based trigger this class was previously waiting on:
+ * `assistant.ts`'s runTurn now calls `session.enterPlanMode` and routes into `draftTurn` (with a
+ * `PlanDraftSeed`) the moment `classifyTurnIntent` reports `matchedPlanTemplate !== null ||
+ * needsMultiStepPlan` and no plan is already active — `PersonalAssistant.enterPlanMode` remains
+ * available as a direct entry point too (tests, a future `/plan` command), unchanged.
+ */
+export declare class PlanDraftingService {
+    private readonly planService;
+    private readonly session;
+    private readonly llmClient;
+    private readonly model;
+    private readonly planApproval;
+    private readonly onTrace;
+    private readonly agentLoop?;
+    private readonly memory?;
+    constructor(planService: PlanService, session: AssistantSession, llmClient: ILLMClient, model: () => string | undefined, planApproval: PlanApprovalService, onTrace: ((event: TraceEvent) => void) | undefined, agentLoop?: Pick<AgentLoop, "runSupervisorInvestigation"> | undefined, memory?: MemoryAdapter | undefined);
+    private planAskPendingKey;
+    /** Peeked by `assistant.ts`'s runTurn before it decides whether a `pendingClarificationId` belongs to this nested-ask side channel (P8) or AskClarificationService's harness-resume path (Q2) — the two staging stores are otherwise independent, so an opaque ID has no other way to say which one it came from. */
+    isPendingAsk(id: string): Promise<boolean>;
+    /**
+     * Resolves a nested plan-drafting ask by ID (P8) — the drafting counterpart to
+     * AskClarificationService.resolvePendingClarification, but folds the answer into the *next
+     * drafting revision call* instead of resuming a paused harness run (there is none mid-draft).
+     * Fail-closed (Protected Invariants) exactly like Q2: no answer, or one that doesn't validate
+     * against exactly the staged questions (INV-28), leaves the turn in `needs_clarification`
+     * rather than silently proceeding or discarding the batch.
+     */
+    resolvePendingAsk(sessionId: string, transcriptKey: string, pendingAskId: string, response: AskResponse | undefined, onUsage: (usage: TokenUsage) => void): Promise<AssistantTurnResult>;
+    draftTurn(sessionId: string, transcriptKey: string, userMessage: string, onUsage: (usage: TokenUsage) => void, seed?: PlanDraftSeed): Promise<PlanDraftOutcome>;
+    private stillAwaitingApproval;
+    /** Stages a single nested question (P8) and returns the `needs_clarification` result — mirrors AskClarificationService.stageAndRespond's "append the user's message, return no reply yet" shape, but into `plan-ask-pending:` instead of `ask-pending:`, and resolved by `resolvePendingAsk` above instead of a harness resume. */
+    private stageNestedAsk;
+    private cancelDrafting;
+}

package/dist/plan-drafting.d.ts

@@ -0,0 +1,58 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { AskQuestion } from '@buildaharness/harness';
+import { DecomposedTaskSpec } from './decomposition-classifier.js';
+import { PlanTaskRecord } from './plan-store.js';
+/**
+ * P1 of plans/ask_question_and_plan_mode_plan.html — the "plan-drafting revision call" P1's
+ * routing (assistant.ts's runTurn, PlanDraftingService) sends every message to while
+ * `planMode.active`. Deliberately narrower than P3's eventual version: no tools at all (P3 adds
+ * read_file/list_directory grounding for a from-scratch draft — see Section & non-goals),
+ * only revises the running draft from conversation text. Kept in its own module, same reasoning
+ * plan-builder.ts documents for buildPlanFromTemplate: a single-purpose LLM call, unit-testable
+ * without the rest of the drafting plumbing.
+ */
+export interface PlanDraftTurn {
+    /** A short, human-readable summary of the current draft, shown back to the user as the turn's reply. */
+    reply: string;
+    tasks: DecomposedTaskSpec[];
+    successCriteria: string;
+    rationale: string;
+    /**
+     * P2 of plans/ask_question_and_plan_mode_plan.html — true only once the model judges the user
+     * has clearly signaled they're satisfied with the current draft and want to proceed, at which
+     * point PlanDraftingService hands off to PlanApprovalService instead of returning another plain
+     * drafting reply. Defaults false on any malformed/missing value (see parsing below) — a
+     * misparsed response must never accidentally fast-track a plan into the approval gate.
+     */
+    readyForApproval: boolean;
+    /**
+     * P8 of plans/ask_question_and_plan_mode_plan.html — set only when this revision hit a genuine
+     * ambiguity worth pausing on instead of guessing (an ambiguous scope boundary, or a
+     * MEDIUM/HIGH-risk branch point with more than one viable approach) — e.g. "which of these two
+     * frameworks should the plan target?" A drafting call that sets this always also leaves
+     * `readyForApproval` false; `PlanDraftingService.draftTurn` stages it as a nested
+     * `needs_clarification` exchange (reusing Q0's `AskQuestion` shape and Q2/Q5/Q6's existing
+     * rendering) instead of treating `reply`/`tasks` as an ordinary revision, and the user's answer
+     * folds into the *next* drafting call as its `userMessage` rather than resuming a harness run
+     * (there is no harness run mid-draft to resume — see plan-drafting-service.ts's doc comment).
+     * Absent on every ordinary revision, same "absent when unused" convention the rest of this
+     * module follows.
+     */
+    question?: AskQuestion;
+}
+/**
+ * Spends one real LLM call revising the draft given `userMessage` — same "malformed/incomplete
+ * JSON is the expected failure mode, not the edge case" fallback buildPlanFromTemplate uses: any
+ * parse failure, or a response with zero usable tasks, returns null (caller keeps the draft
+ * unchanged and reports a generic "couldn't update the draft" reply rather than staging garbage).
+ */
+export declare function draftPlanRevision(llmClient: ILLMClient, userMessage: string, currentTasks: PlanTaskRecord[], currentSuccessCriteria: string, currentRationale: string, model?: string, onUsage?: (usage: TokenUsage) => void, 
+/**
+ * P3 of plans/ask_question_and_plan_mode_plan.html — grounding text for a from-scratch (no
+ * template match) draft, gathered from a bounded read_file/list_directory investigation walk
+ * (see AgentLoop.runSupervisorInvestigation, reused rather than building a new search engine —
+ * Scope & non-goals) so a code-shaped request's draft can reference real repo state instead of
+ * guessing. Absent for every other call (a template-seeded draft, or any revision after the
+ * first) — same "absent when unused" convention the rest of this module follows.
+ */
+groundingContext?: string): Promise<PlanDraftTurn | null>;

package/dist/plan-mode-flag.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure logic backing PersonalAssistant's ASSISTANT_PLAN_MODE handling — split out so it's
+ * unit-testable in isolation, mirroring one-loop-flag.ts/ask-mode-flag.ts's exact shape
+ * (module-level default, an injectable resolver so tests never touch real process.env).
+ *
+ * P11 of plans/ask_question_and_plan_mode_plan.html — the rollout flag gating P1-P8's whole
+ * plan-mode behavior change (exclusive drafting, mandatory approval, the generalized trigger,
+ * auto-advance, the markdown/delegate/trust-mode extensions) behind one switch. 'legacy' (the
+ * default, for the whole rollout window, per `DEFAULT_PLAN_MODE`): P3's judgment-based
+ * auto-trigger (assistant.ts's `runTurn`, the one production call site that ever calls
+ * `PersonalAssistant.enterPlanMode`) never fires, so `planMode.active` never becomes true for
+ * real user traffic and the entire P1-P8/P10 apparatus downstream of it stays dormant by
+ * construction — same "inert until its one entry point is reached" shape P1 itself already
+ * documents for the pre-P3 window, and the same discipline the Trajectory Supervisor's flag
+ * uses (a single call-site gate rather than scattering flag checks through every downstream
+ * consumer). Explicit/manual entry (`enterPlanMode` called directly by a test, or a future
+ * `/plan enter`-style CLI verb) is deliberately left ungated by this flag, since it has no
+ * production caller today independent of P3 (see `enterPlanMode`'s own doc comment) — there is
+ * nothing for 'legacy' to preserve byte-identically there. 'gated' lets P3's auto-trigger run.
+ */
+export type PlanRolloutMode = 'gated' | 'legacy';
+export declare const DEFAULT_PLAN_MODE: PlanRolloutMode;
+/**
+ * Value-level resolver, shared by every surface: `resolvePlanMode` (CLI, reads
+ * `process.env.ASSISTANT_PLAN_MODE`) and chat-ui's `envOverridesFromImportMetaEnv` (browser
+ * build, reads Vite's `import.meta.env.VITE_ASSISTANT_PLAN_MODE`). An unset or empty value
+ * falls back to the default silently; an unrecognized non-empty value falls back with a
+ * startup warning naming `varName` — same typo-tolerance-with-a-warning convention
+ * normalizeOneLoopMode/normalizeAskMode use, since a silently-misread flag here is
+ * safety-relevant (it decides whether real turns can auto-enter a durable, approval-gated
+ * planning loop at all).
+ */
+export declare function normalizePlanMode(raw: string | undefined, varName?: string): PlanRolloutMode;
+export declare function resolvePlanMode(env: NodeJS.ProcessEnv): PlanRolloutMode;

package/dist/plan-service.d.ts

@@ -0,0 +1,61 @@
+import { MemoryAdapter } from '@buildaharness/runtime';
+import { TaskStatus } from '@buildaharness/harness';
+import { Plan } from './plan-builder.js';
+import { nextPendingTask, PlanRecord, PlanPosition, TaskCancelMatch, PlanFsPersistence } from './plan-store.js';
+/**
+ * Thin constructor-scoped facade over `memory` for durable-plan bookkeeping — plan-store.ts (and
+ * plan-builder.ts/plan-templates/, untouched by this split) already hold the real logic, so this
+ * module exists only so TurnInterpreter, HarnessBridge (mid-run `onCheckpoint`), and
+ * ResponseService (post-run planStatus assembly) share one collaborator instead of each importing
+ * plan-store.ts's free functions directly and threading `memory` themselves.
+ *
+ * `fsPersistence` (plan mode's P5) is the same `{backend, workspaceRoot}` pair
+ * AssistantSession.undoWorkspace() resolves for write_file/run_shell_command — `undefined` on a
+ * surface with no real filesystem (e.g. a browser tab), in which case every method below behaves
+ * exactly as it did before P5, Dexie-only.
+ */
+export declare class PlanService {
+    private readonly memory;
+    private readonly fsPersistence?;
+    constructor(memory: MemoryAdapter, fsPersistence?: PlanFsPersistence | undefined);
+    loadActivePlan(sessionId: string): Promise<PlanRecord | null>;
+    /** Unlike loadActivePlan, returns the stored record regardless of `mode` — used by plan mode's P1 drafting loop, which needs to resume a `mode: 'drafting'` record loadActivePlan would never return. */
+    loadPlanRecord(sessionId: string): Promise<PlanRecord | null>;
+    createDraftPlanRecord(templateName: string | null): PlanRecord;
+    matchTaskCancelAttempt(message: string, plan: PlanRecord): TaskCancelMatch | null;
+    cancelPlanTask(sessionId: string, plan: PlanRecord, taskId: string): Promise<PlanRecord>;
+    editPlanTask(sessionId: string, plan: PlanRecord, taskId: string, newDescription: string): Promise<PlanRecord>;
+    abandonPlan(sessionId: string, plan: PlanRecord): Promise<void>;
+    stagePlanForApproval(sessionId: string, plan: PlanRecord): Promise<PlanRecord>;
+    activatePlanRecord(sessionId: string, plan: PlanRecord): Promise<PlanRecord>;
+    savePlan(sessionId: string, plan: PlanRecord): Promise<void>;
+    createPlanRecord(plan: Plan): PlanRecord;
+    updatePlanFromRun(plan: PlanRecord, taskGraphTasks: {
+        id: string;
+        status: TaskStatus;
+    }[]): PlanRecord;
+    planCompletionPct(plan: PlanRecord): number;
+    computePlanPosition(plan: PlanRecord, taskGraphTasks: {
+        id: string;
+        status: TaskStatus;
+    }[]): PlanPosition | null;
+    nextPendingTask(plan: PlanRecord): ReturnType<typeof nextPendingTask>;
+    /** Persists `plan`'s current task statuses and returns the AssistantTurnResult.planStatus shape both the paused and success branches of ResponseService build identically. */
+    saveAndSummarize(sessionId: string, plan: PlanRecord, taskGraphTasks: {
+        id: string;
+        status: TaskStatus;
+    }[]): Promise<{
+        plan: PlanRecord;
+        completionPct: number;
+        planStatus: {
+            templateName: string | null;
+            successCriteria: string;
+            completionPct: number;
+            tasks: {
+                id: string;
+                description: string;
+                status: string;
+            }[];
+        };
+    }>;
+}

package/dist/plan-sketch-service.d.ts

@@ -0,0 +1,24 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { AssistantTurnResult } from './assistant-types.js';
+import { TraceEvent } from './trace-events.js';
+import { AgentLoop } from './agent-loop.js';
+/**
+ * P9 of plans/ask_question_and_plan_mode_plan.html — the lightweight plan-sketch delegate: one
+ * bounded LLM call (grounded, best-effort, via the same read_file/list_directory investigation
+ * walk P3's from-scratch drafting reuses — AgentLoop.runSupervisorInvestigation, not a new search
+ * engine) that returns a plain proposed task list in the chat reply itself. Deliberately NOT
+ * PlanDraftingService: it never touches PlanService/PlanRecord, never calls
+ * AssistantSession.enterPlanMode, and stages nothing for PlanApprovalService to see (INV-35) —
+ * advice for one turn, not a commitment to execute. Kept in its own module/class, same
+ * single-purpose-collaborator discipline every other plan-mode service in this package follows,
+ * so a caller that only wants the free-form sketch never pulls in the stateful drafting/approval
+ * machinery at all.
+ */
+export declare class PlanSketchService {
+    private readonly llmClient;
+    private readonly model;
+    private readonly onTrace;
+    private readonly agentLoop?;
+    constructor(llmClient: ILLMClient, model: () => string | undefined, onTrace: ((event: TraceEvent) => void) | undefined, agentLoop?: Pick<AgentLoop, "runSupervisorInvestigation"> | undefined);
+    sketch(request: string, onUsage: (usage: TokenUsage) => void): Promise<AssistantTurnResult>;
+}

package/dist/plan-sketch.d.ts

@@ -0,0 +1,20 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * P9 of plans/ask_question_and_plan_mode_plan.html — the lightweight plan-sketch delegate's one
+ * bounded LLM call. Deliberately the cheapest possible shape: a single plain-text reply the
+ * caller shows directly in the chat, not a structured task list staged anywhere — there is no
+ * PlanRecord, no PlanTaskRecord, nothing for P2's approval gate to see (INV-35). Distinct from
+ * plan-drafting.ts's draftPlanRevision, which is the first call in an iterative, stateful,
+ * eventually-approved drafting loop; this is one-shot advice, thrown away the moment the reply
+ * is shown — there is no "revise the sketch" follow-up call, no running draft to revise.
+ */
+export interface PlanSketchResult {
+    reply: string;
+}
+/**
+ * Spends one real LLM call sketching a plan for `request` — same "malformed/incomplete output is
+ * the expected failure mode, not the edge case" fallback plan-drafting.ts's draftPlanRevision
+ * uses: any thrown error, or an empty reply, returns null so the caller can show a generic
+ * "couldn't sketch that" message instead of an empty bubble.
+ */
+export declare function sketchPlan(llmClient: ILLMClient, request: string, groundingContext: string | undefined, model: string | undefined, onUsage: ((usage: TokenUsage) => void) | undefined): Promise<PlanSketchResult | null>;

package/dist/plan-store.d.ts

@@ -0,0 +1,232 @@
+import { FsBackend, MemoryAdapter } from '@buildaharness/runtime';
+import { TaskStatus } from '@buildaharness/harness';
+import { Plan } from './plan-builder.js';
+export interface PlanTaskRecord {
+    id: string;
+    description: string;
+    depends_on: string[];
+    status: TaskStatus;
+    /**
+     * Per-task risk, attached at plan-creation time (see plan-builder.ts's buildPlanFromTemplate)
+     * instead of re-derived from the description text on every resume. Optional only for backward
+     * compatibility with a plan persisted before this field existed — assistant.ts's
+     * toHarnessTasks falls back to the lexical planTaskRiskLevel/classifyRisk for those.
+     */
+    riskLevel?: 'LOW' | 'MEDIUM' | 'HIGH';
+    /**
+     * True once the user explicitly cancelled this specific task (see matchTaskCancelAttempt/
+     * cancelPlanTask) — distinct from `status`, which gets set to 'COMPLETE' alongside this so the
+     * harness's task-graph selection and dependent-unblocking treat it as resolved the same way a
+     * genuinely finished task would be (TaskStatus, from @buildaharness/harness, has no CANCELLED
+     * value of its own — extending that union is a cross-package change out of scope here).
+     * formatPlanProgress/planCompletionPct read this flag to show/count it accurately instead of
+     * claiming the user's own work actually got done.
+     */
+    cancelled?: boolean;
+}
+/**
+ * Superset of the old 3-value `status`: 'drafting' and 'awaiting_approval' are new (plan mode's
+ * P1/P2 — not wired to any producer yet, this phase is schema-only), 'active'/'done'/'abandoned'
+ * are the pre-existing values, unchanged in meaning.
+ */
+export type PlanMode = 'drafting' | 'awaiting_approval' | 'active' | 'done' | 'abandoned';
+export interface PlanRecord {
+    /** null for a fully custom-drafted plan (P3) that isn't seeded from one of the named templates. */
+    templateName: string | null;
+    successCriteria: string;
+    /** Why this approach, not just the success criteria — see Plan.rationale. */
+    rationale: string;
+    tasks: PlanTaskRecord[];
+    mode: PlanMode;
+    /** Populated by plan mode's P6 self-verification pass. */
+    reviewNotes?: string[];
+    verifiedAt?: string;
+    /** Whether the harness should auto-advance through this plan's tasks without a per-step pacing pause (plan mode's P4). */
+    executingOnPlan: boolean;
+    /**
+     * Plan mode's P10 "trust this approved plan" opt-in — absent/false (the default, "absent when
+     * unused" per this codebase's convention for additive fields) means every write/shell/email
+     * action this plan's execution proposes stays individually gated exactly as before this phase.
+     * `true` only once the user chose `'approve_trusted'` at the P2 approval screen (never the
+     * default choice there — see PlanApprovalService) — while true, an action proposed during
+     * execution of whichever task is this plan's currently RUNNING one is auto-applied instead of
+     * staged (INV-36; see assistant.ts's buildToolLoopPauseResult). Per-plan, not global or
+     * per-session: a fresh plan, or this same plan reloaded after `abandonPlan`, starts back at
+     * false.
+     */
+    trustApprovedSteps?: boolean;
+    /**
+     * Set only while `mode === 'awaiting_approval'` (plan mode's P2) — correlates a
+     * `turn(message, { planApprovalId, planDecision })` resolution to exactly this staged snapshot,
+     * same "resolved by ID, never re-derived" discipline pendingActionId/pendingClarificationId
+     * already follow. Cleared (undefined) once the plan is activated or the draft is abandoned.
+     */
+    planApprovalId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Pre-P0 persisted shape: `status` instead of `mode`, no `rationale`/`executingOnPlan`. */
+interface LegacyPlanRecordShape {
+    templateName: string;
+    successCriteria: string;
+    tasks: PlanTaskRecord[];
+    status: 'active' | 'done' | 'abandoned';
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Maps a persisted record — old 3-value `status` shape or the current 5-value `mode` shape — to
+ * the current PlanRecord shape, same "default pre-existing records without demoting a real value"
+ * convention fact-extraction.ts's migrateFact already uses elsewhere in this package. A migrated
+ * `active` plan gets `executingOnPlan: true` so an in-flight plan from before this change keeps
+ * progressing rather than silently stalling.
+ */
+export declare function migratePlanRecord(record: PlanRecord | LegacyPlanRecordShape): PlanRecord;
+/**
+ * Plan mode's P5 file-backed persistence: when a real filesystem is available (CLI/desktop —
+ * the same `{backend, workspaceRoot}` pair AssistantSession.undoWorkspace() already resolves for
+ * write_file/run_shell_command), every plan write is mirrored to
+ * `<workspaceRoot>/.buildaharness/plans/<sessionId>.plan.json` (plus a generated `.plan.md`
+ * view), and every load prefers that file over the Dexie/IndexedDB State-tier record so a
+ * hand-edit to the JSON between turns is picked up. On a surface with no filesystem (a browser
+ * tab), this is `undefined` throughout and Dexie alone remains the source of truth, unchanged
+ * from before P5.
+ */
+export interface PlanFsPersistence {
+    backend: FsBackend;
+    workspaceRoot: string;
+}
+/**
+ * Reads `sessionId`'s stored plan record regardless of `mode` — unlike `loadActivePlan`, which
+ * filters to `mode === 'active'` only. Plan mode's P1 drafting path needs to resume a
+ * `mode: 'drafting'` record across turns (and P2 needs `awaiting_approval` the same way), neither
+ * of which `loadActivePlan` would ever return.
+ *
+ * When `fsPersistence` is configured and its plan JSON file exists, that file wins over the
+ * Dexie/State-tier record (P5 — the file is the editable-and-reloadable artifact, so a hand-edit
+ * between turns takes effect on the very next load) and is written back into `memory` to
+ * reconcile the two (INV-33: after any interrupted dual write, the next load's result is
+ * self-consistent and Dexie catches back up to it, rather than the two staying silently split).
+ */
+export declare function loadPlanRecord(memory: MemoryAdapter, sessionId: string, fsPersistence?: PlanFsPersistence): Promise<PlanRecord | null>;
+/** Returns null when no plan exists for this session, or the stored plan is already done/abandoned — a finished plan never auto-resumes. */
+export declare function loadActivePlan(memory: MemoryAdapter, sessionId: string, fsPersistence?: PlanFsPersistence): Promise<PlanRecord | null>;
+/**
+ * Builds an immediately-`active` PlanRecord with no drafting/approval step at all. Before P3 of
+ * plans/ask_question_and_plan_mode_plan.html, TurnInterpreter.resolveTasks called this the instant
+ * classifyTurnIntent matched a template; P3 retired that call site — a template match (or the
+ * newer general needsMultiStepPlan judgment) now always routes through plan mode's exclusive
+ * drafting+approval loop instead (see assistant.ts's auto-trigger and
+ * PlanDraftingService.draftTurn's template-seeding). This function itself is unchanged and still
+ * used directly by tests/callers that want to seed an already-active plan without going through
+ * drafting. The ONLY other place `mode: 'active'` is ever set is `activatePlanRecord` below,
+ * reached solely via a drafted plan's explicit approve/approve-with-edits (INV-31) — this function
+ * remains the one intentional exception to "exactly one place", now purely a low-level primitive
+ * rather than something classification wires up automatically.
+ */
+export declare function createPlanRecord(plan: Plan): PlanRecord;
+/**
+ * The funnel every plan mutation in this module writes through. When `fsPersistence` is
+ * configured, the fs file is written first and Dexie second (P5, INV-33): if the process dies
+ * between the two, the fs file — which `loadPlanRecord` always prefers when present — already
+ * reflects either the old state (rename never happened) or the new one (rename completed),
+ * never a half-written file, so the next load resolves to one consistent version of both instead
+ * of a silently split pair.
+ */
+export declare function savePlan(memory: MemoryAdapter, sessionId: string, plan: PlanRecord, fsPersistence?: PlanFsPersistence): Promise<void>;
+/**
+ * A fresh, empty `mode: 'drafting'` record — the seed for plan mode's P1 drafting loop, started
+ * either from nothing (a from-scratch draft, P3) or already carrying a `templateName` seed.
+ * Unlike `createPlanRecord`, `executingOnPlan` starts false (P4's auto-advance only ever applies
+ * once P2 approval flips the record to `active`) and `mode` starts `'drafting'`, not `'active'`.
+ */
+export declare function createDraftPlanRecord(templateName: string | null): PlanRecord;
+export declare function abandonPlan(memory: MemoryAdapter, sessionId: string, plan: PlanRecord, fsPersistence?: PlanFsPersistence): Promise<void>;
+/**
+ * Stages a drafted plan for plan mode's P2 mandatory whole-plan approval gate: `mode` moves to
+ * `'awaiting_approval'` and a fresh `planApprovalId` is minted so the eventual
+ * `turn(message, { planApprovalId, planDecision })` resolves exactly this snapshot, never a
+ * second, re-derived one (see PlanRecord.planApprovalId's doc comment).
+ */
+export declare function stagePlanForApproval(memory: MemoryAdapter, sessionId: string, plan: PlanRecord, fsPersistence?: PlanFsPersistence): Promise<PlanRecord>;
+/**
+ * The sole place a *drafted* plan reaches `mode: 'active'` (INV-31) — called only from
+ * PlanApprovalService's approve/approve-with-edits branch, once any edits have already landed on
+ * `plan`. `createPlanRecord` above sets `mode: 'active'` too, but that's the pre-existing,
+ * unrelated template-instant-match path — not a second way for a *drafted* plan to skip approval.
+ * `planApprovalId` is cleared since the staged snapshot it correlated to no longer exists once
+ * activated.
+ */
+export declare function activatePlanRecord(memory: MemoryAdapter, sessionId: string, plan: PlanRecord, fsPersistence?: PlanFsPersistence): Promise<PlanRecord>;
+export interface TaskCancelMatch {
+    taskId: string;
+    taskDescription: string;
+}
+/**
+ * Detects a request to cancel/skip ONE task within an active plan — distinct from
+ * classifyTurnIntent's isAbandonRequest judgment, which is about ending the WHOLE plan (see
+ * conv59/conv70's h9 finding: "cancel the daily-budget task" isn't asking to abandon a trip-planning
+ * plan entirely, just to drop one of its steps, and there was no feature to route that to at
+ * all). Matches a cancel-shaped verb (cancel/skip/drop/remove), an explicit reference to the plan
+ * or one of its tasks/steps (TASK_REFERENCE_MARKER), together with a distinctive word (4+ letters,
+ * not a common stopword) shared with one of the plan's own not-yet-complete task
+ * descriptions/ids — deliberately conservative: a bare "cancel" with no recognizable task
+ * reference (e.g. "cancel my gym membership", unrelated to anything in this plan, or "cancel my
+ * travel insurance policy with my current provider", a genuine external request that merely
+ * happens to share a word with a task description) returns null and falls through to the ordinary
+ * message-level risk gate, same as today. Returns the first matching task in plan order, or null.
+ */
+export declare function matchTaskCancelAttempt(message: string, plan: PlanRecord): TaskCancelMatch | null;
+/**
+ * Cancels one task within an active plan — internal bookkeeping only (see PlanTaskRecord.cancelled
+ * for why status becomes 'COMPLETE' alongside the cancelled flag). Unlike abandonPlan, the plan
+ * itself stays 'active' so the remaining tasks continue normally.
+ */
+export declare function cancelPlanTask(memory: MemoryAdapter, sessionId: string, plan: PlanRecord, taskId: string, fsPersistence?: PlanFsPersistence): Promise<PlanRecord>;
+/**
+ * Changes one task's description without marking it complete — a lighter sibling of
+ * cancelPlanTask, for plan mode's P2 approve-with-edits path (a user can want a task reworded
+ * without dropping it entirely, which cancelPlanTask's "mark COMPLETE + cancelled" would do).
+ */
+export declare function editPlanTask(memory: MemoryAdapter, sessionId: string, plan: PlanRecord, taskId: string, newDescription: string, fsPersistence?: PlanFsPersistence): Promise<PlanRecord>;
+/**
+ * Maps the harness's resulting task statuses back onto the plan's own task list —
+ * mirrors what adapter/harness/plan_store.py's task_graph_to_plan does for the
+ * Python planner, just keyed to a chat session instead of a snapshot file. Marks
+ * the plan 'done' once every task is COMPLETE, so loadActivePlan stops resuming it.
+ * Also flips `executingOnPlan` back to false in that same allComplete branch (plan
+ * mode's P4, INV-32) — one of exactly two places that happens, the other being
+ * `abandonPlan`'s explicit user-abort path; every other event (a task failing, a
+ * needs_approval/needs_clarification interrupt, a harness error) leaves it untouched.
+ */
+export declare function updatePlanFromRun(plan: PlanRecord, taskGraphTasks: {
+    id: string;
+    status: TaskStatus;
+}[]): PlanRecord;
+/** Cancelled tasks are excluded from both sides of the ratio — they're neither remaining work nor
+ * something the user actually did, so counting them as "complete" would overstate real progress.
+ * A plan with no tasks at all is 0% (unchanged); a plan whose remaining tasks were all cancelled
+ * is 100% (nothing left to do) — two different situations, not the same "empty" case. */
+export declare function planCompletionPct(plan: PlanRecord): number;
+/**
+ * Live, mid-run position within a durable plan — see the harness layer activation plan's
+ * Phase 3.2. `stepIndex` is 1-based: the task currently RUNNING, or (once nothing is running)
+ * the last COMPLETE task, or the first task before anything has started.
+ */
+export interface PlanPosition {
+    templateName: string | null;
+    stepIndex: number;
+    stepCount: number;
+    currentTaskDescription: string;
+    completionPct: number;
+}
+/** Computes live plan position from a live (possibly mid-run) task-status list — `plan.tasks`' own order is authoritative; `taskGraphTasks` only supplies current status per id. */
+export declare function computePlanPosition(plan: PlanRecord, taskGraphTasks: {
+    id: string;
+    status: TaskStatus;
+}[]): PlanPosition | null;
+/** The next not-yet-COMPLETE task in plan order — used to phrase a pause/resume prompt ("Ready to continue with: <description>?"). Returns null once every task is COMPLETE. */
+export declare function nextPendingTask(plan: PlanRecord): PlanTaskRecord | null;
+/** Human-readable plan status — mirrors agents/planner/utils.py's format_plan_progress, for callers (the CLI) that want text instead of the structured planStatus field. */
+export declare function formatPlanProgress(plan: PlanRecord): string;
+export {};

package/dist/plan-templates/data/content_creation.json.d.ts

@@ -0,0 +1,75 @@
+declare const _default: {
+  "name": "content_creation",
+  "version": "1.0.0",
+  "success_criteria": "A polished, peer-reviewed piece of content is finalised and ready for publication or delivery.",
+  "tags": ["content", "writing", "communication"],
+  "tasks": [
+    {
+      "id": "brief",
+      "title": "Define brief",
+      "description": "Clarify the content goal, target audience, format, tone, length, and success metrics.",
+      "depends_on": [],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "outline",
+      "title": "Create outline",
+      "description": "Structure the content: define sections, key messages per section, and the logical flow.",
+      "depends_on": ["brief"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "draft",
+      "title": "Write draft",
+      "description": "Produce the first full draft following the outline. Focus on completeness over perfection.",
+      "depends_on": ["outline"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["draft"]
+    },
+    {
+      "id": "gather_references",
+      "title": "Gather references",
+      "description": "Collect supporting sources, data, quotes, and visuals that will strengthen the content.",
+      "depends_on": ["outline"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["references"]
+    },
+    {
+      "id": "peer_review",
+      "title": "Peer review",
+      "description": "Have at least one reviewer assess the draft for accuracy, clarity, tone, and completeness.",
+      "depends_on": ["draft", "gather_references"],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "revise",
+      "title": "Revise",
+      "description": "Incorporate review feedback. Address all critical comments before finalisation.",
+      "depends_on": ["peer_review"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "finalise",
+      "title": "Finalise",
+      "description": "Apply final formatting, proofread, and approve for publication or delivery.",
+      "depends_on": ["revise"],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-06-22" }
+}
+;
+
+export default _default;