@skyramp/mcp 0.1.8 → 0.2.0-rc.2

package/build/prompts/test-recommendation/promptPlan.js

@@ -0,0 +1,290 @@
+/**
+ * PromptPlan — structured prompt composition with phases, steps, and sub-steps.
+ *
+ * Design goals:
+ * - Main steps are always non-conditional; their labels (1, 2, 3, …) are
+ *   static string constants usable in tests without calling any function.
+ * - Sub-steps are sequentially numbered within their parent (1.1, 1.2, 2.1, …).
+ *   No manually chosen suffixes — insertion or removal automatically renumbers.
+ * - Conditional sub-steps: when absent, remaining siblings re-number so the
+ *   LLM never sees a gap in the step sequence.
+ * - Phases group steps under an optional named heading with a configurable
+ *   rendering style.
+ * - preview(params) returns a structured snapshot for developer inspection:
+ *   which steps are active, what their labels are, and why conditional ones
+ *   are absent.
+ *
+ * Usage:
+ *   const _plan = new PromptPlan<MyParams>()
+ *     .addPhase("main", "Task Instructions", { headerLevel: "##", stepFormat: "hash" })
+ *     .step("READ",   "Read the files",   (p) => buildReadBody(p))
+ *     .subStep("PATHS", "Resolve paths",  (p) => buildPathsBody(p))
+ *     .step("EXTRACT", "Extract items",   (p) => buildExtractBody(p))
+ *     .subStep("TRACE", "Trace callers",  (p) => buildTraceBody(p),
+ *       { when: (p) => p.hasUnmatched, whenDesc: "unmatched backend files present" })
+ *     .step("CALL",   "Call the tool",    (p) => buildCallBody(p))
+ *     .done();
+ *
+ *   // Static constants for non-conditional steps (safe to export at module level)
+ *   export const STEP_READ    = _plan.labels.READ;    // "1"
+ *   export const STEP_PATHS   = _plan.labels.PATHS;   // "1.1"
+ *   export const STEP_EXTRACT = _plan.labels.EXTRACT; // "2"
+ *   export const STEP_CALL    = _plan.labels.CALL;    // "3"
+ *
+ *   // Dynamic accessor for the conditional sub-step
+ *   export const getStepTrace = (p: MyParams) => _plan.labelFor("TRACE", p); // "2.1" | null
+ *
+ *   // Render for the LLM
+ *   const promptText = _plan.render(params);
+ *
+ *   // Developer review
+ *   console.log(_plan.preview(params));
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+export class PhaseBuilder {
+    _plan;
+    _phase;
+    _lastStep = null;
+    constructor(plan, phase) {
+        this._plan = plan;
+        this._phase = phase;
+    }
+    /**
+     * Add a non-conditional main step.
+     * Main steps always appear in the rendered output and always carry a stable
+     * label (1, 2, 3, …) regardless of which sub-steps are active.
+     */
+    step(key, title, body) {
+        this._plan._registerKey(key);
+        const def = { key, title, body, subSteps: [] };
+        this._phase.steps.push(def);
+        this._lastStep = def;
+        return this;
+    }
+    /**
+     * Add a sub-step under the most recently declared main step.
+     * Sub-steps are sequentially numbered within their parent (1.1, 1.2, …).
+     *
+     * When opts.when is provided the sub-step is conditional: if the condition
+     * returns false for the given params, the step is omitted and remaining
+     * siblings re-number so the LLM never sees a gap.
+     *
+     * @throws when called before any step() in this phase.
+     */
+    subStep(key, title, body, opts) {
+        if (!this._lastStep) {
+            throw new Error(`subStep("${key}") must follow a step() call in the same phase`);
+        }
+        this._plan._registerKey(key);
+        this._lastStep.subSteps.push({
+            key,
+            title,
+            body,
+            condition: opts?.when,
+            conditionDesc: opts?.whenDesc,
+        });
+        return this;
+    }
+    /** Finish building this phase and return the parent PromptPlan. */
+    done() {
+        return this._plan;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+export class PromptPlan {
+    _phases = [];
+    _startFrom;
+    /** Track registered step/sub-step keys for duplicate detection. */
+    _registeredKeys = new Set();
+    /**
+     * @param opts.startFrom - Label of the first main step. Defaults to 1.
+     *   Use 0 for execution-plan style (Step 0, Step 1, Step 2, …).
+     */
+    constructor(opts) {
+        this._startFrom = opts?.startFrom ?? 1;
+    }
+    /** @internal Register a key and throw if already taken. */
+    _registerKey(key) {
+        if (this._registeredKeys.has(key)) {
+            throw new Error(`PromptPlan: duplicate step key "${key}"`);
+        }
+        this._registeredKeys.add(key);
+    }
+    /**
+     * Add a phase and return a PhaseBuilder to register its steps.
+     * Multiple phases share a single global main-step counter, so step labels
+     * increment continuously across phase boundaries.
+     */
+    addPhase(key, title, opts) {
+        const phase = {
+            key,
+            title,
+            headerLevel: opts?.headerLevel ?? "hidden",
+            stepFormat: opts?.stepFormat ?? "hash",
+            steps: [],
+        };
+        this._phases.push(phase);
+        return new PhaseBuilder(this, phase);
+    }
+    /**
+     * Static label map for all non-conditional steps (main steps and
+     * unconditional sub-steps). Conditional sub-steps are not present here —
+     * use labelFor() for those.
+     *
+     * Safe to export as module-level constants for use in tests.
+     *
+     * **Ordering constraint**: unconditional sub-steps that appear *after* a
+     * conditional sibling will have a stable label here only if no conditional
+     * siblings precede them. When a conditional sibling is active at runtime,
+     * labelFor() will assign a higher number than the static label here. To
+     * avoid this mismatch, place conditional sub-steps AFTER all unconditional
+     * siblings, or use labelFor() for any sub-step with a conditional predecessor.
+     *
+     * O(steps) per call — intentionally avoids a stale-cache window during plan
+     * construction. Plans have ~6 steps so the cost is negligible; exported
+     * constants are evaluated once at module-load time.
+     */
+    get labels() {
+        const map = {};
+        let mainIdx = this._startFrom - 1;
+        for (const phase of this._phases) {
+            for (const step of phase.steps) {
+                mainIdx++;
+                map[step.key] = String(mainIdx);
+                let subIdx = 0;
+                for (const sub of step.subSteps) {
+                    if (!sub.condition) {
+                        subIdx++;
+                        map[sub.key] = `${mainIdx}.${subIdx}`;
+                    }
+                }
+            }
+        }
+        return map;
+    }
+    /**
+     * Dynamic label for any registered step given runtime params.
+     *
+     * Returns null when the step has a condition that evaluates to false.
+     * Throws when key is not registered in this plan.
+     *
+     * For non-conditional steps the result equals labels[key], but using
+     * labels is preferred for those since it avoids passing params.
+     */
+    labelFor(key, params) {
+        let mainIdx = this._startFrom - 1;
+        for (const phase of this._phases) {
+            for (const step of phase.steps) {
+                mainIdx++;
+                if (step.key === key)
+                    return String(mainIdx);
+                let subIdx = 0;
+                for (const sub of step.subSteps) {
+                    const active = !sub.condition || sub.condition(params);
+                    if (active)
+                        subIdx++;
+                    if (sub.key === key) {
+                        return active ? `${mainIdx}.${subIdx}` : null;
+                    }
+                }
+            }
+        }
+        throw new Error(`PromptPlan: unknown step key "${key}"`);
+    }
+    /**
+     * Render the full prompt for the given params.
+     *
+     * - Phase headers are emitted when headerLevel is not "hidden".
+     * - Steps are formatted per the phase's stepFormat.
+     * - Conditional sub-steps absent for these params are skipped; remaining
+     *   siblings re-number with no gaps.
+     * - Each section (header + body) is separated by a single blank line.
+     */
+    render(params) {
+        const sections = [];
+        let mainIdx = this._startFrom - 1;
+        for (const phase of this._phases) {
+            if (phase.headerLevel !== "hidden") {
+                sections.push(`${phase.headerLevel} ${phase.title}`);
+            }
+            for (const step of phase.steps) {
+                mainIdx++;
+                const label = String(mainIdx);
+                const title = resolveTitle(step.title, params);
+                const body = step.body(params);
+                sections.push(`${renderStepHeader(phase.stepFormat, label, title)}\n${body.trimEnd()}`);
+                let subIdx = 0;
+                for (const sub of step.subSteps) {
+                    if (sub.condition && !sub.condition(params))
+                        continue;
+                    subIdx++;
+                    const subLabel = `${label}.${subIdx}`;
+                    const subTitle = resolveTitle(sub.title, params);
+                    const subBody = sub.body(params);
+                    sections.push(`${renderStepHeader(phase.stepFormat, subLabel, subTitle)}\n${subBody.trimEnd()}`);
+                }
+            }
+        }
+        return sections.join("\n\n");
+    }
+    /**
+     * Return a structured preview of all steps and their active state for the
+     * given params. Useful in development, tests, and debugging to verify exactly
+     * which steps would be emitted and what labels they carry.
+     *
+     * @example
+     *   const pv = _plan.preview({ ...params, unmatchedFiles: [] });
+     *   // pv.phases[0].steps[1].subSteps[0] =>
+     *   //   { key: "TRACE_CALLERS", label: "2.?", active: false,
+     *   //     conditionDesc: "non-frontend unmatched backend files present" }
+     */
+    preview(params) {
+        let mainIdx = this._startFrom - 1;
+        let activeCount = 0;
+        let totalCount = 0;
+        const phases = this._phases.map((phase) => ({
+            key: phase.key,
+            title: phase.title,
+            steps: phase.steps.map((step) => {
+                mainIdx++;
+                activeCount++;
+                totalCount++;
+                const label = String(mainIdx);
+                let subIdx = 0;
+                const subSteps = step.subSteps.map((sub) => {
+                    const active = !sub.condition || sub.condition(params);
+                    totalCount++;
+                    if (active) {
+                        subIdx++;
+                        activeCount++;
+                    }
+                    return {
+                        key: sub.key,
+                        label: active ? `${label}.${subIdx}` : `${label}.?`,
+                        title: resolveTitle(sub.title, params),
+                        active,
+                        ...(sub.conditionDesc !== undefined
+                            ? { conditionDesc: sub.conditionDesc }
+                            : {}),
+                    };
+                });
+                return {
+                    key: step.key,
+                    label,
+                    title: resolveTitle(step.title, params),
+                    subSteps,
+                };
+            }),
+        }));
+        return { phases, activeStepCount: activeCount, totalStepCount: totalCount };
+    }
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+function resolveTitle(title, params) {
+    return typeof title === "function" ? title(params) : title;
+}
+function renderStepHeader(format, label, title) {
+    return format === "bold"
+        ? `**Step ${label} — ${title}**`
+        : `### Step ${label}: ${title}`;
+}

package/build/prompts/test-recommendation/promptPlan.test.js

@@ -0,0 +1,336 @@
+import { PromptPlan } from "./promptPlan.js";
+// ---------------------------------------------------------------------------
+// Core numbering invariants
+// ---------------------------------------------------------------------------
+describe("PromptPlan — main step numbering", () => {
+    it("generates sequential main-step labels starting at 1", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("A", "Step A", () => "body-a")
+            .step("B", "Step B", () => "body-b")
+            .step("C", "Step C", () => "body-c")
+            .done();
+        expect(plan.labels.A).toBe("1");
+        expect(plan.labels.B).toBe("2");
+        expect(plan.labels.C).toBe("3");
+    });
+    it("supports startFrom: 0 for execution-plan style (Step 0, Step 1, …)", () => {
+        const plan = new PromptPlan({ startFrom: 0 })
+            .addPhase("p", "Phase")
+            .step("COVERAGE", "Coverage", () => "")
+            .step("ENRICH", "Enrich", () => "")
+            .step("DIVERSITY", "Diversity", () => "")
+            .step("EXECUTE", "Execute", () => "")
+            .done();
+        expect(plan.labels.COVERAGE).toBe("0");
+        expect(plan.labels.ENRICH).toBe("1");
+        expect(plan.labels.DIVERSITY).toBe("2");
+        expect(plan.labels.EXECUTE).toBe("3");
+    });
+    it("main step labels are compile-time stable — identical to labelFor() with any params", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("X", "X", () => "")
+            .step("Y", "Y", () => "")
+            .done();
+        const params = { flag: true };
+        expect(plan.labels.X).toBe(plan.labelFor("X", params));
+        expect(plan.labels.Y).toBe(plan.labelFor("Y", params));
+    });
+    it("auto-renumbers when a step is inserted — key contract of the abstraction", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("FIRST", "First", () => "")
+            .step("NEW", "Newly inserted", () => "") // inserted before what was "2"
+            .step("SECOND", "Second", () => "")
+            .done();
+        expect(plan.labels.FIRST).toBe("1");
+        expect(plan.labels.NEW).toBe("2");
+        expect(plan.labels.SECOND).toBe("3"); // auto-renumbered from "2" to "3"
+    });
+});
+// ---------------------------------------------------------------------------
+// Sub-step numbering
+// ---------------------------------------------------------------------------
+describe("PromptPlan — sub-step numbering", () => {
+    it("assigns sequential sub-step labels within their parent (1.1, 1.2, 2.1, …)", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("READ", "Read", () => "")
+            .subStep("PATHS", "Paths", () => "")
+            .step("EXTRACT", "Extract", () => "")
+            .subStep("TRACE", "Trace", () => "", { when: (p) => p.flag })
+            .done();
+        expect(plan.labels.READ).toBe("1");
+        expect(plan.labels.PATHS).toBe("1.1");
+        expect(plan.labels.EXTRACT).toBe("2");
+        // TRACE is conditional — NOT in labels map
+        expect(plan.labels.TRACE).toBeUndefined();
+    });
+    it("sub() does not advance the main counter", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("A", "A", () => "")
+            .subStep("A1", "A1", () => "")
+            .subStep("A2", "A2", () => "")
+            .step("B", "B", () => "")
+            .done();
+        expect(plan.labels.A).toBe("1");
+        expect(plan.labels.A1).toBe("1.1");
+        expect(plan.labels.A2).toBe("1.2");
+        expect(plan.labels.B).toBe("2");
+    });
+    it("conditional sub-step is absent from static labels map", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("A", "A", () => "")
+            .subStep("COND", "Conditional", () => "", { when: (p) => p.flag })
+            .done();
+        expect(plan.labels.A).toBe("1");
+        expect(plan.labels.COND).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// labelFor() — dynamic labels
+// ---------------------------------------------------------------------------
+describe("PromptPlan — labelFor()", () => {
+    const plan = new PromptPlan()
+        .addPhase("p", "Phase")
+        .step("READ", "Read", () => "")
+        .subStep("PATHS", "Paths", () => "")
+        .step("EXTRACT", "Extract", () => "")
+        .subStep("TRACE", "Trace", () => "", { when: (p) => p.flag })
+        .step("DRAFT", "Draft", () => "")
+        .done();
+    it("returns the static label for always-present main steps", () => {
+        const p = { flag: true };
+        expect(plan.labelFor("READ", p)).toBe("1");
+        expect(plan.labelFor("EXTRACT", p)).toBe("2");
+        expect(plan.labelFor("DRAFT", p)).toBe("3");
+    });
+    it("returns the static label for always-present sub-steps", () => {
+        expect(plan.labelFor("PATHS", { flag: false })).toBe("1.1");
+    });
+    it("returns '2.1' for the conditional sub-step when condition is true", () => {
+        expect(plan.labelFor("TRACE", { flag: true })).toBe("2.1");
+    });
+    it("returns null for the conditional sub-step when condition is false", () => {
+        expect(plan.labelFor("TRACE", { flag: false })).toBeNull();
+    });
+    it("throws for an unknown key", () => {
+        expect(() => plan.labelFor("UNKNOWN", { flag: true })).toThrow('PromptPlan: unknown step key "UNKNOWN"');
+    });
+});
+// ---------------------------------------------------------------------------
+// Conditional sub-step: re-numbering when sibling is absent
+// ---------------------------------------------------------------------------
+describe("PromptPlan — conditional sub-step re-numbering", () => {
+    const plan = new PromptPlan()
+        .addPhase("p", "Phase")
+        .step("A", "A", () => "")
+        .subStep("A_COND", "Conditional A", () => "", { when: (p) => p.flag })
+        .subStep("A_ALWAYS", "Always present", () => "always")
+        .done();
+    it("when condition is true, A_COND=1.1 and A_ALWAYS=1.2", () => {
+        expect(plan.labelFor("A_COND", { flag: true })).toBe("1.1");
+        expect(plan.labelFor("A_ALWAYS", { flag: true })).toBe("1.2");
+    });
+    it("when condition is false, A_COND=null and A_ALWAYS re-numbers to 1.1", () => {
+        expect(plan.labelFor("A_COND", { flag: false })).toBeNull();
+        expect(plan.labelFor("A_ALWAYS", { flag: false })).toBe("1.1");
+    });
+});
+// ---------------------------------------------------------------------------
+// render() — output format
+// ---------------------------------------------------------------------------
+describe("PromptPlan — render()", () => {
+    it("emits ### Step N: Title headers for hash format", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase", { stepFormat: "hash" })
+            .step("A", "Do something", () => "body text")
+            .done();
+        const output = plan.render({ flag: true });
+        expect(output).toContain("### Step 1: Do something");
+        expect(output).toContain("body text");
+    });
+    it("emits **Step N — Title** headers for bold format", () => {
+        const plan = new PromptPlan({ startFrom: 0 })
+            .addPhase("p", "Phase", { stepFormat: "bold" })
+            .step("A", "Coverage", () => "coverage body")
+            .done();
+        const output = plan.render({ flag: true });
+        expect(output).toContain("**Step 0 — Coverage**");
+        expect(output).toContain("coverage body");
+    });
+    it("emits the phase header when headerLevel is not hidden", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "My Phase Title", { headerLevel: "##" })
+            .step("A", "Step A", () => "")
+            .done();
+        expect(plan.render({ flag: true })).toContain("## My Phase Title");
+    });
+    it("does NOT emit a phase header when headerLevel is hidden", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Hidden Phase", { headerLevel: "hidden" })
+            .step("A", "Step A", () => "")
+            .done();
+        expect(plan.render({ flag: true })).not.toContain("Hidden Phase");
+    });
+    it("omits a conditional sub-step when condition is false", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("A", "A", () => "step-a-body")
+            .subStep("COND", "Conditional", () => "cond-body", { when: (p) => p.flag })
+            .done();
+        const withFlag = plan.render({ flag: true });
+        const withoutFlag = plan.render({ flag: false });
+        expect(withFlag).toContain("cond-body");
+        expect(withoutFlag).not.toContain("cond-body");
+        expect(withoutFlag).not.toContain("Conditional");
+    });
+    it("re-numbers remaining sub-steps when a conditional one is absent", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("A", "A", () => "")
+            .subStep("COND", "Conditional", () => "cond", { when: (p) => p.flag })
+            .subStep("ALWAYS", "Always", () => "always")
+            .done();
+        // With flag: 1.1 = Conditional, 1.2 = Always
+        expect(plan.render({ flag: true })).toContain("### Step 1.1: Conditional");
+        expect(plan.render({ flag: true })).toContain("### Step 1.2: Always");
+        // Without flag: conditional absent, Always re-numbers to 1.1
+        expect(plan.render({ flag: false })).not.toContain("Conditional");
+        expect(plan.render({ flag: false })).toContain("### Step 1.1: Always");
+    });
+    it("supports dynamic step titles via title functions", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase")
+            .step("A", (p) => p.flag ? "Flag is on" : "Flag is off", () => "body")
+            .done();
+        expect(plan.render({ flag: true })).toContain("### Step 1: Flag is on");
+        expect(plan.render({ flag: false })).toContain("### Step 1: Flag is off");
+    });
+    it("sections are separated by exactly one blank line", () => {
+        const plan = new PromptPlan()
+            .addPhase("p", "Phase", { headerLevel: "##" })
+            .step("A", "Step A", () => "body-a")
+            .step("B", "Step B", () => "body-b")
+            .done();
+        const output = plan.render({ flag: true });
+        // Each pair of sections should have \n\n (exactly one blank line) between them
+        expect(output).toContain("## Phase\n\n### Step 1");
+        expect(output).toContain("body-a\n\n### Step 2");
+    });
+    it("reproduces the analysis-output step sequence", () => {
+        const plan = new PromptPlan()
+            .addPhase("analysis", "Your Task", { headerLevel: "##", stepFormat: "hash" })
+            .step("READ", "Read the changed files", () => "read body")
+            .subStep("PATHS", "Resolve endpoint paths", () => "paths body")
+            .step("EXTRACT", "Extract endpoints", () => "extract body")
+            .subStep("TRACE", "Trace callers", () => "trace body", { when: (p) => p.flag })
+            .step("DRAFT", "Draft scenarios", () => "draft body")
+            .step("CALL", "Call the tool", () => "call body")
+            .done();
+        expect(plan.labels.READ).toBe("1");
+        expect(plan.labels.PATHS).toBe("1.1");
+        expect(plan.labels.EXTRACT).toBe("2");
+        expect(plan.labels.DRAFT).toBe("3");
+        expect(plan.labels.CALL).toBe("4");
+        // With flag: trace appears as 2.1
+        const withTrace = plan.render({ flag: true });
+        expect(withTrace).toContain("### Step 1: Read the changed files");
+        expect(withTrace).toContain("### Step 1.1: Resolve endpoint paths");
+        expect(withTrace).toContain("### Step 2: Extract endpoints");
+        expect(withTrace).toContain("### Step 2.1: Trace callers");
+        expect(withTrace).toContain("### Step 3: Draft scenarios");
+        expect(withTrace).toContain("### Step 4: Call the tool");
+        // Without flag: no trace step, sequence has no gap
+        const noTrace = plan.render({ flag: false });
+        expect(noTrace).not.toContain("trace body");
+        expect(noTrace).not.toContain("Step 2.1");
+        expect(noTrace).toContain("### Step 3: Draft scenarios");
+    });
+});
+// ---------------------------------------------------------------------------
+// preview() — developer review
+// ---------------------------------------------------------------------------
+describe("PromptPlan — preview()", () => {
+    const plan = new PromptPlan()
+        .addPhase("analysis", "Analysis Phase", { headerLevel: "##" })
+        .step("READ", "Read", () => "")
+        .subStep("PATHS", "Paths", () => "")
+        .step("EXTRACT", "Extract", () => "")
+        .subStep("TRACE", "Trace", () => "", {
+        when: (p) => p.flag,
+        whenDesc: "backend unmatched files present",
+    })
+        .step("DRAFT", "Draft", () => "")
+        .done();
+    it("reports correct activeStepCount and totalStepCount", () => {
+        const withFlag = plan.preview({ flag: true });
+        const withoutFlag = plan.preview({ flag: false });
+        expect(withFlag.totalStepCount).toBe(5); // 3 main + 2 subs = 5
+        expect(withFlag.activeStepCount).toBe(5); // all active
+        expect(withoutFlag.totalStepCount).toBe(5);
+        expect(withoutFlag.activeStepCount).toBe(4); // TRACE absent
+    });
+    it("marks the conditional sub-step inactive when condition is false", () => {
+        const pv = plan.preview({ flag: false });
+        const extractStep = pv.phases[0].steps.find(s => s.key === "EXTRACT");
+        const traceSub = extractStep.subSteps.find(s => s.key === "TRACE");
+        expect(traceSub.active).toBe(false);
+        expect(traceSub.label).toBe("2.?");
+        expect(traceSub.conditionDesc).toBe("backend unmatched files present");
+    });
+    it("marks the conditional sub-step active with correct label when condition is true", () => {
+        const pv = plan.preview({ flag: true });
+        const extractStep = pv.phases[0].steps.find(s => s.key === "EXTRACT");
+        const traceSub = extractStep.subSteps.find(s => s.key === "TRACE");
+        expect(traceSub.active).toBe(true);
+        expect(traceSub.label).toBe("2.1");
+    });
+    it("includes all phase / step keys in the preview output", () => {
+        const pv = plan.preview({ flag: true });
+        expect(pv.phases).toHaveLength(1);
+        expect(pv.phases[0].key).toBe("analysis");
+        const stepKeys = pv.phases[0].steps.map(s => s.key);
+        expect(stepKeys).toEqual(["READ", "EXTRACT", "DRAFT"]);
+    });
+});
+// ---------------------------------------------------------------------------
+// PhaseBuilder guard
+// ---------------------------------------------------------------------------
+describe("PhaseBuilder — error handling", () => {
+    it("throws when subStep() is called before any step()", () => {
+        expect(() => {
+            new PromptPlan()
+                .addPhase("p", "Phase")
+                .subStep("ORPHAN", "Orphan", () => "");
+        }).toThrow('subStep("ORPHAN") must follow a step() call in the same phase');
+    });
+    it("throws on duplicate step keys", () => {
+        expect(() => {
+            new PromptPlan()
+                .addPhase("p", "Phase")
+                .step("DUP", "First", () => "")
+                .step("DUP", "Second", () => "");
+        }).toThrow('PromptPlan: duplicate step key "DUP"');
+    });
+    it("throws on duplicate sub-step keys", () => {
+        expect(() => {
+            new PromptPlan()
+                .addPhase("p", "Phase")
+                .step("A", "A", () => "")
+                .subStep("DUP", "First sub", () => "")
+                .subStep("DUP", "Second sub", () => "");
+        }).toThrow('PromptPlan: duplicate step key "DUP"');
+    });
+    it("throws when a sub-step key conflicts with a main step key", () => {
+        expect(() => {
+            new PromptPlan()
+                .addPhase("p", "Phase")
+                .step("SHARED", "Main", () => "")
+                .subStep("SHARED", "Sub", () => "");
+        }).toThrow('PromptPlan: duplicate step key "SHARED"');
+    });
+});

