@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/core/plan-decomposition.js

@@ -0,0 +1,417 @@
+/**
+ * Agent-driven goal decomposition for the planner.
+ *
+ * This module is the model-decomposition counterpart to the deterministic
+ * heuristic path in `plan-proposal.ts`. Given a goal, it drives a bounded,
+ * READ-ONLY planning agent (through the injected `DecompositionRunner` seam —
+ * this module never imports the agent machinery, so it stays in `core` and is
+ * fully unit-testable with a stubbed runner), parses and STRICTLY validates
+ * the agent's structured output, and produces a `PlanProposal` tagged with
+ * honest provenance.
+ *
+ * Failure honesty is the whole point: a spawn error, a timeout/cancellation,
+ * or output that is still malformed after ONE repair attempt all fall back to
+ * the existing heuristic `singleItemProposal` path, tagged
+ * `decomposedBy: 'heuristic'` with a `fallbackReason`. The heuristic path is
+ * reused verbatim — `singleItemProposal`/`assemblePlanProposal` are never
+ * modified — so their existing byte-for-byte test expectations are preserved;
+ * provenance is layered on afterward.
+ *
+ * The module NEVER performs surgery on agent output to force it to validate:
+ * a proposal is accepted only when `assemblePlanProposal` reports ZERO issues
+ * (no dangling dependency, no dependency cycle, no unresolved phase). Anything
+ * short of that is one repair attempt and then an honest fallback — never a
+ * silent edit that drops or rewrites the agent's work items.
+ */
+import { AdaptivePlanner } from './adaptive-planner.js';
+import { assemblePlanProposal, singleItemProposal, } from './plan-proposal.js';
+/** Pull the first balanced JSON object out of arbitrary agent text (fenced or not). */
+function extractJsonObject(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const haystack = fenced?.[1] ?? text;
+    const start = haystack.indexOf('{');
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < haystack.length; i++) {
+        const ch = haystack[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === '\\') {
+                escaped = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return haystack.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Parse + strictly validate a planning agent's output text into a
+ * `RawDecomposition` the assembler can consume. Never throws; every problem is
+ * accumulated into `errors` so a single repair prompt can address them all at
+ * once. Structural rejects: unparseable JSON, empty/absent items array, empty
+ * item title/brief, non-finite ordinal, empty phase title.
+ */
+export function parseDecomposition(text) {
+    const errors = [];
+    const json = extractJsonObject(text ?? '');
+    if (!json) {
+        return { ok: false, errors: ['Output did not contain a JSON object.'] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        return { ok: false, errors: [`Output was not valid JSON: ${err.message}`] };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, errors: ['Top-level value must be a JSON object.'] };
+    }
+    const obj = parsed;
+    const rawItems = obj.items;
+    if (!Array.isArray(rawItems) || rawItems.length === 0) {
+        return { ok: false, errors: ['"items" must be a non-empty array.'] };
+    }
+    // Validate phases (optional).
+    const rawPhases = Array.isArray(obj.phases) ? obj.phases : [];
+    rawPhases.forEach((p, i) => {
+        if (typeof p !== 'object' || p === null || !isNonEmptyString(p.title)) {
+            errors.push(`phases[${i}] must have a non-empty "title".`);
+        }
+    });
+    // Validate items.
+    const items = [];
+    rawItems.forEach((raw, i) => {
+        if (typeof raw !== 'object' || raw === null) {
+            errors.push(`items[${i}] must be an object.`);
+            return;
+        }
+        const item = raw;
+        if (!isNonEmptyString(item.title))
+            errors.push(`items[${i}].title must be a non-empty string.`);
+        if (!isNonEmptyString(item.brief))
+            errors.push(`items[${i}].brief must be a non-empty string.`);
+        if (typeof item.ordinal !== 'number' || !Number.isFinite(item.ordinal)) {
+            errors.push(`items[${i}].ordinal must be a finite number.`);
+        }
+        if (item.phase !== undefined && !isNonEmptyString(item.phase)) {
+            errors.push(`items[${i}].phase, when present, must be a non-empty string.`);
+        }
+        if (isNonEmptyString(item.title) && isNonEmptyString(item.brief) && typeof item.ordinal === 'number' && Number.isFinite(item.ordinal)) {
+            items.push({
+                title: item.title,
+                brief: item.brief,
+                ordinal: item.ordinal,
+                ...(isNonEmptyString(item.phase) ? { phase: item.phase } : {}),
+                ...(Array.isArray(item.dependsOn) ? { dependsOn: item.dependsOn.filter((d) => typeof d === 'string' || typeof d === 'number') } : {}),
+                ...(isNonEmptyString(item.suggestedArchetype) ? { suggestedArchetype: item.suggestedArchetype } : {}),
+                ...(Array.isArray(item.likelyFiles) ? { likelyFiles: item.likelyFiles.filter(isNonEmptyString) } : {}),
+                ...(Array.isArray(item.verification) ? { verification: item.verification.filter(isNonEmptyString) } : {}),
+                ...(typeof item.canRunConcurrently === 'boolean' ? { canRunConcurrently: item.canRunConcurrently } : {}),
+                ...(typeof item.needsReview === 'boolean' ? { needsReview: item.needsReview } : {}),
+            });
+        }
+    });
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const notes = [];
+    if (Array.isArray(obj.notes))
+        notes.push(...obj.notes.filter(isNonEmptyString));
+    if (Array.isArray(obj.risks))
+        notes.push(...obj.risks.filter(isNonEmptyString));
+    const output = {
+        items,
+        ...(rawPhases.length > 0 ? { phases: rawPhases } : {}),
+        ...(Array.isArray(obj.dependencies) ? { dependencies: obj.dependencies } : {}),
+    };
+    return { ok: true, raw: toRawDecomposition(output), ...(notes.length > 0 ? { notes } : {}), errors: [] };
+}
+const DEFAULT_PHASE_TITLE = 'Execute';
+/**
+ * Map a validated `DecompositionAgentOutput` into the `RawDecomposition` shape
+ * `assemblePlanProposal` consumes. Items are ordered by `ordinal` (stable on
+ * ties). Every referenced phase is materialized so the assembler never has to
+ * synthesize an "Unphased" bucket — an unresolved phase from here would be a
+ * real bug, not agent sloppiness. Ordinal-based dependency references are
+ * resolved to titles so the assembler's title resolver handles them uniformly.
+ */
+export function toRawDecomposition(output) {
+    const ordered = [...output.items].sort((a, b) => a.ordinal - b.ordinal);
+    const ordinalToTitle = new Map();
+    for (const item of ordered) {
+        if (!ordinalToTitle.has(item.ordinal))
+            ordinalToTitle.set(item.ordinal, item.title);
+    }
+    const resolveRef = (ref) => {
+        if (typeof ref === 'number')
+            return ordinalToTitle.get(ref) ?? String(ref);
+        const asNum = Number(ref);
+        if (ref.trim() !== '' && Number.isFinite(asNum) && ordinalToTitle.has(asNum))
+            return ordinalToTitle.get(asNum);
+        return ref;
+    };
+    // Phase set: explicit phases first, then any item phase titles not covered,
+    // then the default shared phase if any item lacks one.
+    const phaseTitles = [];
+    const seenPhase = new Set();
+    const addPhase = (title) => {
+        const key = title.toLowerCase().trim();
+        if (!seenPhase.has(key)) {
+            seenPhase.add(key);
+            phaseTitles.push(title);
+        }
+    };
+    const explicit = new Map();
+    for (const p of output.phases ?? []) {
+        explicit.set(p.title.toLowerCase().trim(), p);
+        addPhase(p.title);
+    }
+    let needsDefault = false;
+    for (const item of ordered) {
+        if (item.phase)
+            addPhase(item.phase);
+        else
+            needsDefault = true;
+    }
+    if (needsDefault)
+        addPhase(DEFAULT_PHASE_TITLE);
+    const phases = phaseTitles.map((title) => {
+        const meta = explicit.get(title.toLowerCase().trim());
+        return meta?.description ? { title, description: meta.description } : { title };
+    });
+    // Accumulate dependencies: inline dependsOn plus explicit edges.
+    const depsByTitle = new Map();
+    const addDep = (from, to) => {
+        const key = from.toLowerCase().trim();
+        if (!depsByTitle.has(key))
+            depsByTitle.set(key, new Set());
+        depsByTitle.get(key).add(to);
+    };
+    for (const item of ordered) {
+        for (const dep of item.dependsOn ?? [])
+            addDep(item.title, resolveRef(dep));
+    }
+    for (const edge of output.dependencies ?? [])
+        addDep(resolveRef(edge.from), resolveRef(edge.to));
+    const workItems = ordered.map((item) => {
+        const deps = depsByTitle.get(item.title.toLowerCase().trim());
+        return {
+            title: item.title,
+            brief: item.brief,
+            phase: item.phase ?? DEFAULT_PHASE_TITLE,
+            ...(deps && deps.size > 0 ? { dependsOn: [...deps] } : {}),
+            ...(item.suggestedArchetype ? { suggestedArchetype: item.suggestedArchetype } : {}),
+            ...(item.likelyFiles ? { likelyFiles: item.likelyFiles } : {}),
+            ...(item.verification ? { verification: item.verification } : {}),
+            ...(item.canRunConcurrently !== undefined ? { canRunConcurrently: item.canRunConcurrently } : {}),
+            ...(item.needsReview !== undefined ? { needsReview: item.needsReview } : {}),
+        };
+    });
+    return { phases, workItems };
+}
+// ---------------------------------------------------------------------------
+// Planner agent prompt
+// ---------------------------------------------------------------------------
+/**
+ * Build the system prompt for the read-only planning agent. It is explicit
+ * about the exact JSON contract and about the read-only posture (the agent's
+ * tool set already excludes write/edit/exec; this reinforces intent).
+ */
+export function buildPlannerSystemPrompt() {
+    return [
+        'You are a READ-ONLY planning agent. You may read, search, and analyze the codebase',
+        'to understand it, but you MUST NOT modify anything and you have no write/edit/exec tools.',
+        '',
+        'Decompose the given goal into an ordered set of work items. Respond with a SINGLE JSON',
+        'object and NOTHING else (no prose, no markdown outside a single optional ```json fence).',
+        '',
+        'Schema:',
+        '{',
+        '  "phases": [{ "title": string, "description"?: string }],   // optional; shared phase template',
+        '  "items": [{',
+        '    "title": string,            // required, non-empty, unique',
+        '    "brief": string,            // required, non-empty: what this item does',
+        '    "ordinal": number,          // required: execution order (0-based or 1-based, ascending)',
+        '    "phase"?: string,           // phase title this item belongs to',
+        '    "dependsOn"?: (string|number)[],  // item titles or ordinals this item depends on',
+        '    "suggestedArchetype"?: "engineer"|"reviewer"|"tester"|"researcher"|"integrator",',
+        '    "likelyFiles"?: string[],',
+        '    "verification"?: string[],',
+        '    "canRunConcurrently"?: boolean,',
+        '    "needsReview"?: boolean',
+        '  }],',
+        '  "dependencies"?: [{ "from": string|number, "to": string|number }],  // "from depends on to"',
+        '  "notes"?: string[],',
+        '  "risks"?: string[]',
+        '}',
+        '',
+        'Rules: dependencies must reference real items and must be acyclic. Every brief must be',
+        'non-empty. Keep the decomposition honest — if the goal is genuinely a single unit of work,',
+        'return exactly one item.',
+    ].join('\n');
+}
+function buildUserPrompt(request, repairErrors) {
+    const lines = [`Goal: ${request.goal}`, `Working directory: ${request.workingDir}`];
+    if (request.constraints?.capacity !== undefined)
+        lines.push(`Concurrency capacity: ${request.constraints.capacity}`);
+    if (request.constraints?.budgetUsd !== undefined)
+        lines.push(`Budget (USD): ${request.constraints.budgetUsd}`);
+    if (request.userContext)
+        lines.push('', 'Additional context:', request.userContext);
+    if (repairErrors && repairErrors.length > 0) {
+        lines.push('', 'Your previous response was rejected for these reasons. Fix ALL of them and respond again', 'with a single corrected JSON object:', ...repairErrors.map((e) => `  - ${e}`));
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// The service
+// ---------------------------------------------------------------------------
+/**
+ * Decompose a goal into a `PlanProposal`, honestly tagged with provenance.
+ *
+ * Control flow:
+ *  1. `config.mode === 'heuristic'` → the configured heuristic path (no agent).
+ *  2. The planner's decompose gate declines → honest single-item (no agent).
+ *  3. No runner available → heuristic fallback (reason: no runtime).
+ *  4. Agent path: run → parse → strict-validate → (assemble; issues===0 ?
+ *     accept : ONE repair attempt) → accept-or-fallback. Spawn error,
+ *     cancellation (kill / wall-timeout / token ceiling), or still-invalid
+ *     output after repair all fall back to the heuristic path with a reason.
+ */
+export async function decomposeGoal(request, planner, inputs, config, runner, deps = {}) {
+    const gate = planner.shouldDecompose(inputs);
+    const heuristicResult = (outcome) => {
+        const base = singleItemProposal(request.goal);
+        const fallbackReason = outcome.kind === 'fallback' ? outcome.reason : undefined;
+        const usage = outcome.kind === 'fallback' ? outcome.usage : undefined;
+        const elapsedMs = outcome.kind === 'fallback' ? outcome.elapsedMs : undefined;
+        const proposal = {
+            ...base,
+            decomposedBy: 'heuristic',
+            ...(fallbackReason ? { fallbackReason } : {}),
+            ...(usage ? { agentUsage: usage } : {}),
+            ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+        };
+        deps.onOutcome?.(outcome);
+        return { proposal, gate, issues: [], outcome };
+    };
+    if (config.mode === 'heuristic') {
+        return heuristicResult({ kind: 'heuristic-configured' });
+    }
+    if (!gate.decompose) {
+        return heuristicResult({ kind: 'gate-declined', reasonCode: gate.reasonCode });
+    }
+    if (!runner) {
+        return heuristicResult({ kind: 'fallback', reason: 'no planning agent runtime available' });
+    }
+    const systemPrompt = buildPlannerSystemPrompt();
+    let lastUsage;
+    let totalElapsedMs = 0;
+    const runOnce = async (attempt, repairErrors) => {
+        const result = await runner.run({
+            goal: request.goal,
+            workingDir: request.workingDir,
+            systemPrompt,
+            userPrompt: buildUserPrompt(request, repairErrors),
+            bounds: config.bounds,
+            attempt,
+        });
+        lastUsage = result.usage ?? lastUsage;
+        totalElapsedMs += result.elapsedMs;
+        return result;
+    };
+    // --- initial attempt ---
+    let run;
+    try {
+        run = await runOnce('initial');
+    }
+    catch (err) {
+        return heuristicResult({ kind: 'fallback', reason: `spawn error: ${err.message}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    if (run.status === 'cancelled') {
+        return heuristicResult({ kind: 'fallback', reason: `cancelled${run.detail ? ` (${run.detail})` : ''}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    if (run.status === 'failed') {
+        return heuristicResult({ kind: 'fallback', reason: `agent error: ${run.detail ?? 'unknown'}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    const accept = (proposal, issues, repaired) => {
+        const costUsd = lastUsage ? deps.estimateCostUsd?.(lastUsage) : undefined;
+        const decorated = {
+            ...proposal,
+            decomposedBy: 'agent',
+            elapsedMs: totalElapsedMs,
+            ...(lastUsage ? { agentUsage: lastUsage } : {}),
+            ...(costUsd !== undefined ? { agentCostUsd: costUsd } : {}),
+        };
+        const outcome = {
+            kind: 'agent',
+            itemCount: decorated.workItems.length,
+            repaired,
+            ...(lastUsage ? { usage: lastUsage } : {}),
+            ...(costUsd !== undefined ? { costUsd } : {}),
+            elapsedMs: totalElapsedMs,
+        };
+        deps.onOutcome?.(outcome);
+        return { proposal: decorated, gate, issues, outcome };
+    };
+    // --- validate the initial output ---
+    const first = parseDecomposition(run.output);
+    if (first.ok && first.raw) {
+        const { proposal, issues } = assemblePlanProposal(request.goal, gate.strategy, first.raw);
+        if (issues.length === 0)
+            return accept(proposal, issues, false);
+        // Not clean — fall through to a single repair with the assembler's issues.
+        const repairErrors = issues.map((i) => i.message);
+        const repaired = await tryRepair(repairErrors);
+        if (repaired)
+            return repaired;
+        return heuristicResult({ kind: 'fallback', reason: `invalid agent decomposition after repair: ${issues.map((i) => i.kind).join(', ')}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    }
+    // Malformed structure — one repair attempt with the parser's errors.
+    const repaired = await tryRepair(first.errors);
+    if (repaired)
+        return repaired;
+    return heuristicResult({ kind: 'fallback', reason: `malformed agent output after repair: ${first.errors.slice(0, 3).join('; ')}`, usage: lastUsage, elapsedMs: totalElapsedMs });
+    // --- one repair attempt: returns an accepted result, or null to fall back ---
+    async function tryRepair(repairErrors) {
+        let repairRun;
+        try {
+            repairRun = await runOnce('repair', repairErrors);
+        }
+        catch {
+            return null;
+        }
+        if (repairRun.status !== 'completed')
+            return null;
+        const parsed = parseDecomposition(repairRun.output);
+        if (!parsed.ok || !parsed.raw)
+            return null;
+        const { proposal, issues } = assemblePlanProposal(request.goal, gate.strategy, parsed.raw);
+        if (issues.length !== 0)
+            return null;
+        return accept(proposal, issues, true);
+    }
+}

package/dist/platform/core/plan-proposal.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Plan proposal types + pure assembler.
+ *
+ * This module turns a loose decomposition (produced by an LLM planning agent,
+ * or handed in directly by a caller) into a validated, typed `PlanProposal`.
+ * It is intentionally free of I/O and LLM calls: no filesystem access, no
+ * agent spawning, no network. It exists so `AdaptivePlanner` can stay a
+ * synchronous, deterministic, side-effect-free scorer while still producing
+ * a rich, structured artifact that an orchestration engine can render for
+ * human approval and (once approved) instantiate.
+ *
+ * A `PlanProposal` is DATA. It is never instantiated on its own — approval
+ * flows through the existing `ProjectPlanningState.executionApproved` gate
+ * (see `planProposalToPlanningState` below), and durable persistence reuses
+ * `ExecutionPlanManager` (see `planProposalToExecutionPlanItems` below).
+ * Neither adapter performs any I/O itself; they only shape data for callers
+ * that do.
+ */
+import type { ExecutionStrategy } from './adaptive-planner.js';
+import type { PlanItem } from './execution-plan.js';
+import type { ProjectPlanningState } from '../knowledge/project-planning/types.js';
+/** Archetypes a work item can suggest for its executing agent. Open-ended by design. */
+export type WorkItemArchetype = 'engineer' | 'reviewer' | 'tester' | 'researcher' | 'integrator' | string;
+/**
+ * A single unit of work inside a proposal.
+ *
+ * Field shapes deliberately mirror three existing types so downstream bridges
+ * are near-1:1 maps rather than translations:
+ *   - knowledge `ProjectPlanningTask` (approval-render bridge)
+ *   - knowledge `ProjectWorkPlanTask` (phaseId/dependency naming)
+ *   - core `PlanItem` (persistence bridge)
+ */
+export interface WorkItem {
+    id: string;
+    title: string;
+    brief: string;
+    phaseId: string;
+    dependsOn: string[];
+    suggestedArchetype?: WorkItemArchetype | undefined;
+    likelyFiles?: string[] | undefined;
+    verification?: string[] | undefined;
+    canRunConcurrently?: boolean | undefined;
+    needsReview?: boolean | undefined;
+}
+export interface Phase {
+    id: string;
+    title: string;
+    description?: string | undefined;
+    order: number;
+}
+/** Where a proposal's decomposition came from. */
+export type PlanProposalSource = 'planner-agent' | 'single-item-fallback' | 'caller-supplied';
+/**
+ * Honest provenance for how a proposal's work items were produced.
+ *
+ * - `'agent'`     — a read-only planning agent decomposed the goal, and its
+ *   output validated cleanly (possibly after one repair attempt).
+ * - `'heuristic'` — the deterministic single-item path produced the proposal,
+ *   either because `planner.decomposition` is configured to `'heuristic'`, the
+ *   planner's gate declined to decompose, or the agent path failed and fell
+ *   back. `fallbackReason` is set only in the failure case, never when the
+ *   heuristic path was chosen deliberately by config or gate.
+ */
+export type DecomposedBy = 'agent' | 'heuristic';
+/** Token usage reported by a planning-decomposition agent run. */
+export interface DecompositionAgentUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number | undefined;
+    readonly cacheWriteTokens?: number | undefined;
+    readonly totalTokens: number;
+}
+export interface PlanProposal {
+    id: string;
+    task: string;
+    strategy: ExecutionStrategy;
+    rationale: string;
+    phases: Phase[];
+    workItems: WorkItem[];
+    createdAt: number;
+    source: PlanProposalSource;
+    /**
+     * Provenance overlay set by the decomposition service (plan-decomposition.ts).
+     * Absent on proposals produced directly by `assemblePlanProposal` /
+     * `singleItemProposal`, which stay byte-compatible with pre-provenance tests.
+     */
+    decomposedBy?: DecomposedBy | undefined;
+    /** Token usage of the planning agent (present when the agent path ran, even on fallback). */
+    agentUsage?: DecompositionAgentUsage | undefined;
+    /** Estimated dollar cost of the planning agent run, when a pricing lookup was available. */
+    agentCostUsd?: number | undefined;
+    /** Wall-clock time the planning agent ran, in ms (present when the agent path ran). */
+    elapsedMs?: number | undefined;
+    /**
+     * Why the agent path fell back to the heuristic path. Set ONLY on honest
+     * failure fallbacks (spawn error, timeout, cancellation, or output that was
+     * still malformed after one repair attempt) — never when `'heuristic'` was
+     * chosen by config or by the planner's decompose gate.
+     */
+    fallbackReason?: string | undefined;
+}
+/** The loose JSON shape a planning agent (or a caller) emits, pre-validation. */
+export interface RawDecompositionPhase {
+    title: string;
+    description?: string | undefined;
+}
+export interface RawDecompositionWorkItem {
+    title: string;
+    brief: string;
+    phase: string;
+    dependsOn?: string[] | undefined;
+    suggestedArchetype?: string | undefined;
+    likelyFiles?: string[] | undefined;
+    verification?: string[] | undefined;
+    canRunConcurrently?: boolean | undefined;
+    needsReview?: boolean | undefined;
+}
+export interface RawDecomposition {
+    phases: RawDecompositionPhase[];
+    workItems: RawDecompositionWorkItem[];
+}
+/** Kinds of honest-partial issues `assemblePlanProposal` can flag without throwing. */
+export type PlanProposalIssueKind = 'dangling-dependency' | 'dependency-cycle' | 'unresolved-phase';
+export interface PlanProposalIssue {
+    readonly kind: PlanProposalIssueKind;
+    readonly workItemTitle: string;
+    readonly message: string;
+}
+/**
+ * Turn a raw decomposition into a validated, typed `PlanProposal`.
+ *
+ * Never throws. Malformed input degrades to an honest partial result: an
+ * unresolved phase reference lands its work item in a synthesized "Unphased"
+ * bucket; an unresolved dependency reference is dropped; a dependency cycle
+ * is flagged but left in place (no silent edge removal). Every problem is
+ * reported via the returned `issues` list rather than an exception.
+ *
+ * Dependency resolution mirrors `ExecutionPlanManager.replaceItems` exactly:
+ * a dep that already looks like a UUID passes through unchecked, otherwise
+ * it is resolved by case-insensitive title match, otherwise it is dropped.
+ *
+ * `source` defaults to `'planner-agent'` (the expected majority caller —
+ * `AdaptivePlanner.proposeWorkstream`). Pass `'caller-supplied'` when a
+ * non-agent caller hands in its own decomposition directly.
+ */
+export declare function assemblePlanProposal(task: string, strategy: ExecutionStrategy, raw: RawDecomposition, source?: Extract<PlanProposalSource, 'planner-agent' | 'caller-supplied'>): {
+    proposal: PlanProposal;
+    issues: PlanProposalIssue[];
+};
+/**
+ * The honest fallback: one phase ("Execute"), one work item whose title and
+ * brief both equal the task text, no dependencies. Used whenever decomposition
+ * was not warranted (see `AdaptivePlanner.shouldDecompose`) or no raw
+ * decomposition is available yet.
+ */
+export declare function singleItemProposal(task: string): PlanProposal;
+/**
+ * Project a `PlanProposal` into the existing `/plan approve` seam. This is
+ * data-only — no store is written here. The caller feeds the result into
+ * `ProjectPlanningService.upsertState` (or an equivalent), which is what
+ * actually persists it and evaluates readiness.
+ *
+ * Direction convention for the emitted `ProjectPlanningDependency` records
+ * (this type has no prior producer in the codebase to inherit a convention
+ * from, so it is fixed here): `fromTaskId` depends on `toTaskId`, i.e. the
+ * edge reads "fromTaskId depends on toTaskId" the same way `WorkItem.dependsOn`
+ * reads "this item depends on these ids".
+ *
+ * `ProjectPlanningTask` has no first-class phase concept, so phase
+ * membership is preserved in `metadata` rather than dropped silently.
+ *
+ * `executionApproved` is always `false` here — approval is a separate,
+ * explicit step owned by `/plan approve` (planning-runtime.ts), never implied
+ * by proposing.
+ */
+export declare function planProposalToPlanningState(proposal: PlanProposal): Partial<ProjectPlanningState>;
+/**
+ * Project a `PlanProposal` into the plain items `ExecutionPlanManager` deals
+ * in. This is a deliberately lossy projection: `PlanItem` has no room for
+ * verification/likelyFiles/suggestedArchetype, and those stay in the
+ * full-fidelity `ProjectPlanningState` render above. It exists purely so a
+ * caller can hand a proposal's items to `ExecutionPlanManager` without
+ * re-deriving the phase/description/dependency shape by hand.
+ *
+ * Dependencies are expressed as WORK ITEM TITLES, not ids, because
+ * `ExecutionPlanManager.create()` does not resolve dependency references —
+ * only `ExecutionPlanManager.replaceItems()` does, by case-insensitive
+ * description match. The intended call sequence at instantiation is
+ * therefore:
+ *
+ *   const plan = planManager.create(title, []);
+ *   const { items } = planProposalToExecutionPlanItems(proposal);
+ *   planManager.replaceItems(plan.id, items);
+ *
+ * which reuses `replaceItems`' existing dependency resolver end-to-end
+ * instead of re-implementing dependency resolution here. This module defines
+ * no scheduler of its own — ready-to-run item selection stays
+ * `ExecutionPlanManager.getNextItems`'s job.
+ */
+export declare function planProposalToExecutionPlanItems(proposal: PlanProposal): {
+    title: string;
+    items: Array<Omit<PlanItem, 'id' | 'status'>>;
+};
+//# sourceMappingURL=plan-proposal.d.ts.map

package/dist/platform/core/plan-proposal.d.ts.map

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