poly-weaver 0.15.3 → 1.1.0

package/dist/agents/plan-steering.js

@@ -0,0 +1,102 @@
+import { ITER, SPEC } from "../flow/types.js";
+import { REVIEW_FEEDBACK } from "../user/review-feedback.js";
+const COMMON = "## User clarification and steering\n\nKeep the plan aligned with explicit user guidance from question answers, ordinary chat, or labeled user review feedback, without a separate edit request. Integrate its meaning into the relevant plan sections rather than append comments verbatim. Distinguish user guidance from reviewer findings; reviewer findings alone are not user steering. Later explicit user guidance supersedes conflicting earlier intent; unrelated discussion and your own preferences do not authorize scope changes.";
+const PLAN_ONLY = "Edit only the plan; do not edit repository files.";
+const REVIEW_ONLY = "Edit the plan only for explicit user guidance; report other findings as review issues instead of fixing them. Do not edit repository files.";
+const DEFER_SPEC = "Record required Iteration Spec changes in the plan rather than applying them.";
+const IMPLEMENTATION_VERDICT = "Base your verdict on the updated plan. Do not approve while required implementation or specification work remains outstanding; documenting it in the plan is not completion.";
+export function appendPlanSteering(prompt, role, managed, context, implReplan = false) {
+    if (!context)
+        return prompt;
+    const references = [];
+    const seen = new Set();
+    for (const [label, file] of [
+        ["Read the current main plan", context.mainPlanFile],
+        ["Read the current change plan", context.changePlanFile],
+        ["Read the selected pending Iteration Spec", context.iterationSpecFile],
+    ]) {
+        if (!file || seen.has(file))
+            continue;
+        seen.add(file);
+        if (!prompt.includes(file))
+            references.push(`${label}: ${file}`);
+    }
+    let responsibility;
+    switch (role) {
+        case "planner":
+            responsibility = `${PLAN_ONLY}${managed ? ` ${DEFER_SPEC}` : ""}`;
+            break;
+        case "plan-reviewer":
+            responsibility = `${REVIEW_ONLY}${managed ? ` ${DEFER_SPEC}` : ""} Base your verdict and any plan citations on the updated plan.`;
+            break;
+        case "implementor":
+            responsibility = managed
+                ? "Align the selected pending Iteration Spec with changed durable intent, including changes recorded in the plan. Complete the required implementation and current-spec application. Applied history is immutable."
+                : "";
+            break;
+        case "implementation-reviewer":
+            responsibility = `${REVIEW_ONLY}${managed ? ` ${DEFER_SPEC}` : ""} ${IMPLEMENTATION_VERDICT}`;
+            break;
+    }
+    let suffix = "";
+    if (role === "planner" && implReplan) {
+        suffix = "Write one complete revised plan, retaining the full intended scope and clearly identifying the implementation delta. Do not edit any other plan file.";
+    }
+    else if (role === "implementor" && context.changePlanKind === "complete") {
+        suffix = "The supplied plan includes the full intended scope and identifies the implementation delta. Apply the delta without repeating completed work.";
+    }
+    else if (role === "implementor" && context.changePlanKind === "delta") {
+        suffix = "Read the main plan together with the separate change plan. Apply the delta and incorporate its explicit user steering and required specification changes into the main plan; do not replace the main plan with a delta-only plan.";
+    }
+    const feedback = context.reviewFeedbackFile
+        ? [
+            `Read the retained user review context: ${context.reviewFeedbackFile}`,
+            "Batches are chronological. Issue snapshots are reviewer findings; keep/drop/revise are user decisions, and additions and rejection comments are user-authored. Keeping a finding does not make it user steering. A drop is an intentional waiver, not proof of a fix; respect it without re-raising rephrasings, unless later explicit user guidance supersedes it. This is retained context, not a new verdict-refinement request.",
+            role === "planner"
+                ? "Incorporate unconsumed additions and revision guidance into the complete plan, alongside retained drops and the immediate feedback. Preserve their meaning and constraints, not a verbatim appendix."
+                : "",
+        ].filter(Boolean).join("\n\n")
+        : "";
+    return [prompt, references.join("\n"), COMMON, responsibility, suffix, feedback]
+        .filter(Boolean).join("\n\n");
+}
+/** Runtime identity, not snapshotted factory code, owns this permission. */
+export function defaultPlanSteering(kind, name, steps) {
+    if (kind !== "built-in" || name !== "default")
+        return undefined;
+    const planner = steps.find((step) => step.role === "planner");
+    if (!planner?.writes.plan)
+        return undefined;
+    const changePlanner = steps.find((step) => step.role === "planner" && step.writes.plan !== planner.writes.plan);
+    const implementor = steps.find((step) => step.role === "implementor");
+    return {
+        mainPlanKey: planner.writes.plan,
+        changePlanKey: implementor?.reads.revisePlan ?? changePlanner?.writes.plan,
+    };
+}
+export function resolvePlanSteering(step, ctx) {
+    if (!ctx.planSteering || !(step.role === "planner" || step.role === "implementor" ||
+        (step.role === "reviewer" && (!step.variant || step.variant === "plan" || step.variant === "impl"))))
+        return undefined;
+    const mainPlanFile = ctx.artifacts.getFile(ctx.planSteering.mainPlanKey);
+    const changeKey = step.reads.revisePlan ?? ctx.planSteering.changePlanKey;
+    const change = changeKey ? ctx.artifacts.get(changeKey) : undefined;
+    const consumingChange = step.role === "implementor" && !!step.reads.revisePlan && !!change?.file;
+    return {
+        mainPlanFile,
+        reviewFeedbackFile: ctx.artifacts.getFile(REVIEW_FEEDBACK),
+        changePlanFile: change?.meta?.steeringIncorporated && !consumingChange ? undefined : change?.file,
+        iterationSpecFile: step.managedSpec
+            ? ctx.artifacts.getFile(ITER) ?? (step.reads.spec ? ctx.artifacts.getFile(step.reads.spec) : undefined)
+            : undefined,
+        changePlanKind: consumingChange
+            ? change.meta?.completeSuccessor === true ? "complete" : "delta"
+            : undefined,
+    };
+}
+export function steeringRationaleFile(step, ctx) {
+    return step.managedSpec
+        ? ctx.artifacts.getFile(step.reads.explanation ?? SPEC)
+        : undefined;
+}
+//# sourceMappingURL=plan-steering.js.map