package/build/prompts/test-recommendation/recommendationSections.js

@@ -172,7 +172,7 @@ When no Playwright trace exists, use the Playwright browser tools (\`browser_nav
 `}
 `;
 }
-export function buildVerificationChecklist(topN, maxGen) {
+export function buildVerificationChecklist(topN, maxGen, codeReviewStepLabel = "0") {
     const minTotal = Math.min(maxGen + 1, topN);
     return `<verification>
 Before finalizing your output, verify:
@@ -186,6 +186,8 @@ Before finalizing your output, verify:
 8. **bugCatchingTarget**: Every GENERATE integration test that targets a business rule, formula, or constraint has a non-empty \`bugCatchingTarget\`.
 9. **FK chaining**: In multi-step integration tests, path params sourced from a prior step's response (e.g. \`order_id\` from step 1) use \`chainsFrom\` — not hardcoded IDs.
 10. **Concrete scenario names**: No GENERATE item uses a placeholder name ending in a numeric suffix (e.g. \`ui-test-for-changed-component-1\`, \`ui-test-from-trace-2\`). Derive the name from the actual changed component or flow: if the diff touches \`LinkCard.tsx\`, the scenario name should be \`link-card-pin-toggle\` or \`link-card-edit-description\`, not \`ui-test-for-changed-component-1\`. The changed file list is available above — use it.
+11. **Issue coverage**: If \`<bug_found>\` blocks exist from Step ${codeReviewStepLabel} (Code Review), verify that the highest-severity flaw (HIGH or CRITICAL) has at least one GENERATE item directly targeting it (its pass/fail outcome depends on whether that bug exists). At most one promotion per run. If the promoted flaw lacks a dedicated GENERATE item, promote or create one before proceeding. Additional HIGH/CRITICAL flaws beyond the first should appear in ADDITIONAL at highest priority.
+12. **Code Review completeness**: Did you produce a \`<function_review>\` block for EVERY changed function/handler in Step ${codeReviewStepLabel}? If any function is missing a review, you skipped the correctness analysis for it. Go back and complete it before finalizing.
 </verification>`;
 }
 export function buildFewShotExamples() {
@@ -317,8 +319,7 @@ ${authGuidance}
    **OpenAPI spec is NOT required.** \`apiSchema\` is OPTIONAL — omit it if no spec exists.
    **CRITICAL — Query params vs request body:**
    - For **POST/PUT/PATCH**: use \`requestBody\` with realistic field values from source code schemas.
-   - For **GET/DELETE with search/filter/pagination**: use \`queryParams\` (JSON string, e.g., \`{"q": "bear", "limit": 10}\`).
-     Do not put query parameters in \`requestBody\` for GET requests — GET request bodies are non-standard and may be ignored or rejected.
+   - For **GET/DELETE with search/filter/pagination**: use \`queryParams\`. Do not put query parameters in \`requestBody\` for GET requests — GET request bodies are non-standard and may be ignored or rejected.
    - For **GET by ID**: no \`requestBody\` or \`queryParams\` needed — the ID is in the path.
    \`responseBody\` should match the actual API response shape from source code (including all fields
    returned by the controller — e.g., \`id\`, \`ownerId\`, \`createdAt\`, included relations like \`collection\`, \`tags\`).