@alex.botez/clarifying-ideas 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandru Botez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# Clarifying Ideas
+
+An agent skill that helps you turn vague ideas into structured requirements.
+
+[![CI](https://github.com/alexbot/clarifying-ideas/actions/workflows/ci.yml/badge.svg)](https://github.com/alexbot/clarifying-ideas/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@alex.botez/clarifying-ideas)](https://www.npmjs.com/package/@alex.botez/clarifying-ideas)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## The Problem
+
+Most people either vibe-code, start building and figure it out along the way, or paste a one-line prompt and hope what comes back is a spec. Both skip the step before planning: figuring out what success looks like, who cares, where the boundaries are, and which assumptions will bite you later.
+
+```
+             Most projects start here
+                        ↓
+        ┌──────┐    ┌────────┐    ┌───────┐    ┌──────┐    ┌────────┐
+  ?  →  │ Plan │ →  │ Design │ →  │ Build │ →  │ Test │ →  │ Launch │
+        └──────┘    └────────┘    └───────┘    └──────┘    └────────┘
+  ↑
+  Clarifying Ideas sits here.
+```
+
+That step has methods (qualitative research, goal modeling, structured interviews) but they depend on trained facilitators and workshops. Solo developers, founders, and small teams skip it entirely, and discover the gaps mid-build.
+
+## Quick Start
+
+```bash
+npx skills add alexbot/clarifying-ideas -a claude-code      # Claude Code
+npx skills add alexbot/clarifying-ideas -a cursor            # Cursor
+npx skills add alexbot/clarifying-ideas -a github-copilot    # GitHub Copilot
+```
+
+Then `/clarifying-ideas` in your agent. Any agent that supports [agentskills.io](https://agentskills.io) works. See the [full list](https://www.npmjs.com/package/skills#supported-agents).
+
+## What It Does
+
+Clarifying Ideas asks the right questions, 25–32 across seven phases, and you control every answer. It moves you from a vague idea to a scoped project definition.
+
+- Catches gaps you'd miss on your own: undefined success criteria, wrong assumptions, conflicting premises nobody stated
+- Every goal, stakeholder, scope decision, and assumption traces back to the conversation turn that produced it
+- AI flags ambiguity, never self-resolves. You decide everything
+
+## Example
+
+The vague idea:
+
+> *"Our local library branch is losing visitors and the city might close it. I want to help revive it."*
+
+What AI generates from that prompt, versus what emerges after 28 Clarifying Ideas questions:
+
+| | AI-generated | After Clarifying Ideas |
+|---|---|---|
+| **Purpose** | **Increase traffic by 40%** through events, outreach, and digital resources | **Determine whether the library is what the neighborhood actually needs** |
+| **Goals** | 8 goals with **invented metrics**: 2,500 monthly visitors, $15K fundraising, 30% card registration increase | 3 goals that **flag unknowns**: what patrons actually need, what the city's closure criteria are, who the target visitors should be |
+| **Scope** | **Execution**: launch 5 programs, recruit 15 volunteers, secure grants | **Research**: talk to families, interview city council, assess whether the library is even the right solution |
+| **Insight** | "The library is **a critical community asset**" (stated as fact) | "I never stopped to ask **whether the library is actually what the neighborhood needs**" |
+
+[AI-generated brief](docs/examples/library.brief.generated.md) · [Clarifying Ideas brief](docs/examples/library.brief.md) · [More examples](docs/examples/)
+
+## Output
+
+The interview produces two artifacts:
+
+- **Session file** (`.clarifying-ideas/session.yaml`). YAML with every goal, stakeholder, scope item, and assumption traced to its conversation turn. Designed as input for spec-driven development tools or any pipeline that needs structured intent.
+- **Project brief.** Run `/project-brief` on the session to generate a readable markdown summary for stakeholder pitches, project kickoffs, or business plans.
+
+The session file lives in your project directory. AI coding agents (Claude Code, Cursor, Aider, etc.) can read it directly — no conversion or extra setup needed. Point your agent at the file and it has the full structured context from the interview.
+
+## How It Works
+
+The interview is complex: 7 phases, state persistence, extraction cycles, deviation handling. The phases are opening, purpose, goals, stakeholders, scope, assumptions, and validation. Rather than relying on the model to follow a long prompt correctly, Clarifying Ideas splits the work. A compiled script handles all process decisions (what to ask, when to transition, how to store artifacts) while the model handles only semantic work (understanding what you said, extracting meaning, composing follow-ups). The model can't skip phases or lose track; the script drives.
+
+Interview techniques draw on Kvale & Patton (semi-structured interviewing), Miller & Rollnick (motivational interviewing), Reynolds & Gutman (means-end laddering), and KAOS (goal decomposition). See [docs/decisions/](docs/decisions/) for the full architecture story.
+
+## Security
+
+Clarifying Ideas runs locally. No telemetry, no analytics, no data sent anywhere. There are no postinstall scripts — `npm install` runs nothing. All writes go to `.clarifying-ideas/` inside your project directory; nothing touches shared caches, home directories, or system paths.
+
+## Development
+
+Requires **Node 22+**.
+
+```bash
+npm install
+npm run build          # TypeScript compilation
+npm run build:skill    # esbuild bundle → dist/skill/
+npx vitest run         # Run tests
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, and how to pick up work.
+
+## License
+
+[MIT](LICENSE)

package/dist/durable/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Durable workflow framework — public barrel.
+ *
+ * Memoized coroutine execution with suspend/resume. See workflow.ts for the
+ * full implementation; this file is the public surface for cross-layer and
+ * external consumers.
+ */
+export { Suspend, NonDeterminismError, DuplicateCallIdError, WorkflowContext, execute, } from "./workflow.js";
+export type { StateEntry, WorkflowStatus, WorkflowState, StatePersistence, InferRequest, InferStep, PromptRequest, PromptStep, Prompt, Resolver, Workflow, FidelityDetail, FidelityResult, ExecutionResult, } from "./workflow.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/durable/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/durable/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,OAAO,GACR,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,aAAa,EACb,UAAU,EACV,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,cAAc,EACd,eAAe,GAChB,MAAM,eAAe,CAAC"}

package/dist/durable/index.js

@@ -0,0 +1,9 @@
+/**
+ * Durable workflow framework — public barrel.
+ *
+ * Memoized coroutine execution with suspend/resume. See workflow.ts for the
+ * full implementation; this file is the public surface for cross-layer and
+ * external consumers.
+ */
+export { Suspend, NonDeterminismError, DuplicateCallIdError, WorkflowContext, execute, } from "./workflow.js";
+//# sourceMappingURL=index.js.map

package/dist/durable/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/durable/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,OAAO,GACR,MAAM,eAAe,CAAC"}

package/dist/durable/workflow.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Durable workflow framework — memoized coroutine execution with suspend/resume.
+ *
+ * Workflows call infer (LLM) and prompt (user) through a context object. All calls
+ * are logged to an ordered state array; on re-execution, recorded values replay
+ * and only new calls hit the resolver. Any call can suspend via Suspend throw,
+ * which persists the suspension point and propagates to the caller.
+ */
+/** Thrown by a resolver (or call fn) to signal that a call cannot be fulfilled now. */
+export declare class Suspend {
+    readonly id: string;
+    readonly value?: unknown | undefined;
+    constructor(id: string, value?: unknown | undefined);
+}
+/** Thrown when a replayed call id doesn't match the recorded sequence. */
+export declare class NonDeterminismError extends Error {
+    constructor(position: number, expected: string, got: string);
+}
+/** Thrown when the same call id is used more than once in a single execution. */
+export declare class DuplicateCallIdError extends Error {
+    constructor(id: string);
+}
+/** A single entry in the state log — either completed (has value) or suspended. */
+export type StateEntry = {
+    id: string;
+    value: unknown;
+} | {
+    id: string;
+    suspended: true;
+};
+/** Lifecycle status of a workflow execution. */
+export type WorkflowStatus = "running" | "suspended" | "completed" | "failed";
+/** Serializable snapshot of a workflow's progress — status plus ordered call log. */
+export interface WorkflowState {
+    status: WorkflowStatus;
+    entries: StateEntry[];
+}
+/** Storage adapter for persisting workflow state between executions. */
+export interface StatePersistence {
+    load(): WorkflowState | null;
+    save(state: WorkflowState): void;
+    /** Create initial empty state with "running" status. */
+    initialize(): void;
+    /** Transition workflow to a new status. */
+    setStatus(status: WorkflowStatus): void;
+}
+/** Payload for an infer call — semantic processing by the resolver (typically LLM). */
+export interface InferRequest {
+    message: string;
+    schema?: Record<string, unknown>;
+}
+/** Phantom brand — carries result type without runtime presence. */
+declare const INFER_STEP_RESULT: unique symbol;
+/** Pre-built infer request with embedded id and phantom return type. */
+export interface InferStep<T = unknown> extends InferRequest {
+    readonly id: string;
+    readonly [INFER_STEP_RESULT]?: T;
+}
+/** Payload for a prompt call — user-facing message with optional suggested answers. */
+export interface PromptRequest {
+    message: string;
+    suggestions?: string[];
+}
+/** Pre-built prompt request with embedded id — mirrors InferStep for prompt calls. */
+export interface PromptStep extends PromptRequest {
+    readonly id: string;
+}
+/** A prompt emitted by the framework — either an infer or prompt request tagged with its call id. */
+export type Prompt = {
+    id: string;
+    type: "infer";
+    request: InferRequest;
+} | {
+    id: string;
+    type: "prompt";
+    request: PromptRequest;
+};
+/** Callback that fulfills prompts — the single adapter interface for all non-compute calls. */
+export type Resolver = (prompt: Prompt) => Promise<unknown>;
+/** Per-extraction mismatch detail — which keys were expected but missing. */
+export interface FidelityDetail {
+    id: string;
+    expectedKeys: string[];
+    actualKeys: string[];
+    missingKeys: string[];
+    reason?: "non-object" | "missing-keys";
+}
+/** Accumulated fidelity result across all schema-bearing infer calls. */
+export interface FidelityResult {
+    checked: number;
+    mismatched: number;
+    details: FidelityDetail[];
+}
+/** Result of a workflow execution — extensible container for execution-level concerns. */
+export interface ExecutionResult {
+    fidelity: FidelityResult;
+}
+/**
+ * Execution context passed to workflow functions.
+ *
+ * Provides three call primitives (call, infer, prompt) that memoize results
+ * in an ordered state log and replay on re-execution.
+ */
+export declare class WorkflowContext {
+    private persistence;
+    private resolver;
+    private cursor;
+    private seen;
+    private state;
+    private fidelity;
+    private lastPrompt;
+    constructor(persistence: StatePersistence, resolver: Resolver);
+    /**
+     * Deterministic compute — runs fn, memoizes, replays from log on re-execution.
+     * If fn throws Suspend, a suspended entry is written before propagating.
+     */
+    call<T>(id: string, fn: () => T | Promise<T>): Promise<T>;
+    /** ID of the most recent prompt() call, or null before any prompt. */
+    get lastPromptId(): string | null;
+    get currentSource(): {
+        promptId: string;
+    } | undefined;
+    /** Accumulated fidelity result for all schema-bearing infer calls in this execution. */
+    fidelityResult(): FidelityResult;
+    /** Non-deterministic semantic processing — delegates to resolver, memoized. */
+    infer<T>(step: InferStep<T>): Promise<T>;
+    infer<T>(id: string, request: InferRequest): Promise<T>;
+    /** Check result keys against schema keys; accumulate fidelity counters. */
+    private checkFidelity;
+    /** Human interaction — delegates to resolver, memoized. May cause suspension. */
+    prompt(step: PromptStep): Promise<string>;
+    prompt(id: string, request: PromptRequest): Promise<string>;
+}
+/** A workflow function — receives a context, performs calls, returns when complete. */
+export type Workflow = (ctx: WorkflowContext) => Promise<void>;
+/**
+ * Run (or resume) a workflow. Replays memoized calls, then continues execution.
+ * Returns execution result on completion. Throws Suspend on suspension (already
+ * persisted by the context). Throws other errors on failure.
+ *
+ * If status is already `completed`, returns `{ fidelity: EMPTY_FIDELITY }`
+ * without re-executing. Callers that need to distinguish fresh completion
+ * from a no-op should check `persistence.status()` before calling.
+ *
+ * Suspension is a throw, not a return. A `Suspend` instance carries the id of
+ * the suspending call and the pending `Prompt` payload as its `value` field.
+ * Callers must handle both paths:
+ *
+ *     try {
+ *       const result = await execute(persistence, workflow, resolver);
+ *       // Workflow completed — `result.fidelity` has the extraction stats.
+ *     } catch (e) {
+ *       if (e instanceof Suspend) {
+ *         // Workflow paused on a prompt — `e.value` is the `Prompt` payload,
+ *         // `e.id` is the suspended call's id. Persist-and-return so the
+ *         // next invocation resumes from this point.
+ *       } else {
+ *         // Real failure — persistence has already been flagged "failed".
+ *         throw e;
+ *       }
+ *     }
+ */
+export declare function execute(persistence: StatePersistence, workflow: Workflow, resolver: Resolver): Promise<ExecutionResult>;
+export {};
+//# sourceMappingURL=workflow.d.ts.map

package/dist/durable/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/durable/workflow.ts"],"names":[],"mappings":"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"}

package/dist/durable/workflow.js

@@ -0,0 +1,224 @@
+/**
+ * Durable workflow framework — memoized coroutine execution with suspend/resume.
+ *
+ * Workflows call infer (LLM) and prompt (user) through a context object. All calls
+ * are logged to an ordered state array; on re-execution, recorded values replay
+ * and only new calls hit the resolver. Any call can suspend via Suspend throw,
+ * which persists the suspension point and propagates to the caller.
+ */
+// Errors
+/** Thrown by a resolver (or call fn) to signal that a call cannot be fulfilled now. */
+export class Suspend {
+    id;
+    value;
+    constructor(id, value) {
+        this.id = id;
+        this.value = value;
+    }
+}
+/** Thrown when a replayed call id doesn't match the recorded sequence. */
+export class NonDeterminismError extends Error {
+    constructor(position, expected, got) {
+        super(`Non-determinism at position ${position}: expected "${expected}", got "${got}"`);
+    }
+}
+/** Thrown when the same call id is used more than once in a single execution. */
+export class DuplicateCallIdError extends Error {
+    constructor(id) {
+        super(`Duplicate call id: "${id}"`);
+    }
+}
+// Context
+/**
+ * Execution context passed to workflow functions.
+ *
+ * Provides three call primitives (call, infer, prompt) that memoize results
+ * in an ordered state log and replay on re-execution.
+ */
+export class WorkflowContext {
+    persistence;
+    resolver;
+    cursor = 0;
+    seen = new Set();
+    state;
+    fidelity = { checked: 0, mismatched: 0, details: [] };
+    lastPrompt = null;
+    constructor(persistence, resolver) {
+        this.persistence = persistence;
+        this.resolver = resolver;
+        const state = persistence.load();
+        if (!state)
+            throw new Error("WorkflowContext requires initialized persistence; call persistence.initialize() first");
+        this.state = state;
+    }
+    /**
+     * Deterministic compute — runs fn, memoizes, replays from log on re-execution.
+     * If fn throws Suspend, a suspended entry is written before propagating.
+     */
+    async call(id, fn) {
+        // Replay path: entry exists in state log
+        if (this.cursor < this.state.entries.length) {
+            const entry = this.state.entries[this.cursor];
+            if (entry.id !== id)
+                throw new NonDeterminismError(this.cursor, entry.id, id);
+            this.seen.add(entry.id);
+            this.cursor++;
+            // Suspended entry — try to fulfill
+            if ("suspended" in entry) {
+                try {
+                    const result = await fn();
+                    this.state.entries[this.cursor - 1] = { id, value: result };
+                    this.persistence.save(this.state);
+                    return result;
+                }
+                catch (e) {
+                    if (e instanceof Suspend) {
+                        this.state.status = "suspended";
+                        this.persistence.save(this.state);
+                        throw e;
+                    }
+                    throw e;
+                }
+            }
+            // Completed entry — return cached value
+            return entry.value;
+        }
+        // First-hit path: new call not yet in state log
+        if (this.seen.has(id))
+            throw new DuplicateCallIdError(id);
+        this.seen.add(id);
+        try {
+            const result = await fn();
+            this.state.entries.push({ id, value: result });
+            this.cursor++;
+            this.persistence.save(this.state);
+            return result;
+        }
+        catch (e) {
+            if (e instanceof Suspend) {
+                this.state.entries.push({ id, suspended: true });
+                this.state.status = "suspended";
+                this.cursor++;
+                this.persistence.save(this.state);
+                throw e;
+            }
+            throw e;
+        }
+    }
+    /** ID of the most recent prompt() call, or null before any prompt. */
+    get lastPromptId() { return this.lastPrompt; }
+    get currentSource() {
+        return this.lastPrompt ? { promptId: this.lastPrompt } : undefined;
+    }
+    /** Accumulated fidelity result for all schema-bearing infer calls in this execution. */
+    fidelityResult() {
+        return this.fidelity;
+    }
+    async infer(first, second) {
+        const id = typeof first === "string" ? first : first.id;
+        const request = typeof first === "string"
+            ? second
+            : { message: first.message, schema: first.schema };
+        const prompt = { id, type: "infer", request };
+        const result = await this.call(id, () => this.resolver(prompt));
+        if (request.schema && (result == null || typeof result !== "object")) {
+            const expectedKeys = Object.keys(request.schema);
+            this.fidelity.checked++;
+            this.fidelity.mismatched++;
+            this.fidelity.details.push({
+                id, expectedKeys, actualKeys: [], missingKeys: expectedKeys, reason: "non-object",
+            });
+            return {};
+        }
+        if (request.schema && result != null && typeof result === "object") {
+            this.checkFidelity(id, request.schema, result);
+        }
+        return result;
+    }
+    /** Check result keys against schema keys; accumulate fidelity counters. */
+    checkFidelity(id, schema, result) {
+        const expectedKeys = Object.keys(schema);
+        const actualKeys = Object.keys(result);
+        const missingKeys = expectedKeys.filter((k) => !(k in result));
+        this.fidelity.checked++;
+        if (missingKeys.length > 0) {
+            this.fidelity.mismatched++;
+            this.fidelity.details.push({ id, expectedKeys, actualKeys, missingKeys, reason: "missing-keys" });
+        }
+    }
+    async prompt(first, second) {
+        const id = typeof first === "string" ? first : first.id;
+        const request = typeof first === "string"
+            ? second
+            : { message: first.message, ...(first.suggestions ? { suggestions: first.suggestions } : {}) };
+        request.message = normalizeMessage(request.message);
+        this.lastPrompt = id;
+        const p = { id, type: "prompt", request };
+        const result = await this.call(id, () => this.resolver(p));
+        if (typeof result !== "string")
+            return "";
+        return result;
+    }
+}
+function normalizeMessage(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trim())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+// Execute
+const EMPTY_FIDELITY = { checked: 0, mismatched: 0, details: [] };
+/**
+ * Run (or resume) a workflow. Replays memoized calls, then continues execution.
+ * Returns execution result on completion. Throws Suspend on suspension (already
+ * persisted by the context). Throws other errors on failure.
+ *
+ * If status is already `completed`, returns `{ fidelity: EMPTY_FIDELITY }`
+ * without re-executing. Callers that need to distinguish fresh completion
+ * from a no-op should check `persistence.status()` before calling.
+ *
+ * Suspension is a throw, not a return. A `Suspend` instance carries the id of
+ * the suspending call and the pending `Prompt` payload as its `value` field.
+ * Callers must handle both paths:
+ *
+ *     try {
+ *       const result = await execute(persistence, workflow, resolver);
+ *       // Workflow completed — `result.fidelity` has the extraction stats.
+ *     } catch (e) {
+ *       if (e instanceof Suspend) {
+ *         // Workflow paused on a prompt — `e.value` is the `Prompt` payload,
+ *         // `e.id` is the suspended call's id. Persist-and-return so the
+ *         // next invocation resumes from this point.
+ *       } else {
+ *         // Real failure — persistence has already been flagged "failed".
+ *         throw e;
+ *       }
+ *     }
+ */
+export async function execute(persistence, workflow, resolver) {
+    const state = persistence.load();
+    if (!state) {
+        persistence.initialize();
+    }
+    else if (state.status === "completed") {
+        return { fidelity: EMPTY_FIDELITY };
+    }
+    else if (state.status !== "running") {
+        persistence.setStatus("running");
+    }
+    const ctx = new WorkflowContext(persistence, resolver);
+    try {
+        await workflow(ctx);
+        persistence.setStatus("completed");
+        return { fidelity: ctx.fidelityResult() };
+    }
+    catch (e) {
+        if (e instanceof Suspend)
+            throw e;
+        persistence.setStatus("failed");
+        throw e;
+    }
+}
+//# sourceMappingURL=workflow.js.map

package/dist/durable/workflow.js.map

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

package/dist/interview/classification.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Review classification — LLM call that classifies the respondent's reaction
+ * to a presented item list (confirmed / removed / new items). Schema shape is
+ * phase-specific and passed by the caller.
+ *
+ * The base confirmation schema (`ConfirmClassifySchema` with `targetId`) and
+ * `ctx.confirm` live in `phases/shared.ts` because the classification takes
+ * the RE `Phase` and `Artifacts` types.
+ */
+import { z } from "zod";
+declare module "../durable/workflow.js" {
+    interface WorkflowContext {
+        review<S extends z.ZodObject<any>>(id: string, response: string, itemRef: string, artifactsContext: string, schema: S, ri?: number): Promise<z.infer<S>>;
+    }
+}
+//# sourceMappingURL=classification.d.ts.map

package/dist/interview/classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.d.ts","sourceRoot":"","sources":["../../src/interview/classification.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,eAAe;QACvB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;KAC1J;CACF"}

package/dist/interview/classification.js

@@ -0,0 +1,25 @@
+/**
+ * Review classification — LLM call that classifies the respondent's reaction
+ * to a presented item list (confirmed / removed / new items). Schema shape is
+ * phase-specific and passed by the caller.
+ *
+ * The base confirmation schema (`ConfirmClassifySchema` with `targetId`) and
+ * `ctx.confirm` live in `phases/shared.ts` because the classification takes
+ * the RE `Phase` and `Artifacts` types.
+ */
+import { WorkflowContext } from "../durable/index.js";
+/** Classify the respondent's reaction to a presented item list (confirmed/removed/new items). */
+WorkflowContext.prototype.review = async function (id, response, itemRef, artifactsContext, schema, ri) {
+    const fullId = ri !== undefined ? `${id}-r${ri}` : id;
+    return this.extract({
+        id: fullId,
+        response,
+        artifactsContext,
+        schema,
+        guidance: `The respondent reacted to the presented list.\n${itemRef ? `Item IDs: ${itemRef}` : "No items existed yet."}`,
+    });
+};
+if (typeof WorkflowContext.prototype.review !== "function") {
+    throw new Error("interview/classification.ts self-check failed: WorkflowContext.prototype.review is not a function.");
+}
+//# sourceMappingURL=classification.js.map

package/dist/interview/classification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.js","sourceRoot":"","sources":["../../src/interview/classification.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAQtD,iGAAiG;AACjG,eAAe,CAAC,SAAS,CAAC,MAAM,GAAG,KAAK,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAG;IACrG,MAAM,MAAM,GAAG,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,OAAO,IAAI,CAAC,OAAO,CAAC;QAClB,EAAE,EAAE,MAAM;QACV,QAAQ;QACR,gBAAgB;QAChB,MAAM;QACN,QAAQ,EAAE,kDAAkD,OAAO,CAAC,CAAC,CAAC,aAAa,OAAO,EAAE,CAAC,CAAC,CAAC,uBAAuB,EAAE;KACzH,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,IAAI,OAAQ,eAAe,CAAC,SAAgD,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;IACnG,MAAM,IAAI,KAAK,CAAC,oGAAoG,CAAC,CAAC;AACxH,CAAC"}

package/dist/interview/composition.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Question composition — LLM call that produces an interview question with
+ * optional suggested answers, preceded by the composition quality preamble.
+ */
+import type { ComposeParams } from "./describe.js";
+import type { QuestionContext } from "./prompt.js";
+declare module "../durable/workflow.js" {
+    interface WorkflowContext {
+        compose(step: ComposeParams): Promise<QuestionContext>;
+    }
+}
+//# sourceMappingURL=composition.d.ts.map

package/dist/interview/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/interview/composition.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,eAAe;QACvB,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;KACxD;CACF"}

package/dist/interview/composition.js

@@ -0,0 +1,19 @@
+/**
+ * Question composition — LLM call that produces an interview question with
+ * optional suggested answers, preceded by the composition quality preamble.
+ */
+import { WorkflowContext } from "../durable/index.js";
+import { compositionPreamble } from "./preambles.js";
+/** Compose a question with suggestions; falls back to step.fallback if agent returns empty. */
+WorkflowContext.prototype.compose = async function (step) {
+    const compPre = compositionPreamble();
+    const enrichedStep = compPre
+        ? { ...step, message: compPre + "\n\n" + step.message }
+        : step;
+    const { question, suggestions } = await this.infer(enrichedStep);
+    return question ? { question, suggestions } : { question: step.fallback };
+};
+if (typeof WorkflowContext.prototype.compose !== "function") {
+    throw new Error("interview/composition.ts self-check failed: WorkflowContext.prototype.compose is not a function.");
+}
+//# sourceMappingURL=composition.js.map

package/dist/interview/composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.js","sourceRoot":"","sources":["../../src/interview/composition.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AASrD,+FAA+F;AAC/F,eAAe,CAAC,SAAS,CAAC,OAAO,GAAG,KAAK,WAAW,IAAmB;IACrE,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IACtC,MAAM,YAAY,GAAG,OAAO;QAC1B,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE;QACvD,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACjE,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;AAC5E,CAAC,CAAC;AAEF,IAAI,OAAQ,eAAe,CAAC,SAAgD,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;IACpG,MAAM,IAAI,KAAK,CAAC,kGAAkG,CAAC,CAAC;AACtH,CAAC"}