package/dist/agents/plan-steering.js.map

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

package/dist/agents/planners/adapter.d.ts

@@ -2,15 +2,17 @@ import type { PlannerDriver, PlanResult, PlannerPromptSet } from "./types.js";
 import type { ProviderStrategy } from "../../providers/types.js";
 import type { ProviderContext } from "../../flow/types.js";
 import { BaseAdapter } from "../runner.js";
+import { type PlanSteeringContext } from "../plan-steering.js";
 type PlannerRunOptions = {
     outputPlanFile?: string;
     resumeSessionId?: string;
     planFile?: string;
     explanationFile?: string;
     feedbackFile?: string;
-    feedbackSource?: "reviewer" | "user";
+    feedbackSource?: "reviewer" | "user" | "curated";
     implReplan?: boolean;
     managedSpec?: boolean;
+    planSteering?: PlanSteeringContext;
 };
 export declare function selectPlannerPrompt(taskFile: string, opts: PlannerRunOptions, prompts?: PlannerPromptSet): string;
 export declare class PlannerAdapter extends BaseAdapter implements PlannerDriver {

package/dist/agents/planners/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,gBAAwC,GAChD,MAAM,CA4CR;AAED,qBAAa,cAAe,SAAQ,WAAY,YAAW,aAAa;IAIpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,EACE,OAAO,CAAC,EAAE,gBAAgB,YAAA,EAC3C,IAAI,CAAC,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,eAAe,EACzB,iBAAiB,CAAC,EAAE,MAAM;IAKtB,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,UAAU,CAAC;CA6DvB"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEnF,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,gBAAwC,GAChD,MAAM,CAKR;AA2DD,qBAAa,cAAe,SAAQ,WAAY,YAAW,aAAa;IAIpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,EACE,OAAO,CAAC,EAAE,gBAAgB,YAAA,EAC3C,IAAI,CAAC,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,eAAe,EACzB,iBAAiB,CAAC,EAAE,MAAM;IAKtB,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,UAAU,CAAC;CAsEvB"}

package/dist/agents/planners/adapter.js

