planpong 0.3.0 → 0.5.0

package/dist/src/schemas/json-schema.js

@@ -0,0 +1,172 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { DirectionFeedbackSchema, RiskFeedbackSchema, ReviewFeedbackSchema, } from "./feedback.js";
+import { PlannerRevisionSchema, DirectionRevisionSchema, EditsRevisionSchema, } from "./revision.js";
+/**
+ * JSON Schemas generated from Zod schemas, used for constrained model output
+ * via `claude --json-schema` and `codex --output-schema`.
+ *
+ * KNOWN LIMITATION: Zod refinements (e.g., the `approved_with_notes` severity
+ * constraint on ReviewFeedbackSchema) and transforms do NOT round-trip to
+ * JSON Schema. The generated JSON Schema enforces structural validity only.
+ * Semantic rules are validated post-parse by Zod in convergence.ts.
+ *
+ * Schemas are generated once at module load and cached as constants.
+ */
+/**
+ * Internal observability fields on feedback schemas — set by the parser
+ * after the model responds. These must NOT appear in the schema sent to
+ * the model, since the model doesn't produce them.
+ */
+const OBSERVABILITY_FIELDS = new Set([
+    "fallback_used",
+    "missing_phase_fields",
+]);
+function stripObservabilityFields(node) {
+    if (Array.isArray(node))
+        return node.map(stripObservabilityFields);
+    if (node && typeof node === "object") {
+        const obj = node;
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === "properties" && value && typeof value === "object") {
+                const props = value;
+                const filtered = {};
+                for (const [propKey, propValue] of Object.entries(props)) {
+                    if (!OBSERVABILITY_FIELDS.has(propKey)) {
+                        filtered[propKey] = stripObservabilityFields(propValue);
+                    }
+                }
+                result[key] = filtered;
+            }
+            else if (key === "required" && Array.isArray(value)) {
+                result[key] = value.filter((k) => typeof k !== "string" || !OBSERVABILITY_FIELDS.has(k));
+            }
+            else {
+                result[key] = stripObservabilityFields(value);
+            }
+        }
+        return result;
+    }
+    return node;
+}
+/**
+ * Transform a JSON Schema to the OpenAI-strict dialect required by Codex
+ * (and most OpenAI-compatible providers) for structured output:
+ *
+ * - Every `object` node must have `additionalProperties: false`
+ * - Every property must appear in `required`
+ * - Optional properties are expressed as nullable (type union with "null")
+ *
+ * Input: a JSON Schema 7 document generated from Zod (with optional fields
+ * missing from `required`).
+ * Output: an OpenAI-strict JSON Schema that is accepted by strict mode and
+ * still structurally compatible with the original Zod validation.
+ *
+ * Anthropic's validator accepts the stricter form, so we apply this
+ * transformation universally rather than per-provider.
+ */
+function toOpenAIStrict(node) {
+    if (Array.isArray(node))
+        return node.map(toOpenAIStrict);
+    if (!node || typeof node !== "object")
+        return node;
+    const obj = node;
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = toOpenAIStrict(value);
+    }
+    // Only transform object nodes that have properties
+    if (result.type !== "object" ||
+        !result.properties ||
+        typeof result.properties !== "object") {
+        return result;
+    }
+    const properties = result.properties;
+    const originalRequired = new Set(Array.isArray(result.required) ? result.required : []);
+    const allKeys = Object.keys(properties);
+    // Every property must be in `required`
+    result.required = allKeys;
+    // Previously optional fields → mark as nullable
+    for (const propKey of allKeys) {
+        if (!originalRequired.has(propKey)) {
+            properties[propKey] = makeNullable(properties[propKey]);
+        }
+    }
+    // Every object needs `additionalProperties: false`
+    if (result.additionalProperties === undefined) {
+        result.additionalProperties = false;
+    }
+    return result;
+}
+/**
+ * Make a JSON Schema node accept null in addition to its existing type.
+ * - Simple type: `{ type: "string" }` → `{ type: ["string", "null"] }`
+ * - Enum: `{ type: "string", enum: [...] }` → `{ type: ["string", "null"], enum: [..., null] }`
+ * - Union types: append "null" if not present
+ * - Other constructs: wrap in `anyOf` with null
+ */
+function makeNullable(node) {
+    if (!node || typeof node !== "object")
+        return node;
+    const obj = { ...node };
+    const existingType = obj.type;
+    if (typeof existingType === "string") {
+        obj.type = [existingType, "null"];
+    }
+    else if (Array.isArray(existingType)) {
+        if (!existingType.includes("null")) {
+            obj.type = [...existingType, "null"];
+        }
+    }
+    else {
+        // No concrete type (e.g., anyOf/oneOf) — wrap in anyOf
+        return { anyOf: [node, { type: "null" }] };
+    }
+    // If the node has an enum, also add null as a valid enum value
+    if (Array.isArray(obj.enum) && !obj.enum.includes(null)) {
+        obj.enum = [...obj.enum, null];
+    }
+    return obj;
+}
+function generate(schema) {
+    const raw = zodToJsonSchema(schema, {
+        target: "jsonSchema7",
+        $refStrategy: "none",
+    });
+    const stripped = stripObservabilityFields(raw);
+    return toOpenAIStrict(stripped);
+}
+export const DirectionFeedbackJsonSchema = generate(DirectionFeedbackSchema);
+export const RiskFeedbackJsonSchema = generate(RiskFeedbackSchema);
+export const ReviewFeedbackJsonSchema = generate(ReviewFeedbackSchema);
+export const PlannerRevisionJsonSchema = generate(PlannerRevisionSchema);
+const DirectionRevisionJsonSchema = generate(DirectionRevisionSchema);
+const EditsRevisionJsonSchema = generate(EditsRevisionSchema);
+/**
+ * Get the JSON Schema appropriate for a given review phase.
+ */
+export function getFeedbackJsonSchemaForPhase(phase) {
+    if (phase === "direction")
+        return DirectionFeedbackJsonSchema;
+    if (phase === "risk")
+        return RiskFeedbackJsonSchema;
+    return ReviewFeedbackJsonSchema;
+}
+/**
+ * Get the JSON Schema for a planner revision response, selecting the
+ * shape based on phase and the configured revision mode.
+ *
+ * - Direction phase always emits `updated_plan` (sweeping rewrites are
+ *   allowed in round 1).
+ * - Risk + detail phase with `revisionMode: "edits"` emits an `edits[]`
+ *   array — the planner cannot fall back to full output.
+ * - Risk + detail phase with `revisionMode: "full"` keeps the full-plan
+ *   shape (kill switch).
+ */
+export function getRevisionJsonSchema(phase, revisionMode) {
+    if (phase === "direction" || revisionMode === "full") {
+        return DirectionRevisionJsonSchema;
+    }
+    return EditsRevisionJsonSchema;
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/src/schemas/json-schema.js.map

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

package/dist/src/schemas/metrics.d.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+export declare const InvocationAttemptSchema: z.ZodObject<{
+    mode: z.ZodEnum<["structured", "legacy"]>;
+    provider: z.ZodString;
+    model: z.ZodNullable<z.ZodString>;
+    effort: z.ZodNullable<z.ZodString>;
+    prompt_chars: z.ZodNumber;
+    prompt_lines: z.ZodNumber;
+    output_chars: z.ZodNullable<z.ZodNumber>;
+    output_lines: z.ZodNullable<z.ZodNumber>;
+    duration_ms: z.ZodNumber;
+    ok: z.ZodBoolean;
+    error_kind: z.ZodNullable<z.ZodEnum<["capability", "fatal", "parse", "zod", "edit-retry"]>>;
+    error_exit_code: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    provider: string;
+    model: string | null;
+    effort: string | null;
+    ok: boolean;
+    mode: "structured" | "legacy";
+    prompt_chars: number;
+    prompt_lines: number;
+    output_chars: number | null;
+    output_lines: number | null;
+    duration_ms: number;
+    error_kind: "capability" | "fatal" | "parse" | "zod" | "edit-retry" | null;
+    error_exit_code: number | null;
+}, {
+    provider: string;
+    model: string | null;
+    effort: string | null;
+    ok: boolean;
+    mode: "structured" | "legacy";
+    prompt_chars: number;
+    prompt_lines: number;
+    output_chars: number | null;
+    output_lines: number | null;
+    duration_ms: number;
+    error_kind: "capability" | "fatal" | "parse" | "zod" | "edit-retry" | null;
+    error_exit_code: number | null;
+}>;
+export declare const RoundMetricsSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    session_id: z.ZodString;
+    round: z.ZodNumber;
+    phase: z.ZodEnum<["direction", "risk", "detail"]>;
+    role: z.ZodEnum<["review", "revision"]>;
+    started_at: z.ZodString;
+    completed_at: z.ZodString;
+    total_duration_ms: z.ZodNumber;
+    attempts: z.ZodArray<z.ZodObject<{
+        mode: z.ZodEnum<["structured", "legacy"]>;
+        provider: z.ZodString;
+        model: z.ZodNullable<z.ZodString>;
+        effort: z.ZodNullable<z.ZodString>;
+        prompt_chars: z.ZodNumber;
+        prompt_lines: z.ZodNumber;
+        output_chars: z.ZodNullable<z.ZodNumber>;
+        output_lines: z.ZodNullable<z.ZodNumber>;
+        duration_ms: z.ZodNumber;
+        ok: z.ZodBoolean;
+        error_kind: z.ZodNullable<z.ZodEnum<["capability", "fatal", "parse", "zod", "edit-retry"]>>;
+        error_exit_code: z.ZodNullable<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        model: string | null;
+        effort: string | null;
+        ok: boolean;
+        mode: "structured" | "legacy";
+        prompt_chars: number;
+        prompt_lines: number;
+        output_chars: number | null;
+        output_lines: number | null;
+        duration_ms: number;
+        error_kind: "capability" | "fatal" | "parse" | "zod" | "edit-retry" | null;
+        error_exit_code: number | null;
+    }, {
+        provider: string;
+        model: string | null;
+        effort: string | null;
+        ok: boolean;
+        mode: "structured" | "legacy";
+        prompt_chars: number;
+        prompt_lines: number;
+        output_chars: number | null;
+        output_lines: number | null;
+        duration_ms: number;
+        error_kind: "capability" | "fatal" | "parse" | "zod" | "edit-retry" | null;
+        error_exit_code: number | null;
+    }>, "many">;
+    revision_mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<["full", "edits"]>>>;
+    edits_attempted: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    edits_applied: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    edits_failed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    edits_retried: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    edits_recovered: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    retry_invoked: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    schema_version: 1;
+    session_id: string;
+    round: number;
+    phase: "direction" | "risk" | "detail";
+    role: "review" | "revision";
+    started_at: string;
+    completed_at: string;
+    total_duration_ms: number;
+    attempts: {
+        provider: string;
+        model: string | null;
+        effort: string | null;
+        ok: boolean;
+        mode: "structured" | "legacy";
+        prompt_chars: number;
+        prompt_lines: number;
+        output_chars: number | null;
+        output_lines: number | null;
+        duration_ms: number;
+        error_kind: "capability" | "fatal" | "parse" | "zod" | "edit-retry" | null;
+        error_exit_code: number | null;
+    }[];
+    revision_mode?: "edits" | "full" | null | undefined;
+    edits_attempted?: number | null | undefined;
+    edits_applied?: number | null | undefined;
+    edits_failed?: number | null | undefined;
+    edits_retried?: number | null | undefined;
+    edits_recovered?: number | null | undefined;
+    retry_invoked?: boolean | null | undefined;
+}, {
+    schema_version: 1;
+    session_id: string;
+    round: number;
+    phase: "direction" | "risk" | "detail";
+    role: "review" | "revision";
+    started_at: string;
+    completed_at: string;
+    total_duration_ms: number;
+    attempts: {
+        provider: string;
+        model: string | null;
+        effort: string | null;
+        ok: boolean;
+        mode: "structured" | "legacy";
+        prompt_chars: number;
+        prompt_lines: number;
+        output_chars: number | null;
+        output_lines: number | null;
+        duration_ms: number;
+        error_kind: "capability" | "fatal" | "parse" | "zod" | "edit-retry" | null;
+        error_exit_code: number | null;
+    }[];
+    revision_mode?: "edits" | "full" | null | undefined;
+    edits_attempted?: number | null | undefined;
+    edits_applied?: number | null | undefined;
+    edits_failed?: number | null | undefined;
+    edits_retried?: number | null | undefined;
+    edits_recovered?: number | null | undefined;
+    retry_invoked?: boolean | null | undefined;
+}>;
+export type InvocationAttempt = z.infer<typeof InvocationAttemptSchema>;
+export type RoundMetrics = z.infer<typeof RoundMetricsSchema>;
+export interface MetricsContext {
+    sessionId: string;
+    round: number;
+    phase: "direction" | "risk" | "detail";
+    role: "review" | "revision";
+}
+export interface TimingSummary {
+    duration_ms: number;
+    attempts: number;
+}
+export declare function summarizeTiming(metrics: RoundMetrics): TimingSummary;

