@buildaharness/aielia 0.3.0

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

@@ -0,0 +1,66 @@
+declare const _default: {
+  "name": "decision_making",
+  "version": "1.0.0",
+  "success_criteria": "A decision is made, documented with full rationale, and communicated to stakeholders.",
+  "tags": ["decision", "evaluation", "criteria"],
+  "tasks": [
+    {
+      "id": "define_criteria",
+      "title": "Define decision criteria",
+      "description": "List the criteria that will govern the decision. Assign relative weights. Confirm with decision owners.",
+      "depends_on": [],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "identify_options",
+      "title": "Identify options",
+      "description": "Generate a complete list of candidate options. Include at least one 'do nothing' option for baseline.",
+      "depends_on": ["define_criteria"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "evaluate_options",
+      "title": "Evaluate options",
+      "description": "Score each option against the weighted criteria. Document evidence for each score.",
+      "depends_on": ["identify_options"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["evaluation"]
+    },
+    {
+      "id": "stakeholder_check",
+      "title": "Stakeholder check",
+      "description": "Validate options against stakeholder constraints and political considerations not captured in criteria.",
+      "depends_on": ["identify_options"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["stakeholders"]
+    },
+    {
+      "id": "select",
+      "title": "Select",
+      "description": "Choose the winning option based on evaluation scores and stakeholder input. Record the final decision.",
+      "depends_on": ["evaluate_options", "stakeholder_check"],
+      "risk_level": "HIGH",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "document_rationale",
+      "title": "Document rationale",
+      "description": "Write a decision record: what was decided, why, what was rejected and why, and who approved.",
+      "depends_on": ["select"],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-06-22" }
+}
+;
+
+export default _default;

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

@@ -0,0 +1,75 @@
+declare const _default: {
+  "name": "problem_solving",
+  "version": "1.0.0",
+  "success_criteria": "The problem is resolved, the chosen approach has been validated, and the rationale is documented.",
+  "tags": ["generic", "analysis", "decision"],
+  "tasks": [
+    {
+      "id": "clarify_problem",
+      "title": "Clarify the problem",
+      "description": "Restate the problem in concrete terms, identify stakeholders, and confirm scope.",
+      "depends_on": [],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "root_cause_analysis",
+      "title": "Root cause analysis",
+      "description": "Identify underlying causes rather than surface symptoms. Use evidence from available sources.",
+      "depends_on": ["clarify_problem"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "generate_options",
+      "title": "Generate solution options",
+      "description": "Brainstorm at least three distinct approaches. Document trade-offs for each.",
+      "depends_on": ["root_cause_analysis"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["options"]
+    },
+    {
+      "id": "assess_constraints",
+      "title": "Assess constraints",
+      "description": "Identify time, resource, and stakeholder constraints that narrow the solution space.",
+      "depends_on": ["root_cause_analysis"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["constraints"]
+    },
+    {
+      "id": "select_approach",
+      "title": "Select approach",
+      "description": "Choose the best option given the constraints. Document the decision rationale.",
+      "depends_on": ["generate_options", "assess_constraints"],
+      "risk_level": "HIGH",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "implement",
+      "title": "Implement",
+      "description": "Execute the chosen approach. Track progress against the plan.",
+      "depends_on": ["select_approach"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "validate",
+      "title": "Validate outcome",
+      "description": "Confirm the problem is resolved. Measure against the original success criteria.",
+      "depends_on": ["implement"],
+      "risk_level": "HIGH",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-06-22" }
+}
+;
+
+export default _default;

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

@@ -0,0 +1,57 @@
+declare const _default: {
+  "name": "process_improvement",
+  "version": "1.0.0",
+  "success_criteria": "Identified gaps are addressed via a piloted improvement that shows measurable positive outcomes.",
+  "tags": ["process", "improvement", "operations"],
+  "tasks": [
+    {
+      "id": "map_current_state",
+      "title": "Map current state",
+      "description": "Document the existing process end-to-end: steps, owners, inputs, outputs, cycle time, and pain points.",
+      "depends_on": [],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "identify_gaps",
+      "title": "Identify gaps",
+      "description": "Analyse the current state map for inefficiencies, bottlenecks, errors, and unmet needs.",
+      "depends_on": ["map_current_state"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "design_improvements",
+      "title": "Design improvements",
+      "description": "Propose process changes that address the identified gaps. Design the future-state process map.",
+      "depends_on": ["identify_gaps"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "pilot",
+      "title": "Pilot",
+      "description": "Run the improved process in a controlled environment. Monitor for unintended side-effects.",
+      "depends_on": ["design_improvements"],
+      "risk_level": "HIGH",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "measure_outcomes",
+      "title": "Measure outcomes",
+      "description": "Collect metrics from the pilot. Compare against the baseline. Decide: adopt, adjust, or abandon.",
+      "depends_on": ["pilot"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-06-22" }
+}
+;
+
+export default _default;

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

@@ -0,0 +1,66 @@
+declare const _default: {
+  "name": "project_planning",
+  "version": "1.0.0",
+  "success_criteria": "The project scope is defined, resources are allocated, risks are assessed, and a schedule with a kickoff milestone is ready.",
+  "tags": ["project", "planning", "management"],
+  "tasks": [
+    {
+      "id": "scope_definition",
+      "title": "Define project scope",
+      "description": "Document project goals, deliverables, boundaries, and acceptance criteria. Align with stakeholders.",
+      "depends_on": [],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "work_breakdown",
+      "title": "Work breakdown structure",
+      "description": "Decompose deliverables into discrete tasks. Estimate effort and identify dependencies.",
+      "depends_on": ["scope_definition"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "resource_planning",
+      "title": "Resource planning",
+      "description": "Identify required team members, tools, and budget. Confirm availability and assign owners.",
+      "depends_on": ["work_breakdown"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["resources"]
+    },
+    {
+      "id": "risk_assessment",
+      "title": "Risk assessment",
+      "description": "Identify project risks, assess likelihood and impact, and define mitigation actions.",
+      "depends_on": ["work_breakdown"],
+      "risk_level": "HIGH",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["risks"]
+    },
+    {
+      "id": "schedule",
+      "title": "Build schedule",
+      "description": "Produce a timeline with milestones. Incorporate resource constraints and risk buffers.",
+      "depends_on": ["resource_planning", "risk_assessment"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "kickoff",
+      "title": "Kickoff",
+      "description": "Run the project kickoff. Distribute the plan, confirm roles, and establish communication cadence.",
+      "depends_on": ["schedule"],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-06-22" }
+}
+;
+
+export default _default;

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

@@ -0,0 +1,66 @@
+declare const _default: {
+  "name": "research_analysis",
+  "version": "1.0.0",
+  "success_criteria": "Research questions are answered with synthesised evidence from multiple sources, and a clear report is produced.",
+  "tags": ["research", "analysis", "evidence"],
+  "tasks": [
+    {
+      "id": "define_questions",
+      "title": "Define research questions",
+      "description": "State the primary and secondary research questions. Define scope and success criteria for the inquiry.",
+      "depends_on": [],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "gather_sources",
+      "title": "Gather sources",
+      "description": "Identify and collect relevant data sources, documents, and stakeholder inputs. Assess source quality.",
+      "depends_on": ["define_questions"],
+      "risk_level": "LOW",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "extract_insights",
+      "title": "Extract insights",
+      "description": "Read and analyse each source. Extract key findings, data points, and quotes that bear on the research questions.",
+      "depends_on": ["gather_sources"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "cross_reference",
+      "title": "Cross-reference findings",
+      "description": "Identify agreements, contradictions, and gaps across sources. Flag conflicting evidence for resolution.",
+      "depends_on": ["extract_insights"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 1,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "synthesise",
+      "title": "Synthesise",
+      "description": "Combine verified findings into a coherent narrative that directly answers the research questions.",
+      "depends_on": ["cross_reference"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "report",
+      "title": "Write report",
+      "description": "Produce a structured report: executive summary, findings, evidence, recommendations, and limitations.",
+      "depends_on": ["synthesise"],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-06-22" }
+}
+;
+
+export default _default;

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

@@ -0,0 +1,66 @@
+declare const _default: {
+  "name": "trip_planning",
+  "version": "1.0.0",
+  "success_criteria": "The destination is researched, transport and lodging are booked, an itinerary exists, and travel-document/packing logistics are confirmed ahead of departure.",
+  "tags": ["trip", "travel", "planning"],
+  "tasks": [
+    {
+      "id": "destination_research",
+      "title": "Research the destination",
+      "description": "Research weather, entry/visa requirements, must-see highlights, and local customs for the destination and travel dates.",
+      "depends_on": [],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "book_transport",
+      "title": "Book transport",
+      "description": "Book flights or other transport to and from the destination for the planned dates.",
+      "depends_on": ["destination_research"],
+      "risk_level": "HIGH",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["bookings"]
+    },
+    {
+      "id": "book_lodging",
+      "title": "Book lodging",
+      "description": "Book accommodations for each leg of the trip, matching the transport dates.",
+      "depends_on": ["destination_research"],
+      "risk_level": "HIGH",
+      "abstraction_level": 1,
+      "parallel_write_domains": ["bookings"]
+    },
+    {
+      "id": "itinerary_planning",
+      "title": "Plan the itinerary",
+      "description": "Draft a day-by-day itinerary balancing travel time, rest, and key activities, confirmed against the transport and lodging dates.",
+      "depends_on": ["book_transport", "book_lodging"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "logistics_prep",
+      "title": "Prepare travel logistics",
+      "description": "Confirm passport/visa validity, arrange travel insurance, and build a packing list based on the itinerary and destination.",
+      "depends_on": ["itinerary_planning"],
+      "risk_level": "MEDIUM",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    },
+    {
+      "id": "final_check",
+      "title": "Final pre-departure check",
+      "description": "Confirm all bookings, travel documents, and packing are ready ahead of departure.",
+      "depends_on": ["logistics_prep"],
+      "risk_level": "LOW",
+      "abstraction_level": 0,
+      "parallel_write_domains": []
+    }
+  ],
+  "metadata": { "author": "buildaharness", "created": "2026-07-10" }
+}
+;
+
+export default _default;

package/dist/plan-templates/index.d.ts

@@ -0,0 +1,33 @@
+export interface PlanTask {
+    id: string;
+    title: string;
+    description: string;
+    depends_on: string[];
+    risk_level: 'LOW' | 'MEDIUM' | 'HIGH';
+    abstraction_level: number;
+    parallel_write_domains: string[];
+}
+export interface PlanTemplate {
+    name: string;
+    version: string;
+    success_criteria: string;
+    tags: string[];
+    tasks: PlanTask[];
+    metadata: Record<string, unknown>;
+}
+export declare function loadTemplate(name: string): PlanTemplate;
+export declare function listTemplateNames(): string[];
+/**
+ * Heuristic: match description keywords to a template name. Always returns a
+ * template — falls back to 'problem_solving' on zero keyword hits, exactly like
+ * agents/planner/utils.py's pick_template_for_task. Used by buildPlanFromTemplate
+ * once a template has already been chosen some other way (e.g. matchTemplateIfConfident).
+ */
+export declare function pickTemplateForTask(description: string): string;
+/**
+ * Stricter variant for the planning gate (planning-classifier.ts): returns null on
+ * zero keyword hits instead of defaulting to problem_solving. The gate needs "no
+ * real match" to be distinguishable from "weakly matched problem_solving" — an
+ * always-a-fallback heuristic can't express that distinction.
+ */
+export declare function matchTemplateIfConfident(description: string): string | null;

package/dist/plan-verification.d.ts

@@ -0,0 +1,31 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { PlanTaskRecord } from './plan-store.js';
+/**
+ * P6 of plans/ask_question_and_plan_mode_plan.html — runs between drafting (P1/P3) and staging
+ * for approval (P2). Two independent checks, deliberately ordered cheapest-and-most-certain
+ * first: (1) dependency-graph validity (pure, synchronous, no LLM call — the same three checks
+ * `adapter/harness/task_graph.py`'s `validate_task_graph` runs Python-side: orphaned `depends_on`
+ * references and cycle detection via the identical iterative-DFS WHITE/GRAY/BLACK algorithm, plus
+ * a duplicate-task-id check this phase's Scope calls for that the Python original doesn't need
+ * because `TaskGraph` construction already dedupes by id), then (2) one bounded LLM call for the
+ * harder judgment — a lighter, narrower version of `reviewer.py`'s three-lens shape, specifically
+ * the adversarial lens's question. A graph error is a fails-fast condition (the plan must not
+ * reach `awaiting_approval` with an invalid structure); an LLM-lens failure is not — it just means
+ * the plan proceeds to approval without `reviewNotes` (Validation section, LLM-failure fallback).
+ */
+export declare function validatePlanTaskGraph(tasks: PlanTaskRecord[]): string[];
+export type PlanVerificationOutcome = {
+    kind: 'graph_invalid';
+    errors: string[];
+} | {
+    kind: 'verified';
+    reviewNotes: string[];
+    verifiedAt: string;
+};
+/**
+ * Deterministic checks first (fails fast on a structural problem — the caller must not stage a
+ * plan whose graph is invalid), then the bounded adversarial-completeness LLM call. Called from
+ * `PlanDraftingService.draftTurn` right before handing a `readyForApproval` draft to
+ * `PlanApprovalService.stageAndRespond`.
+ */
+export declare function verifyPlanDraft(llmClient: ILLMClient, tasks: PlanTaskRecord[], successCriteria: string, rationale: string, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<PlanVerificationOutcome>;

package/dist/reminder-tools.d.ts

@@ -0,0 +1,13 @@
+import { ToolDefinition, ReminderStore } from '@buildaharness/runtime';
+export declare const CREATE_REMINDER_TOOL: ToolDefinition;
+export declare const LIST_REMINDERS_TOOL: ToolDefinition;
+export declare const REMINDER_TOOLS: ToolDefinition[];
+/**
+ * `sourceUserMessage` is the current turn's raw user message — used only for the fact-shaped
+ * guard below, never stored. Checking it (not just the tool call's own `text` argument) matters
+ * because the model routinely rewords/normalizes text before calling a tool (e.g. "I'm allergic
+ * to peanuts, please remember that" → "User is allergic to peanuts" as the `text` argument),
+ * which would otherwise dodge a check against `text` alone even though the turn is clearly
+ * fact-shaped.
+ */
+export declare function executeReminderTool(store: ReminderStore, toolName: string, input: Record<string, unknown>, sourceUserMessage?: string): Promise<string>;

package/dist/response-service.d.ts

@@ -0,0 +1,73 @@
+import { EscalationHalt, HarnessCheckpoint, VerificationResult, LayerActivityEvent, HarnessRunResult } from '@buildaharness/harness';
+import { TokenUsage } from '@buildaharness/runtime';
+import { TurnIntentClassification } from './turn-intent-classifier.js';
+import { PlanRecord } from './plan-store.js';
+import { PlanService } from './plan-service.js';
+import { AssistantSession } from './assistant-session.js';
+import { MemoryService } from './memory-service.js';
+import { AssistantSource } from './assistant-source.js';
+import { BatchBudgetTrace } from './agent-loop.js';
+import { AssistantTurnResult } from './assistant-types.js';
+import { TraceEvent } from './trace-events.js';
+/**
+ * AssistantTurnResult assembly for every return path — the triviality fast path, the
+ * plan-pacing pause, the harness success path, and the EscalationHalt-caught path — split out of
+ * runTurn in Phase 4d of the architecture remediation plan. Each method persists whatever this
+ * path needs to persist (transcript, facts, plan) and returns the final result, so the sequencer
+ * (assistant.ts) never has to duplicate per-path assembly logic.
+ */
+export declare class ResponseService {
+    private readonly memoryService;
+    private readonly session;
+    private readonly planService;
+    private readonly onTrace;
+    constructor(memoryService: MemoryService, session: AssistantSession, planService: PlanService, onTrace: ((event: TraceEvent) => void) | undefined);
+    buildTrivialResult(params: {
+        sessionId: string;
+        transcriptKey: string;
+        userMessage: string;
+        draftReply: string;
+        classification: TurnIntentClassification;
+        sources: AssistantSource[] | undefined;
+        batchBudgetTrace: BatchBudgetTrace | undefined;
+        usageTotal: TokenUsage | undefined;
+        onUsage?: (usage: TokenUsage) => void;
+    }): Promise<AssistantTurnResult>;
+    buildPausedResult(params: {
+        sessionId: string;
+        transcriptKey: string;
+        userMessage: string;
+        draftReply: string;
+        classification: TurnIntentClassification;
+        activePlan: PlanRecord | null;
+        checkpoint: HarnessCheckpoint;
+        lastVerification: VerificationResult | null;
+        layerActivity: LayerActivityEvent[];
+        sources: AssistantSource[] | undefined;
+        batchBudgetTrace: BatchBudgetTrace | undefined;
+        usageTotal: TokenUsage | undefined;
+        onUsage?: (usage: TokenUsage) => void;
+    }): Promise<AssistantTurnResult>;
+    buildSuccessResult(params: {
+        sessionId: string;
+        transcriptKey: string;
+        userMessage: string;
+        draftReply: string;
+        classification: TurnIntentClassification;
+        activePlan: PlanRecord | null;
+        result: HarnessRunResult;
+        lastVerification: VerificationResult | null;
+        layerActivity: LayerActivityEvent[];
+        sources: AssistantSource[] | undefined;
+        batchBudgetTrace: BatchBudgetTrace | undefined;
+        usageTotal: TokenUsage | undefined;
+        onUsage?: (usage: TokenUsage) => void;
+    }): Promise<AssistantTurnResult>;
+    buildEscalatedResult(params: {
+        sessionId: string;
+        transcriptKey: string;
+        userMessage: string;
+        err: EscalationHalt;
+        classification: TurnIntentClassification;
+    }): Promise<AssistantTurnResult>;
+}

package/dist/review-checker.d.ts

@@ -0,0 +1,22 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { BeliefCandidate } from './contradiction-checker.js';
+/**
+ * One LLM call checking a proposed change against everything relevant at once (never one call
+ * per belief/prediction) — layered on top of review-proposed-change.ts's lexical `isNegation`
+ * check, which only catches an explicit phrase like "not X"/"removes X"/"no longer X". That check
+ * also requires the change description and the belief it's compared against to share a concrete
+ * subject before it fires (see looksLikeCodingFact's doc comment in contradiction-checker.ts) —
+ * which is why decomposition-classifier.ts and plan-builder.ts prompt task descriptions to lead
+ * with their subject. A
+ * paraphrased conflict ("we're dropping the login feature" vs. a belief that login is required)
+ * slips past that phrase list entirely. Skipped when the change description itself reads like a
+ * structured/technical (coding) action — see looksLikeCodingFact's doc comment for why that's
+ * exactly the domain the lexical check already handles reasonably well; this is worth spending a
+ * call on for a natural-language-shaped change instead. Falls back to "no conflict" on any parse
+ * failure or LLM error, matching this codebase's other LLM-backed classifiers — a missed conflict
+ * costs nothing worse than the lexical-only behavior this is layered on top of.
+ */
+export declare function checkSemanticReviewConflict(changeDescription: string, highConfidenceBeliefs: BeliefCandidate[], hypothesisPredictions: string[], llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<{
+    conflict: boolean;
+    reason?: string;
+}>;

package/dist/risk-classifier.d.ts

@@ -0,0 +1,7 @@
+export type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH';
+export interface RiskClassification {
+    riskLevel: RiskLevel;
+    requiresApproval: boolean;
+    reason: string;
+}
+export declare function classifyRisk(message: string): RiskClassification;

package/dist/scripted-llm-client.d.ts

@@ -0,0 +1,37 @@
+import { ILLMClient, LLMStructuredResponse } from '@buildaharness/runtime';
+/**
+ * A deterministic, network-free {@link ILLMClient} for tests and demos — the one publicly
+ * supported way to drive a real `PersonalAssistant` turn end to end without a proxy, an API key,
+ * or a live model. Built for plans/chat_ui_browser_e2e_plan.html phase B1 (the browser-e2e lane
+ * that unblocks the `ASSISTANT_ONE_LOOP` default-flip), and reusable by chat-ui's `demo-seed.ts`.
+ *
+ * It mirrors the shape of the internal `ScriptedToolLLMClient` that `assistant.test.ts` has used
+ * for a long time: every turn spends exactly one mandatory `classifyTurnIntent` call up front,
+ * which this client recognises (by a distinctive phrase from that classifier's system prompt) and
+ * answers on its own from a lightweight, deterministic default — so `responses` only has to
+ * script the *tool loop / one-loop proposer's* own calls, not that bookkeeping call.
+ *
+ * `responses` entries are consumed in order, one per non-classifier `callChatStructured` call:
+ *   - a plain `string` → `{ content: string }` (a final answer, no tool calls)
+ *   - an `LLMStructuredResponse` → use as-is (set `toolCalls` to simulate the model calling a tool)
+ *
+ * `callChat`/`callChatSync` (the no-tools reply path, and post-approval synthesis) stream
+ * `streamChunks` (default: `['']`).
+ */
+export interface ScriptedLLMClientScript {
+    /** Ordered structured responses for the tool loop / one-loop proposer. A bare string is shorthand for a final answer with no tool calls. */
+    responses?: Array<string | LLMStructuredResponse>;
+    /** Chunks streamed from `callChat`/`callChatSync`. Defaults to `['']`. */
+    streamChunks?: string[];
+    /**
+     * Per-user-message override of the auto-answered `classifyTurnIntent` JSON fields (e.g.
+     * `{ isTrivial: true }`, `{ riskLevel: 'HIGH' }`, `{ decomposedTasks: [...] }`). Return
+     * `undefined` to keep the derived default for that message.
+     */
+    classify?: (userMessage: string) => Record<string, unknown> | undefined;
+}
+/**
+ * Builds a scripted {@link ILLMClient}. See {@link ScriptedLLMClientScript}. The returned value
+ * is a plain `ILLMClient` — pass it straight to `PersonalAssistant.create({ llmClient })`.
+ */
+export declare function createScriptedLLMClient(script?: ScriptedLLMClientScript): ILLMClient;

package/dist/semantic-criterion-coverage.d.ts

@@ -0,0 +1,30 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { Belief } from '@buildaharness/harness';
+/**
+ * assistant.ts's single ad hoc/single-task turn always passes this exact sentence as its harness
+ * run's successCriteria — a meta-instruction ("respond helpfully"), not a factual claim a belief
+ * could ever state or paraphrase. Every other one of HarnessRuntime's semantic hooks has its own
+ * cheap, no-LLM-call skip for the domain it knows doesn't need escalation (looksLikeCodingFact for
+ * contradictionChecker/semanticChangeReviewer, empty symptoms/patterns for semanticFailureMatcher);
+ * this is that skip for criterion coverage. Without it, any ad hoc turn with at least one recorded
+ * belief would spend a real LLM call every single time, forever, on a criterion that structurally
+ * can never be "covered" by a belief in the first place — found by running the existing test suite
+ * against a freshly-built @buildaharness/harness dist (see this plan's Phase 5 corrections) rather
+ * than by design; a durable plan's own successCriteria (real, task-specific text like "the login
+ * tests pass" — see plan-store.ts's PlanRecord) is exactly the case this hook exists for and is
+ * NOT skipped.
+ */
+export declare const NON_CHECKABLE_DEFAULT_CRITERION = "Respond helpfully, accurately, and safely to the user request.";
+/**
+ * One LLM call per uncovered criterion, checking it against the whole belief set at once — layered
+ * on top of reviewerPass's implementerLens (packages/harness/src/nodes/reviewer-pass.ts), which
+ * otherwise only checks success-criterion coverage via a plain `.includes()` substring match.
+ * Called only for a criterion that substring check already found no coverage for (see
+ * SemanticCriterionCoverage's own doc comment) — a criterion the cheap check already covers never
+ * reaches this call. Falls back to "not covered" (the substring check's own verdict stands) on any
+ * parse failure or LLM error, matching this codebase's other LLM-backed classifiers
+ * (checkForContradictions, checkSemanticReviewConflict, checkSemanticFailureMatch) — a missed
+ * coverage costs nothing worse than the substring-only behavior this is layered on top of, since it
+ * only ever adds coverage, never removes it.
+ */
+export declare function checkSemanticCriterionCoverage(criterion: string, beliefs: Belief[], llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<boolean>;