@@ -1,21 +1,26 @@
 import { BaseAdapter } from "../runner.js";
 import { defaultPlannerPrompts } from "./prompts.js";
+import { writeFile } from "node:fs/promises";
+import { appendPlanSteering } from "../plan-steering.js";
 export function selectPlannerPrompt(taskFile, opts, prompts = defaultPlannerPrompts) {
+    return appendPlanSteering(selectBasePlannerPrompt(taskFile, opts, prompts), "planner", opts.managedSpec === true, opts.planSteering, opts.implReplan);
+}
+function selectBasePlannerPrompt(taskFile, opts, prompts) {
     if (opts.feedbackFile) {
         // Impl-replan: dedicated prompts with correct labels
         if (opts.implReplan) {
             if (opts.resumeSessionId) {
-                return prompts.implResumeRevision(opts.feedbackFile, opts.outputPlanFile);
+                return prompts.implResumeRevision(opts.feedbackFile, opts.outputPlanFile, opts.planSteering, opts.explanationFile);
             }
-            return prompts.implRevision(taskFile, opts.planFile, opts.feedbackFile, opts.outputPlanFile);
+            return prompts.implRevision(taskFile, opts.planFile, opts.feedbackFile, opts.outputPlanFile, opts.planSteering, opts.explanationFile);
         }
         // Normal plan revision
         if (opts.resumeSessionId) {
-            return prompts.resumeRevision(opts.feedbackFile, opts.feedbackSource ?? "reviewer", opts.outputPlanFile, opts.managedSpec, opts.explanationFile);
+            return prompts.resumeRevision(opts.feedbackFile, opts.feedbackSource ?? "reviewer", opts.outputPlanFile, opts.managedSpec, opts.explanationFile, opts.planSteering);
         }
-        return prompts.revision(taskFile, opts.planFile, opts.feedbackFile, opts.feedbackSource ?? "reviewer", opts.outputPlanFile, opts.managedSpec, opts.explanationFile);
+        return prompts.revision(taskFile, opts.planFile, opts.feedbackFile, opts.feedbackSource ?? "reviewer", opts.outputPlanFile, opts.managedSpec, opts.explanationFile, opts.planSteering);
     }
-    return prompts.initial(taskFile, opts.outputPlanFile, opts.managedSpec, opts.explanationFile);
+    return prompts.initial(taskFile, opts.outputPlanFile, opts.managedSpec, opts.explanationFile, opts.planSteering);
 }
 export class PlannerAdapter extends BaseAdapter {
     prompts;
@@ -44,24 +49,31 @@ export class PlannerAdapter extends BaseAdapter {
             promptPrefix: planMode.argPrefix,
             planMode: true,
         });
-        // Extract clarifications and plan file path in parallel — both read the
-        // same session file independently and have no data dependency.
-        const [clarifications, planFilePath] = await Promise.all([
-            this.strategy.session.extractClarifications
-                ? this.strategy.session.extractClarifications(result.sessionFilePath, result.lineOffset)
-                : [],
-            this.strategy.session.extractPlanFilePath
-                ? this.strategy.session.extractPlanFilePath(result.sessionFilePath, result.lineOffset)
-                : undefined,
-        ]);
+        let nativePlanFilePath = result.nativePlanResult?.path;
+        if (!nativePlanFilePath
+            && result.nativePlanResult?.content !== undefined
+            && opts.outputPlanFile) {
+            await writeFile(opts.outputPlanFile, result.nativePlanResult.content, "utf-8");
+            nativePlanFilePath = opts.outputPlanFile;
+        }
+        if (!nativePlanFilePath
+            && result.observed
+            && result.responseText.trim().length > 0
+            && opts.outputPlanFile) {
+            await writeFile(opts.outputPlanFile, result.responseText, "utf-8");
+            nativePlanFilePath = opts.outputPlanFile;
+        }
+        const planFilePath = nativePlanFilePath ??
+            (!result.observed && this.strategy.session.extractPlanFilePath
+                ? await this.strategy.session.extractPlanFilePath(result.sessionFilePath, result.lineOffset)
+                : undefined);
         if (planMode.nativePlanFile && !planFilePath) {
-            // Native mode must extract a provider plan path; outputPlanFile fallback is non-native only.
-            throw new Error("Native plan file extraction failed: no plan file found in session JSONL");
+            // Native mode must provide a provider plan path or SDK plan content.
+            throw new Error("Native plan file extraction failed: no plan path or content was returned");
         }
         return {
             sessionId: result.sessionId,
             rawText: result.responseText,
-            clarifications: clarifications.length > 0 ? clarifications : undefined,
             agentUsed: this.name,
             planFilePath,
             sessionFilePath: this.sessionFilePath,

package/dist/agents/planners/adapter.js.map

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

package/dist/agents/planners/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAmB7B,qBAAa,kBAAmB,YAAW,WAAW;IAGxC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,WAAW,CAAK;gBAEJ,MAAM,EAAE,aAAa;IAEnC,OAAO,CACX,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;CAqIvB"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/handler.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAoB7B,qBAAa,kBAAmB,YAAW,WAAW;IAGxC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,WAAW,CAAK;gBAEJ,MAAM,EAAE,aAAa;IAEnC,OAAO,CACX,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;CAuHvB"}