package/dist/src/schemas/metrics.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+export const InvocationAttemptSchema = z.object({
+    mode: z.enum(["structured", "legacy"]),
+    provider: z.string(),
+    model: z.string().nullable(),
+    effort: z.string().nullable(),
+    prompt_chars: z.number().int().nonnegative(),
+    prompt_lines: z.number().int().nonnegative(),
+    output_chars: z.number().int().nonnegative().nullable(),
+    output_lines: z.number().int().nonnegative().nullable(),
+    duration_ms: z.number().int().nonnegative(),
+    ok: z.boolean(),
+    // `edit-retry` marks the targeted retry pass for failed edits in
+    // edits-mode revisions. It is not a state-machine downgrade — the
+    // structured/legacy mode is captured in `mode` independently.
+    error_kind: z
+        .enum(["capability", "fatal", "parse", "zod", "edit-retry"])
+        .nullable(),
+    error_exit_code: z.number().int().nullable(),
+});
+// Edits-mode revision telemetry. Null fields in full-mode revisions and in
+// review rounds. `revision_mode` is the discriminator — when `"full"`, all
+// `edits_*` and `retry_invoked` fields are null; when `"edits"`, they
+// describe the round's edit-application pass.
+export const RoundMetricsSchema = z.object({
+    schema_version: z.literal(1),
+    session_id: z.string(),
+    round: z.number().int().positive(),
+    phase: z.enum(["direction", "risk", "detail"]),
+    role: z.enum(["review", "revision"]),
+    started_at: z.string(),
+    completed_at: z.string(),
+    total_duration_ms: z.number().int().nonnegative(),
+    attempts: z.array(InvocationAttemptSchema),
+    revision_mode: z.enum(["full", "edits"]).nullable().optional(),
+    edits_attempted: z.number().int().nonnegative().nullable().optional(),
+    edits_applied: z.number().int().nonnegative().nullable().optional(),
+    edits_failed: z.number().int().nonnegative().nullable().optional(),
+    edits_retried: z.number().int().nonnegative().nullable().optional(),
+    edits_recovered: z.number().int().nonnegative().nullable().optional(),
+    retry_invoked: z.boolean().nullable().optional(),
+});
+export function summarizeTiming(metrics) {
+    return {
+        duration_ms: metrics.total_duration_ms,
+        attempts: metrics.attempts.length,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/schemas/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/schemas/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACtC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACvD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC3C,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;IACf,iEAAiE;IACjE,kEAAkE;IAClE,8DAA8D;IAC9D,UAAU,EAAE,CAAC;SACV,IAAI,CAAC,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;SAC3D,QAAQ,EAAE;IACb,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAEH,2EAA2E;AAC3E,2EAA2E;AAC3E,sEAAsE;AACtE,8CAA8C;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACjD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAC1C,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC9D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACrE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACnE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAClE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACnE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACrE,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC;AAiBH,MAAM,UAAU,eAAe,CAAC,OAAqB;IACnD,OAAO;QACL,WAAW,EAAE,OAAO,CAAC,iBAAiB;QACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM;KAClC,CAAC;AACJ,CAAC"}

package/dist/src/schemas/revision.d.ts

@@ -48,6 +48,165 @@ export declare const IssueResponseSchema: z.ZodObject<{
         justification: string;
     } | undefined;
 }>;
+export declare const ReplaceEditSchema: z.ZodObject<{
+    section: z.ZodString;
+    before: z.ZodString;
+    after: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    section: string;
+    before: string;
+    after: string;
+}, {
+    section: string;
+    before: string;
+    after: string;
+}>;
+export declare const DirectionRevisionSchema: z.ZodObject<{
+    responses: z.ZodArray<z.ZodObject<{
+        issue_id: z.ZodString;
+        action: z.ZodEnum<["accepted", "rejected", "deferred"]>;
+        severity_dispute: z.ZodOptional<z.ZodObject<{
+            original: z.ZodEnum<["P1", "P2", "P3"]>;
+            revised: z.ZodEnum<["P1", "P2", "P3"]>;
+            justification: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        }, {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        }>>;
+        rationale: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }, {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }>, "many">;
+    updated_plan: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    responses: {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }[];
+    updated_plan: string;
+}, {
+    responses: {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }[];
+    updated_plan: string;
+}>;
+export declare const EditsRevisionSchema: z.ZodObject<{
+    responses: z.ZodArray<z.ZodObject<{
+        issue_id: z.ZodString;
+        action: z.ZodEnum<["accepted", "rejected", "deferred"]>;
+        severity_dispute: z.ZodOptional<z.ZodObject<{
+            original: z.ZodEnum<["P1", "P2", "P3"]>;
+            revised: z.ZodEnum<["P1", "P2", "P3"]>;
+            justification: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        }, {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        }>>;
+        rationale: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }, {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }>, "many">;
+    edits: z.ZodArray<z.ZodObject<{
+        section: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        section: string;
+        before: string;
+        after: string;
+    }, {
+        section: string;
+        before: string;
+        after: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    responses: {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }[];
+    edits: {
+        section: string;
+        before: string;
+        after: string;
+    }[];
+}, {
+    responses: {
+        issue_id: string;
+        action: "accepted" | "rejected" | "deferred";
+        rationale: string;
+        severity_dispute?: {
+            original: "P1" | "P2" | "P3";
+            revised: "P1" | "P2" | "P3";
+            justification: string;
+        } | undefined;
+    }[];
+    edits: {
+        section: string;
+        before: string;
+        after: string;
+    }[];
+}>;
 export declare const PlannerRevisionSchema: z.ZodObject<{
     responses: z.ZodArray<z.ZodObject<{
         issue_id: z.ZodString;
@@ -86,7 +245,7 @@ export declare const PlannerRevisionSchema: z.ZodObject<{
         } | undefined;
     }>, "many">;
     updated_plan: z.ZodString;
-}, "strip", z.ZodTypeAny, {
+}, "strict", z.ZodTypeAny, {
     responses: {
         issue_id: string;
         action: "accepted" | "rejected" | "deferred";
@@ -113,4 +272,9 @@ export declare const PlannerRevisionSchema: z.ZodObject<{
 }>;
 export type SeverityDispute = z.infer<typeof SeverityDisputeSchema>;
 export type IssueResponse = z.infer<typeof IssueResponseSchema>;
-export type PlannerRevision = z.infer<typeof PlannerRevisionSchema>;
+export type ReplaceEdit = z.infer<typeof ReplaceEditSchema>;
+export type DirectionRevision = z.infer<typeof DirectionRevisionSchema>;
+export type EditsRevision = z.infer<typeof EditsRevisionSchema>;
+export type PlannerRevision = DirectionRevision | EditsRevision;
+export declare function isEditsRevision(r: PlannerRevision): r is EditsRevision;
+export declare function isDirectionRevision(r: PlannerRevision): r is DirectionRevision;

package/dist/src/schemas/revision.js

@@ -10,8 +10,41 @@ export const IssueResponseSchema = z.object({
     severity_dispute: SeverityDisputeSchema.optional(),
     rationale: z.string(),
 });
-export const PlannerRevisionSchema = z.object({
+// `before.length <= 2000` and `after.length <= 5000` are hard caps that prevent
+// the planner from "editing" the entire plan in one edit, which defeats the
+// point. Section scoping makes the unique-match constraint mean "unique within
+// section" rather than "unique within plan".
+export const ReplaceEditSchema = z.object({
+    section: z.string().min(1),
+    before: z.string().min(1).max(2000),
+    after: z.string().max(5000),
+});
+// Direction-phase revisions are intentionally allowed to be sweeping rewrites,
+// so they keep the full-plan output shape.
+export const DirectionRevisionSchema = z
+    .object({
     responses: z.array(IssueResponseSchema),
     updated_plan: z.string(),
-});
+})
+    .strict();
+// Risk + detail-phase revisions emit a structured edit list instead. The
+// applier replays edits server-side. No `updated_plan` field — `.strict()`
+// rejects payloads that try to provide one.
+export const EditsRevisionSchema = z
+    .object({
+    responses: z.array(IssueResponseSchema),
+    edits: z.array(ReplaceEditSchema),
+})
+    .strict();
+// Backward-compatible export — equals DirectionRevisionSchema.
+// Kept so existing imports of `PlannerRevisionSchema` (e.g., legacy
+// JSON-Schema generation) continue to compile while the codebase migrates
+// to phase-aware schemas.
+export const PlannerRevisionSchema = DirectionRevisionSchema;
+export function isEditsRevision(r) {
+    return "edits" in r;
+}
+export function isDirectionRevision(r) {
+    return "updated_plan" in r;
+}
 //# sourceMappingURL=revision.js.map

package/dist/src/schemas/revision.js.map

@@ -1 +1 @@
-{"version":3,"file":"revision.js","sourceRoot":"","sources":["../../../src/schemas/revision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;CAC1B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACpD,gBAAgB,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAClD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;IACvC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;CACzB,CAAC,CAAC"}
+{"version":3,"file":"revision.js","sourceRoot":"","sources":["../../../src/schemas/revision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;CAC1B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACpD,gBAAgB,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAClD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAEH,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC;CAC5B,CAAC,CAAC;AAEH,+EAA+E;AAC/E,2CAA2C;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,CAAC;IACN,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;IACvC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;CACzB,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,yEAAyE;AACzE,2EAA2E;AAC3E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC;CAClC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,+DAA+D;AAC/D,oEAAoE;AACpE,0EAA0E;AAC1E,0BAA0B;AAC1B,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAS7D,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,OAAO,OAAO,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,CAAkB;IACpD,OAAO,cAAc,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/src/schemas/session.d.ts

@@ -35,6 +35,8 @@ export declare const SessionSchema: z.ZodObject<{
     startedAt: z.ZodString;
     planHash: z.ZodString;
     initialLineCount: z.ZodOptional<z.ZodNumber>;
+    reviewerSessionId: z.ZodOptional<z.ZodString>;
+    reviewerSessionInitialized: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     status: "aborted" | "approved" | "blocked" | "planning" | "in_review";
@@ -55,6 +57,8 @@ export declare const SessionSchema: z.ZodObject<{
     startedAt: string;
     planHash: string;
     initialLineCount?: number | undefined;
+    reviewerSessionId?: string | undefined;
+    reviewerSessionInitialized?: boolean | undefined;
 }, {
     id: string;
     status: "aborted" | "approved" | "blocked" | "planning" | "in_review";
@@ -75,5 +79,7 @@ export declare const SessionSchema: z.ZodObject<{
     startedAt: string;
     planHash: string;
     initialLineCount?: number | undefined;
+    reviewerSessionId?: string | undefined;
+    reviewerSessionInitialized?: boolean | undefined;
 }>;
 export type Session = z.infer<typeof SessionSchema>;