package/dist/agents/planners/handler.js

@@ -1,9 +1,11 @@
-import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { appendClarifications } from "../../prompts.js";
+import { randomUUID } from "node:crypto";
+import { refreshSteeringPlans } from "../../flow/artifacts.js";
+import { resolvePlanSteering, steeringRationaleFile } from "../plan-steering.js";
+import { consumePlannerFeedback, materializeReviewFeedback, pendingPlannerFeedback } from "../../user/review-feedback.js";
 import { readPlanFromContract, removeFileIfExists, } from "../../orchestrator.js";
 import { TASK, } from "../../flow/types.js";
-import { bindAttemptFailureReporter, bindDriverRuntime, bindPtyBufferReporter, bindSessionReporter, flushDriverSidecar, } from "../runner.js";
+import { bindAttemptFailureReporter, bindDriverRuntime, bindObserverDiagnosticsReporter, bindPtyBufferReporter, bindSessionReporter, flushDriverSidecar, } from "../runner.js";
 import { bindStepLiveSidecar, cleanupStepLiveSidecar, resolveResumeSessionId, } from "../session-resume.js";
 /** Return the plan file path for a given version (1-based). */
 function planFileForVersion(root, version) {
@@ -16,28 +18,41 @@ export class PlannerRoleHandler {
         this.driver = driver;
     }
     async execute(step, ctx, retry) {
-        const specFile = (step.reads.spec && ctx.artifacts.getFile(step.reads.spec))
+        await refreshSteeringPlans(ctx);
+        await materializeReviewFeedback(ctx);
+        const feedbackBatches = pendingPlannerFeedback(ctx);
+        const planSteering = resolvePlanSteering(step, ctx);
+        const implReplan = planSteering
+            ? step.writes.plan !== ctx.planSteering.mainPlanKey
+            : !step.reads.spec && step.reads.task !== undefined && step.reads.task !== TASK;
+        const specFile = (implReplan ? planSteering?.mainPlanFile : undefined)
+            ?? (step.reads.spec && ctx.artifacts.getFile(step.reads.spec))
             ?? (step.reads.task && ctx.artifacts.getFile(step.reads.task));
         if (!specFile)
             throw new Error("PlannerRoleHandler: spec or task artifact missing");
-        const explanationFile = step.managedSpec && step.reads.explanation
-            ? ctx.artifacts.getFile(step.reads.explanation)
-            : undefined;
+        const explanationFile = planSteering ? steeringRationaleFile(step, ctx)
+            : step.managedSpec && step.reads.explanation
+                ? ctx.artifacts.getFile(step.reads.explanation)
+                : undefined;
         // Read feedback from verdict artifact (set by incorporateFeedback)
         const verdictArtifact = step.reads.verdict
             ? ctx.artifacts.get(step.reads.verdict) : undefined;
         const feedbackFile = verdictArtifact?.file;
-        const feedbackSource = feedbackFile
-            ? verdictArtifact?.meta?.source
+        const source = verdictArtifact?.meta?.source;
+        const feedbackSource = feedbackFile && (source === "reviewer" || source === "user" || source === "curated")
+            ? source
             : undefined;
-        const prevPlanFile = ctx.artifacts.getFile(step.writes.plan);
-        if (this.planVersion === 0) {
-            const restoredVersion = ctx.artifacts.getMeta(step.writes.plan, "version");
-            if (restoredVersion != null && restoredVersion > 0)
+        const prevPlanFile = planSteering && !implReplan
+            ? planSteering.mainPlanFile : ctx.artifacts.getFile(step.writes.plan);
+        if (this.planVersion === 0 || planSteering) {
+            const restoredVersion = ctx.artifacts.getMeta(planSteering ? ctx.planSteering.mainPlanKey : step.writes.plan, "version");
+            if (restoredVersion != null && restoredVersion > this.planVersion)
                 this.planVersion = restoredVersion;
         }
         this.planVersion++;
-        const outputPlanFile = planFileForVersion(ctx.sessionDir, this.planVersion);
+        const outputPlanFile = planSteering
+            ? join(ctx.sessionDir, `plan-v${this.planVersion}-${randomUUID()}.md`)
+            : planFileForVersion(ctx.sessionDir, this.planVersion);
         const stepAny = step;
         const sessionKey = stepAny.sessionShareKey ?? step.id;
         const boundaryFired = stepAny.sessionBoundary?.(ctx) === true;
@@ -45,16 +60,15 @@ export class PlannerRoleHandler {
             ctx.sessionIds.delete(sessionKey);
         }
         const resumeSessionId = await resolveResumeSessionId(ctx, stepAny, this.driver, sessionKey, ctx.sessionIds.get(sessionKey), boundaryFired);
-        // implReplan is the "impl-review revising the plan" case: a planner step
-        // whose task input is remapped to something other than TASK (and whose
-        // input is therefore not the original task). Spec-driven planning still
-        // reads `spec`, NOT a remapped task, so it must NOT be flagged as
-        // impl-replan. The flag selects implementation-plan/review prompt labels.
-        const implReplan = !step.reads.spec && step.reads.task !== undefined && step.reads.task !== TASK;
         bindSessionReporter(this.driver, ctx.lastStepSessionFilePaths);
         bindPtyBufferReporter(this.driver, ctx);
         bindAttemptFailureReporter(this.driver, ctx);
-        bindDriverRuntime(this.driver, { output: ctx.output, terminalHost: ctx.terminalHost });
+        bindObserverDiagnosticsReporter(this.driver, ctx);
+        bindDriverRuntime(this.driver, {
+            output: ctx.output,
+            terminalHost: ctx.terminalHost,
+            providerObserverRuns: ctx.providerObserverRuns,
+        });
         const sidecarPath = bindStepLiveSidecar(this.driver, ctx, sessionKey, stepAny.driver);
         let planResult;
         let planText;
@@ -72,6 +86,7 @@ export class PlannerRoleHandler {
                     feedbackSource,
                     implReplan,
                     managedSpec: step.managedSpec === true,
+                    planSteering,
                 });
                 const actualPlanFile = planResult.planFilePath ?? outputPlanFile;
                 const planText = await readPlanFromContract(actualPlanFile);
@@ -86,48 +101,27 @@ export class PlannerRoleHandler {
             ctx.lastStepSessionFilePaths?.push(planResult.sessionFilePath);
         }
         // Store plan artifact (use the actual file the plan was written to)
-        ctx.artifacts.set(step.writes.plan, {
+        const artifact = {
             file: actualPlanFile,
             text: planText,
-            meta: { version: this.planVersion },
-        });
+            meta: {
+                version: this.planVersion,
+                ...(planSteering ? {
+                    steeringPlan: true,
+                    canonicalPlanKey: ctx.planSteering.mainPlanKey,
+                    ...(implReplan ? { completeSuccessor: true } : {}),
+                } : {}),
+            },
+        };
+        if (planSteering)
+            ctx.artifacts.set(ctx.planSteering.mainPlanKey, artifact);
+        ctx.artifacts.set(step.writes.plan, artifact);
+        await refreshSteeringPlans(ctx);
+        await consumePlannerFeedback(ctx, step, feedbackBatches);
         // Track session for resume
         if (planResult.sessionId) {
             ctx.sessionIds.set(sessionKey, planResult.sessionId);
         }
-        // Merge in-planning clarifications (AskUserQuestion Q&A) into the
-        // planner's input baseline: spec if present, task otherwise.
-        if (!step.managedSpec && planResult.clarifications?.length) {
-            const specKey = step.reads.spec;
-            const taskKey = step.reads.task;
-            const specArtifact = specKey ? ctx.artifacts.get(specKey) : undefined;
-            const baseline = specArtifact?.text != null
-                ? { key: specKey, artifact: specArtifact }
-                : (() => {
-                    if (!taskKey || taskKey !== TASK)
-                        return null;
-                    const taskArtifact = ctx.artifacts.get(taskKey);
-                    return taskArtifact?.text != null
-                        ? { key: taskKey, artifact: taskArtifact }
-                        : null;
-                })();
-            if (baseline) {
-                const entries = planResult.clarifications.map((c) => ({
-                    type: "qa",
-                    clarification: c,
-                }));
-                const result = appendClarifications(baseline.artifact.text, entries, ctx.nextClarificationNumber);
-                ctx.nextClarificationNumber = result.nextNumber;
-                ctx.artifacts.set(baseline.key, {
-                    ...baseline.artifact,
-                    text: result.content,
-                    file: baseline.artifact.file,
-                });
-                if (baseline.artifact.file) {
-                    await writeFile(baseline.artifact.file, result.content, "utf-8");
-                }
-            }
-        }
         await cleanupStepLiveSidecar(sidecarPath);
         return { kind: "continue" };
     }

package/dist/agents/planners/handler.js.map

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

package/dist/agents/planners/prompts.d.ts

@@ -1,8 +1,9 @@
 import type { PlannerPromptSet } from "./types.js";
-export declare function buildPlannerPrompt(taskFile: string, outputPlanFile: string | undefined, managedSpec?: boolean, explanationFile?: string): string;
-export declare function buildRevisionPrompt(taskFile: string, planFile: string | undefined, feedbackFile: string, source: "reviewer" | "user", outputPlanFile: string | undefined, managedSpec?: boolean, explanationFile?: string): string;
-export declare function buildResumeRevisionPrompt(feedbackFile: string, source: "reviewer" | "user", outputPlanFile: string | undefined, managedSpec?: boolean, explanationFile?: string): string;
-export declare function buildImplRevisionPrompt(planFile: string, prevRevisePlanFile: string | undefined, feedbackFile: string, outputPlanFile: string | undefined): string;
-export declare function buildImplResumeRevisionPrompt(feedbackFile: string, outputPlanFile: string | undefined): string;
+import type { PlanSteeringContext } from "../plan-steering.js";
+export declare function buildPlannerPrompt(taskFile: string, outputPlanFile: string | undefined, managedSpec?: boolean, explanationFile?: string, steering?: PlanSteeringContext): string;
+export declare function buildRevisionPrompt(taskFile: string, planFile: string | undefined, feedbackFile: string, source: "reviewer" | "user" | "curated", outputPlanFile: string | undefined, managedSpec?: boolean, explanationFile?: string, steering?: PlanSteeringContext): string;
+export declare function buildResumeRevisionPrompt(feedbackFile: string, source: "reviewer" | "user" | "curated", outputPlanFile: string | undefined, managedSpec?: boolean, explanationFile?: string, steering?: PlanSteeringContext): string;
+export declare function buildImplRevisionPrompt(planFile: string, prevRevisePlanFile: string | undefined, feedbackFile: string, outputPlanFile: string | undefined, steering?: PlanSteeringContext, explanationFile?: string): string;
+export declare function buildImplResumeRevisionPrompt(feedbackFile: string, outputPlanFile: string | undefined, steering?: PlanSteeringContext, explanationFile?: string): string;
 export declare const defaultPlannerPrompts: PlannerPromptSet;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/agents/planners/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAmEnD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,UAAQ,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAoBR;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,UAAQ,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAkCR;AAED,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,UAAU,GAAG,MAAM,EAC3B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,UAAQ,EACnB,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAqBR;AAID,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAcR;AAED,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAQR;AAID,eAAO,MAAM,qBAAqB,EAAE,gBAMnC,CAAC"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAmE/D,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,UAAQ,EACnB,eAAe,CAAC,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,MAAM,CAoBR;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,EACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,UAAQ,EACnB,eAAe,CAAC,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,MAAM,CAkCR;AAED,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,EACvC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,UAAQ,EACnB,eAAe,CAAC,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,MAAM,CAqBR;AAID,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,QAAQ,CAAC,EAAE,mBAAmB,EAC9B,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAmBR;AAED,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,QAAQ,CAAC,EAAE,mBAAmB,EAC9B,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAcR;AAID,eAAO,MAAM,qBAAqB,EAAE,gBAMnC,CAAC"}

package/dist/agents/planners/prompts.js

@@ -1,4 +1,4 @@
-const MANAGED_ITERATION_CLOSURE_DIRECTIVE = "Do not move the Iteration Spec to `applied/`; a later stage does that.";
+import { managedIterationClosureDirective } from "../prompt-utils.js";
 /** Append the "write plan as markdown" instruction when an output path is given. */
 function appendOutputFileInstruction(lines, outputPlanFile) {
     if (outputPlanFile) {
@@ -19,7 +19,7 @@ function managedExplanationLine(explanationFile) {
         ? `Read its supporting Iteration Rationale: ${explanationFile}`
         : "No supporting Iteration Rationale file was provided.";
 }
-function managedPlannerRepositorySpecificationLines(revision = false) {
+function managedPlannerRepositorySpecificationLines(revision = false, steering) {
     return [
         "## Repository specification",
         "",
@@ -35,17 +35,19 @@ function managedPlannerRepositorySpecificationLines(revision = false) {
         "### Legacy-spec migration",
         "### Consistency checks",
         "",
-        "Only propose an Iteration Spec update for an important uncovered or contradictory point, and call it out clearly. Write `None` under Iteration updates when no update is needed.",
+        steering
+            ? "Record required Iteration Spec changes under Iteration updates when explicit user guidance changes durable requirements, rationale, scope, or acceptance outcomes, or when an important uncovered or contradictory point requires correction. Describe each proposed change clearly; do not edit the Iteration Spec. Write `None` when no update is needed."
+            : "Only propose an Iteration Spec update for an important uncovered or contradictory point, and call it out clearly. Write `None` under Iteration updates when no update is needed.",
         "",
         "## Strict rules",
         "",
         "- Do not modify repository files.",
-        `- ${MANAGED_ITERATION_CLOSURE_DIRECTIVE}`,
-        "- In native plan mode, write the plan only through the provider's native plan mechanism; do not create or edit working-tree files.",
+        `- ${managedIterationClosureDirective(steering)}`,
+        ...(steering ? [] : ["- In native plan mode, write the plan only through the provider's native plan mechanism; do not create or edit working-tree files."]),
     ];
 }
 // ── Planner prompts ──
-export function buildPlannerPrompt(taskFile, outputPlanFile, managedSpec = false, explanationFile) {
+export function buildPlannerPrompt(taskFile, outputPlanFile, managedSpec = false, explanationFile, steering) {
     if (managedSpec) {
         const lines = [
             `Read the accepted Iteration Spec: ${taskFile}`,
@@ -53,7 +55,7 @@ export function buildPlannerPrompt(taskFile, outputPlanFile, managedSpec = false
             "",
             "Create an implementation plan.",
             "",
-            ...managedPlannerRepositorySpecificationLines(),
+            ...managedPlannerRepositorySpecificationLines(false, steering),
         ];
         appendManagedPlanOutputInstruction(lines, outputPlanFile);
         return lines.join("\n");
@@ -66,8 +68,8 @@ export function buildPlannerPrompt(taskFile, outputPlanFile, managedSpec = false
     appendOutputFileInstruction(lines, outputPlanFile);
     return lines.join("\n");
 }
-export function buildRevisionPrompt(taskFile, planFile, feedbackFile, source, outputPlanFile, managedSpec = false, explanationFile) {
-    const sourceLabel = source === "reviewer" ? "reviewer's" : "user's";
+export function buildRevisionPrompt(taskFile, planFile, feedbackFile, source, outputPlanFile, managedSpec = false, explanationFile, steering) {
+    const sourceLabel = source === "curated" ? "curated mixed reviewer/user" : source === "reviewer" ? "reviewer's" : "user's";
     if (managedSpec) {
         const lines = [
             `Read the accepted Iteration Spec: ${taskFile}`,
@@ -76,7 +78,7 @@ export function buildRevisionPrompt(taskFile, planFile, feedbackFile, source, ou
         if (planFile) {
             lines.push(`Read your previous implementation plan: ${planFile}`);
         }
-        lines.push(`Read the ${sourceLabel} feedback: ${feedbackFile}`, "", `Revise the implementation plan to address the ${sourceLabel} feedback.`, "", ...managedPlannerRepositorySpecificationLines(true));
+        lines.push(`Read the ${sourceLabel} feedback: ${feedbackFile}`, "", `Revise the implementation plan to address the ${sourceLabel} feedback.`, "", ...managedPlannerRepositorySpecificationLines(true, steering));
         appendManagedPlanOutputInstruction(lines, outputPlanFile);
         return lines.join("\n");
     }
@@ -90,15 +92,15 @@ export function buildRevisionPrompt(taskFile, planFile, feedbackFile, source, ou
     appendOutputFileInstruction(lines, outputPlanFile);
     return lines.join("\n");
 }
-export function buildResumeRevisionPrompt(feedbackFile, source, outputPlanFile, managedSpec = false, explanationFile) {
-    const sourceLabel = source === "reviewer" ? "reviewer's" : "user's";
+export function buildResumeRevisionPrompt(feedbackFile, source, outputPlanFile, managedSpec = false, explanationFile, steering) {
+    const sourceLabel = source === "curated" ? "curated mixed reviewer/user" : source === "reviewer" ? "reviewer's" : "user's";
     if (managedSpec) {
         const lines = [
             `Read the new ${sourceLabel} feedback: ${feedbackFile}`,
             ...(explanationFile ? [`Read the supporting Iteration Rationale: ${explanationFile}`] : []),
             "",
             "Retain the accepted Iteration Spec and repository-specification scope. Revise every affected implementation and .poly-spec application step for the new feedback.",
-            MANAGED_ITERATION_CLOSURE_DIRECTIVE,
+            managedIterationClosureDirective(steering),
         ];
         appendManagedPlanOutputInstruction(lines, outputPlanFile, true);
         return lines.join("\n");
@@ -112,23 +114,35 @@ export function buildResumeRevisionPrompt(feedbackFile, source, outputPlanFile,
     return lines.join("\n");
 }
 // ── Impl-revision planner prompts ──
-export function buildImplRevisionPrompt(planFile, prevRevisePlanFile, feedbackFile, outputPlanFile) {
+export function buildImplRevisionPrompt(planFile, prevRevisePlanFile, feedbackFile, outputPlanFile, steering, explanationFile) {
     const lines = [
         `Read the approved implementation plan: ${planFile}`,
     ];
-    if (prevRevisePlanFile) {
+    if (prevRevisePlanFile && prevRevisePlanFile !== planFile) {
         lines.push(`Read your previous change plan: ${prevRevisePlanFile}`);
     }
-    lines.push(`Read the implementation review: ${feedbackFile}`, "", "Create a change plan to address the review issues.");
+    lines.push(`Read the implementation review: ${feedbackFile}`, "", steering
+        ? "Revise the complete main plan to address the implementation review, clearly identifying the implementation delta."
+        : "Create a change plan to address the review issues.");
+    if (steering?.iterationSpecFile) {
+        lines.push(managedExplanationLine(explanationFile), "", ...managedPlannerRepositorySpecificationLines(true, steering));
+    }
     appendOutputFileInstruction(lines, outputPlanFile);
     return lines.join("\n");
 }
-export function buildImplResumeRevisionPrompt(feedbackFile, outputPlanFile) {
+export function buildImplResumeRevisionPrompt(feedbackFile, outputPlanFile, steering, explanationFile) {
     const lines = [
         `Read the new implementation review: ${feedbackFile}`,
         "",
-        "Create a new change plan to address the issues.",
+        steering
+            ? "Revise the complete main plan to address the implementation review, clearly identifying the implementation delta."
+            : "Create a new change plan to address the issues.",
     ];
+    if (steering?.iterationSpecFile) {
+        if (explanationFile)
+            lines.push(managedExplanationLine(explanationFile));
+        lines.push("Retain the complete implementation and repository-specification scope.", managedIterationClosureDirective(steering));
+    }
     appendOutputFileInstruction(lines, outputPlanFile);
     return lines.join("\n");
 }