@navels/neal 0.1.0 → 0.3.0

package/dist/neal/agents/schemas.js

@@ -1,405 +1,568 @@
+import { z } from 'zod';
+import { normalizeExecutionShapeDeclaration, validatePlanDocument } from '../plan-validation.js';
 import { repairReviewerSquashMessageDraft, validateReviewerSquashMessageDraft } from '../squash-message.js';
-const REVIEWER_PAYLOAD_KEYS = [
-    'summary',
-    'findings',
-    'meaningfulProgressAction',
-    'meaningfulProgressRationale',
-];
-const REVIEWER_FINDING_KEYS = ['severity', 'files', 'claim', 'evidence', 'requiredAction'];
+export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_START = 'NEAL_PROGRESS_JUSTIFICATION_JSON_START';
+export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_END = 'NEAL_PROGRESS_JUSTIFICATION_JSON_END';
+// --- zod payload definitions (single source of truth) -----------------------
 const REVIEWER_FINDING_SEVERITIES = ['blocking', 'non_blocking'];
+export const PLAN_REVIEWER_FINDING_CLASSES = [
+    'plan_correctness',
+    'verification_hardening',
+];
 const REVIEWER_MEANINGFUL_PROGRESS_ACTIONS = [
     'accept',
     'block_for_operator',
     'replace_plan',
     'advance_parent',
 ];
-export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_START = 'NEAL_PROGRESS_JUSTIFICATION_JSON_START';
-export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_END = 'NEAL_PROGRESS_JUSTIFICATION_JSON_END';
+const EXECUTION_SHAPES = ['one_shot', 'multi_scope', 'multi_scope_unknown'];
+const CONSULTANT_TRIAGE_CATEGORIES = [
+    'misunderstanding',
+    'authorization',
+    'external_precondition',
+    'impossible_task',
+];
+const CODER_FINDING_RESPONSE_DECISIONS = ['fixed', 'rejected', 'deferred'];
+const CODER_RESPONSE_OUTCOMES = ['responded', 'blocked', 'split_plan'];
+const CODER_BLOCKED_RECOVERY_ACTIONS = [
+    'resume_current_scope',
+    'replace_current_scope',
+    'stay_blocked',
+    'terminal_block',
+];
+const CODER_PLAN_RESPONSE_OUTCOMES = ['responded', 'blocked'];
+const CODER_PLAN_ACTIONS = ['ready_for_review', 'blocked'];
+const CODER_SCOPE_ACTIONS = ['continue', 'scope_done', 'done', 'blocked', 'split_plan', 'manual_gate'];
+const MANUAL_GATE_RESUME_CHECK_TYPES = ['command'];
+const MANUAL_GATE_RESUME_CHECK_CWDS = ['repo', 'run_dir'];
+const FINAL_COMPLETION_REVIEWER_ACTIONS = ['accept_complete', 'continue_execution', 'block_for_operator'];
+const SQUASH_COMMIT_MESSAGE_DESCRIPTION = 'Project-facing Git history metadata used only when action is accept_complete; set null for continue_execution or block_for_operator.';
+const SQUASH_COMMIT_SUBJECT_DESCRIPTION = 'Concise project-facing commit subject summarizing code or product behavior, not plan documents, paths, scopes, Neal mechanics, provider process, reviewer process, or final cleanup.';
+const SQUASH_COMMIT_BULLETS_DESCRIPTION = 'Two to five project-facing Git history bullets summarizing behavior changes; avoid plan paths, markdown plan filenames, temporary run paths, scope wording, Neal mechanics, provider process, or reviewer process.';
+// The reviewer payload is the strict unknown-key family: unknown properties
+// are rejected at both the top level and inside findings (z.strictObject).
+// Every other payload uses zod's default strip-mode z.object — unknown
+// properties are accepted and omitted from the normalized output.
+const reviewerFindingSchema = z.strictObject({
+    severity: z.enum(REVIEWER_FINDING_SEVERITIES),
+    files: z.array(z.string()),
+    claim: z.string(),
+    evidence: z.string(),
+    requiredAction: z.string(),
+});
+const reviewerPayloadSchema = z.strictObject({
+    summary: z.string(),
+    findings: z.array(reviewerFindingSchema),
+    meaningfulProgressAction: z.enum(REVIEWER_MEANINGFUL_PROGRESS_ACTIONS),
+    meaningfulProgressRationale: z.string(),
+});
+const planReviewerFindingSchema = z.object({
+    severity: z.enum(REVIEWER_FINDING_SEVERITIES),
+    files: z.array(z.string()),
+    claim: z.string(),
+    requiredAction: z.string(),
+    // Optional at the payload boundary: an absent class normalizes to the fail-safe
+    // plan_correctness downstream (see validatePlanReviewerPayload), while a
+    // present-but-invalid value is rejected by the sequential validator before any
+    // normalization runs. The reviewer round is a `neal-json-block-v1` structured
+    // round (the schema is advisory prompt context, not native strict output), so —
+    // like the consultant's optional targetCanonicalIds — this property is
+    // intentionally absent from the emitted `required` tuple and buildPlanReviewerSchema
+    // is excluded from the strict all-required contract.
+    findingClass: z.enum(PLAN_REVIEWER_FINDING_CLASSES).optional(),
+});
+const planReviewerPayloadSchema = z.object({
+    summary: z.string(),
+    executionShape: z.enum(EXECUTION_SHAPES),
+    findings: z.array(planReviewerFindingSchema),
+});
+const consultantPayloadSchema = z.object({
+    recoverable: z.boolean(),
+    triageCategory: z.enum(CONSULTANT_TRIAGE_CATEGORIES),
+    resolutionDirective: z.string(),
+    targetCanonicalIds: z.array(z.string()).optional(),
+    rationale: z.string(),
+});
+const coderFindingResponseSchema = z.object({
+    id: z.string(),
+    decision: z.enum(CODER_FINDING_RESPONSE_DECISIONS),
+    summary: z.string(),
+});
+const coderResponsePayloadSchema = z.object({
+    outcome: z.enum(CODER_RESPONSE_OUTCOMES),
+    summary: z.string(),
+    blocker: z.string(),
+    derivedPlan: z.string(),
+    responses: z.array(coderFindingResponseSchema),
+});
+const coderBlockedRecoveryDispositionPayloadSchema = z.object({
+    action: z.enum(CODER_BLOCKED_RECOVERY_ACTIONS),
+    summary: z.string(),
+    rationale: z.string(),
+    blocker: z.string(),
+    replacementPlan: z.string(),
+});
+const coderPlanResponsePayloadSchema = z.object({
+    outcome: z.enum(CODER_PLAN_RESPONSE_OUTCOMES),
+    summary: z.string(),
+    blocker: z.string(),
+    responses: z.array(coderFindingResponseSchema),
+});
+const coderPlanPayloadSchema = z.object({
+    action: z.enum(CODER_PLAN_ACTIONS),
+    message: z.string(),
+    executionShape: z.enum(EXECUTION_SHAPES),
+    planBody: z.string(),
+    blockedReason: z.string(),
+});
+const executeScopeProgressSchema = z.object({
+    milestoneTargeted: z.string(),
+    newEvidence: z.string(),
+    whyNotRedundant: z.string(),
+    nextStepUnlocked: z.string(),
+});
+const manualGateResumeCheckSchema = z.object({
+    type: z.enum(MANUAL_GATE_RESUME_CHECK_TYPES),
+    name: z.string(),
+    command: z.array(z.string()),
+    cwd: z.enum(MANUAL_GATE_RESUME_CHECK_CWDS).nullable(),
+    timeoutMs: z.number().nullable(),
+});
+const manualGateSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    reason: z.string(),
+    instructionsMarkdown: z.string(),
+    resumeChecks: z.array(manualGateResumeCheckSchema),
+});
+const coderScopePayloadSchema = z.object({
+    action: z.enum(CODER_SCOPE_ACTIONS),
+    message: z.string(),
+    progress: executeScopeProgressSchema,
+    manualGate: manualGateSchema.nullable(),
+    derivedPlan: z.string(),
+    blockedReason: z.string(),
+});
+// Parse-stage view of the coder scope payload. The full definition above is
+// what the emitted JSON Schema promises callers; validation historically only
+// checks object-ness of `progress` and `manualGate` up front, then applies
+// the delimiter-protocol progress messages and the manual-gate deep
+// validation (which trims strings and accepts absent cwd/timeoutMs) as
+// explicit post-parse steps with their own pinned message grammar.
+const coderScopeParseSchema = coderScopePayloadSchema.extend({
+    progress: z.looseObject({}),
+    manualGate: z.looseObject({}).nullable(),
+});
+const finalCompletionSummaryPayloadSchema = z.object({
+    planGoalSatisfied: z.boolean(),
+    whatChangedOverall: z.string(),
+    verificationSummary: z.string(),
+    remainingKnownGaps: z.array(z.string()),
+});
+const squashCommitMessageDraftSchema = z.object({
+    subject: z.string().describe(SQUASH_COMMIT_SUBJECT_DESCRIPTION),
+    bullets: z.array(z.string()).min(2).max(5).describe(SQUASH_COMMIT_BULLETS_DESCRIPTION),
+});
+const finalCompletionReviewerPayloadSchema = z.object({
+    action: z.enum(FINAL_COMPLETION_REVIEWER_ACTIONS),
+    summary: z.string(),
+    rationale: z.string(),
+    missingWork: z
+        .object({
+        summary: z.string(),
+        requiredOutcome: z.string(),
+        verification: z.string(),
+    })
+        .nullable(),
+    squashCommitMessage: squashCommitMessageDraftSchema.nullable().describe(SQUASH_COMMIT_MESSAGE_DESCRIPTION),
+});
+// Parse-stage view of the final-completion reviewer verdict. The squash draft
+// is advisory: a malformed or absent draft must never reject the verdict, so
+// validation only checks object-ness here and routes the draft through
+// validate/repair in parseFinalCompletionReviewerPayload.
+const finalCompletionReviewerParseSchema = finalCompletionReviewerPayloadSchema.extend({
+    squashCommitMessage: z.looseObject({}).nullable().optional(),
+});
+// Canonical key order of the previous hand-written builders. Emitted schemas
+// are serialized into prompt text with JSON.stringify(schema, null, 2), so
+// this ordering changes prompt bytes and is pinned byte-for-byte by
+// test/agent-payload-schemas.test.ts.
+const EMITTED_SCHEMA_KEY_ORDER = [
+    'description',
+    'type',
+    'enum',
+    'minItems',
+    'maxItems',
+    'items',
+    'properties',
+    'required',
+    'additionalProperties',
+];
+function isJsonSchemaRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// Collapse zod's `anyOf: [X, { type: 'null' }]` encoding of .nullable() into
+// the hand-written builders' merged form: X with `type: [<X type>, 'null']`,
+// appending null to X's enum when one is present (e.g. the resume-check cwd).
+function collapseNullableAnyOf(node) {
+    const { anyOf, ...rest } = node;
+    if (!Array.isArray(anyOf) || anyOf.length !== 2) {
+        return node;
+    }
+    const [base, nullBranch] = anyOf;
+    if (!isJsonSchemaRecord(base) || !isJsonSchemaRecord(nullBranch)) {
+        return node;
+    }
+    if (nullBranch.type !== 'null' || Object.keys(nullBranch).length !== 1) {
+        return node;
+    }
+    const merged = { ...base, ...rest };
+    merged.type = Array.isArray(base.type) ? [...base.type, 'null'] : [base.type, 'null'];
+    if (Array.isArray(base.enum)) {
+        merged.enum = [...base.enum, null];
+    }
+    return merged;
+}
+function normalizeEmittedSchemaNode(node) {
+    const record = collapseNullableAnyOf(node);
+    const keys = Object.keys(record);
+    const orderedKeys = [
+        ...EMITTED_SCHEMA_KEY_ORDER.filter((key) => keys.includes(key)),
+        ...keys.filter((key) => !EMITTED_SCHEMA_KEY_ORDER.includes(key)),
+    ];
+    const normalized = {};
+    for (const key of orderedKeys) {
+        const value = record[key];
+        if (key === 'items' && isJsonSchemaRecord(value)) {
+            normalized[key] = normalizeEmittedSchemaNode(value);
+        }
+        else if (key === 'properties' && isJsonSchemaRecord(value)) {
+            const properties = {};
+            for (const [propertyName, propertySchema] of Object.entries(value)) {
+                properties[propertyName] = isJsonSchemaRecord(propertySchema)
+                    ? normalizeEmittedSchemaNode(propertySchema)
+                    : propertySchema;
+            }
+            normalized[key] = properties;
+        }
+        else {
+            normalized[key] = value;
+        }
+    }
+    const type = normalized.type;
+    const isObjectNode = type === 'object' || (Array.isArray(type) && type.includes('object'));
+    if (isObjectNode && normalized.properties !== undefined) {
+        normalized.additionalProperties = false;
+    }
+    return normalized;
+}
+// The declared literal return shape is asserted here rather than proven
+// structurally: the byte-level serialization pins in
+// test/agent-payload-schemas.test.ts fail whenever the zod-derived emission
+// diverges from the declared shapes.
+function emitJsonSchema(schema) {
+    const emitted = z.toJSONSchema(schema);
+    delete emitted.$schema;
+    return normalizeEmittedSchemaNode(emitted);
+}
 export function buildReviewerSchema() {
-    return {
-        type: 'object',
-        properties: {
-            summary: { type: 'string' },
-            findings: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    properties: {
-                        severity: { type: 'string', enum: ['blocking', 'non_blocking'] },
-                        files: { type: 'array', items: { type: 'string' } },
-                        claim: { type: 'string' },
-                        evidence: { type: 'string' },
-                        requiredAction: { type: 'string' },
-                    },
-                    required: ['severity', 'files', 'claim', 'evidence', 'requiredAction'],
-                    additionalProperties: false,
-                },
-            },
-            meaningfulProgressAction: { type: 'string', enum: ['accept', 'block_for_operator', 'replace_plan', 'advance_parent'] },
-            meaningfulProgressRationale: { type: 'string' },
-        },
-        required: ['summary', 'findings', 'meaningfulProgressAction', 'meaningfulProgressRationale'],
-        additionalProperties: false,
-    };
+    return emitJsonSchema(reviewerPayloadSchema);
 }
-export function validateReviewerPayload(payload) {
-    const value = requireReviewerObject(payload, 'Reviewer payload');
-    requireReviewerProperties(value, REVIEWER_PAYLOAD_KEYS, 'Reviewer payload');
-    if (!Array.isArray(value.findings)) {
-        throw new Error('Reviewer payload.findings must be an array.');
+export function buildPlanReviewerSchema() {
+    return emitJsonSchema(planReviewerPayloadSchema);
+}
+export function buildConsultantSchema() {
+    return emitJsonSchema(consultantPayloadSchema);
+}
+export function buildCoderResponseSchema() {
+    return emitJsonSchema(coderResponsePayloadSchema);
+}
+export function buildCoderBlockedRecoveryDispositionSchema() {
+    return emitJsonSchema(coderBlockedRecoveryDispositionPayloadSchema);
+}
+export function buildCoderPlanResponseSchema() {
+    return emitJsonSchema(coderPlanResponsePayloadSchema);
+}
+export function buildCoderPlanSchema() {
+    return emitJsonSchema(coderPlanPayloadSchema);
+}
+export function buildCoderScopeSchema() {
+    return emitJsonSchema(coderScopePayloadSchema);
+}
+export function buildExecuteScopeProgressSchema() {
+    return emitJsonSchema(executeScopeProgressSchema);
+}
+export function buildFinalCompletionSummarySchema() {
+    return emitJsonSchema(finalCompletionSummaryPayloadSchema);
+}
+export function buildFinalCompletionReviewerSchema() {
+    return emitJsonSchema(finalCompletionReviewerPayloadSchema);
+}
+// --- sequential zod-backed validation ------------------------------------------
+//
+// The historical validators were strictly sequential: each field was read and
+// checked one at a time in a fixed order, throwing at the FIRST failure, so a
+// property later in the validation order was never read once an earlier check
+// failed — a later throwing accessor could not mask an earlier error. A
+// whole-payload safeParse instead reads every field eagerly to collect all
+// issues. The traversal below therefore keeps the historical sequential read
+// order and short-circuit semantics while zod performs the actual
+// validation: each field or array element is parsed by its own zod
+// sub-schema at the point the traversal reaches it, and the first zod issue
+// is translated through ONE shared formatter into the historical grammar:
+//   `<Label>[.<path>] must be a non-null object.` / `... must be a string.` /
+//   `... must be a boolean.` / `... must be an array.` /
+//   `... must be exactly one of: a, b.`
+function describeSchemaIssue(fieldPath, issue) {
+    if (issue.code === 'invalid_type') {
+        switch (issue.expected) {
+            case 'object':
+                return `${fieldPath} must be a non-null object.`;
+            case 'string':
+                return `${fieldPath} must be a string.`;
+            case 'boolean':
+                return `${fieldPath} must be a boolean.`;
+            case 'array':
+                return `${fieldPath} must be an array.`;
+            default:
+                break;
+        }
     }
-    return {
-        summary: requireReviewerString(value.summary, 'Reviewer payload.summary'),
-        findings: value.findings.map(validateReviewerFindingPayload),
-        meaningfulProgressAction: requireReviewerEnum(value.meaningfulProgressAction, 'Reviewer payload.meaningfulProgressAction', REVIEWER_MEANINGFUL_PROGRESS_ACTIONS),
-        meaningfulProgressRationale: requireReviewerString(value.meaningfulProgressRationale, 'Reviewer payload.meaningfulProgressRationale'),
-    };
+    if (issue.code === 'invalid_value') {
+        return `${fieldPath} must be exactly one of: ${issue.values.join(', ')}.`;
+    }
+    // Any other zod constraint surfaces with zod's own issue description.
+    return `${fieldPath} failed validation: ${issue.message}`;
 }
-function validateReviewerFindingPayload(finding, index) {
-    const label = `Reviewer payload.findings[${index}]`;
-    const value = requireReviewerObject(finding, label);
-    requireReviewerProperties(value, REVIEWER_FINDING_KEYS, label);
-    if (!Array.isArray(value.files)) {
-        throw new Error(`${label}.files must be an array.`);
+function firstSchemaIssueMessage(schema, value, fieldPath) {
+    const result = schema.safeParse(value);
+    if (result.success) {
+        // Unreachable: callers invoke this only for values the schema rejects.
+        return `${fieldPath} failed validation.`;
     }
-    return {
-        severity: requireReviewerEnum(value.severity, `${label}.severity`, REVIEWER_FINDING_SEVERITIES),
-        files: value.files.map((file, fileIndex) => requireReviewerString(file, `${label}.files[${fileIndex}]`)),
-        claim: requireReviewerString(value.claim, `${label}.claim`),
-        evidence: requireReviewerString(value.evidence, `${label}.evidence`),
-        requiredAction: requireReviewerString(value.requiredAction, `${label}.requiredAction`),
-    };
+    return describeSchemaIssue(fieldPath, result.error.issues[0]);
+}
+// Container gates: return the value when it has the container type the
+// schema demands; otherwise derive the failure message from the schema's own
+// zod issue. zod fails fast on container-type mismatches without reading any
+// property or element, so no accessor is invoked for a rejected value, and
+// the gate lets the traversal defer member reads to their historical
+// positions instead of letting a whole-container parse read them eagerly.
+function requireRecordSequential(schema, value, fieldPath) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    throw new Error(firstSchemaIssueMessage(schema, value, fieldPath));
 }
-function requireReviewerObject(value, label) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error(`${label} must be a non-null object.`);
+function requireArraySequential(schema, value, fieldPath) {
+    if (Array.isArray(value)) {
+        return value;
     }
-    return value;
+    throw new Error(firstSchemaIssueMessage(schema, value, fieldPath));
 }
-function requireReviewerProperties(value, requiredKeys, label) {
-    for (const key of requiredKeys) {
-        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+function validateFieldSequential(fieldSchema, value, fieldPath) {
+    if (fieldSchema instanceof z.ZodOptional) {
+        if (value === undefined) {
+            return undefined;
+        }
+        return validateFieldSequential(fieldSchema.unwrap(), value, fieldPath);
+    }
+    if (fieldSchema instanceof z.ZodNullable) {
+        if (value === null) {
+            return null;
+        }
+        return validateFieldSequential(fieldSchema.unwrap(), value, fieldPath);
+    }
+    if (fieldSchema instanceof z.ZodArray) {
+        const items = requireArraySequential(fieldSchema, value, fieldPath);
+        const element = fieldSchema.element;
+        if (element instanceof z.ZodObject) {
+            // Historical object-array semantics: every item's object-ness is
+            // checked before any item's fields are read.
+            const records = items.map((item, index) => requireRecordSequential(element, item, `${fieldPath}[${index}]`));
+            return records.map((item, index) => walkObjectSequential(element, item, `${fieldPath}[${index}]`));
+        }
+        return items.map((item, index) => validateFieldSequential(element, item, `${fieldPath}[${index}]`));
+    }
+    if (fieldSchema instanceof z.ZodObject) {
+        const record = requireRecordSequential(fieldSchema, value, fieldPath);
+        // Empty-shape loose objects are the historical object-ness-only
+        // passthroughs (coder-scope progress/manualGate, the squash draft): the
+        // ORIGINAL reference is returned so the explicit post-parse steps read
+        // fields at their historical positions.
+        if (Object.keys(fieldSchema.shape).length === 0) {
+            return record;
+        }
+        return walkObjectSequential(fieldSchema, record, fieldPath);
+    }
+    // Leaf schema: zod itself enforces the constraint at the point the
+    // traversal reaches this field; its first issue is translated through the
+    // shared formatter.
+    const result = fieldSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(describeSchemaIssue(fieldPath, result.error.issues[0]));
+    }
+    return result.data;
+}
+// Walks a strip-mode object schema field-by-field in shape declaration order,
+// reading each property only when its turn comes and throwing at the first
+// failure. Unknown keys are omitted from the rebuilt output (historical
+// permissive behavior).
+function walkObjectSequential(schema, record, basePath) {
+    const output = {};
+    for (const [key, fieldSchema] of Object.entries(schema.shape)) {
+        const fieldPath = `${basePath}.${key}`;
+        // Historical optional/nullable field patterns performed one property
+        // read for the undefined/null test and a FRESH read for validation when
+        // the field was present, so stateful accessors observe both reads (the
+        // consultant targetCanonicalIds ternary and the coder-scope
+        // manualGate ternary behaved this way).
+        if (fieldSchema instanceof z.ZodOptional) {
+            if (record[key] === undefined) {
+                continue;
+            }
+            output[key] = validateFieldSequential(fieldSchema.unwrap(), record[key], fieldPath);
+            continue;
+        }
+        if (fieldSchema instanceof z.ZodNullable) {
+            if (record[key] === null) {
+                output[key] = null;
+                continue;
+            }
+            output[key] = validateFieldSequential(fieldSchema.unwrap(), record[key], fieldPath);
+            continue;
+        }
+        output[key] = validateFieldSequential(fieldSchema, record[key], fieldPath);
+    }
+    return output;
+}
+// Permissive-family entry point: object-ness first (`<Label> must be a
+// non-null object.`), then the sequential field walk in shape declaration
+// order, which matches the historical field-by-field check order of these
+// validators.
+function parsePayload(schema, payload, label) {
+    if (!(schema instanceof z.ZodObject)) {
+        throw new Error(`${label} failed validation: sequential parsing requires an object schema.`);
+    }
+    const record = requireRecordSequential(schema, payload, label);
+    return walkObjectSequential(schema, record, label);
+}
+// --- reviewer payload (strict unknown-key family) ----------------------------
+// The strict reviewer family additionally enforced, at each object level and
+// BEFORE reading any declared field: required own properties (in key order,
+// via Object.prototype.hasOwnProperty — prototype-inherited properties are
+// rejected and their accessors never invoked) and unknown-key rejection (in
+// input order, via Object.keys). The historical sequence, reproduced below:
+// object-ness, missing required own properties, unknown properties, findings
+// array-ness, summary, each finding in order (object-ness, missing, unknown,
+// files array-ness, severity, files items, claim, evidence, requiredAction),
+// then meaningfulProgressAction and meaningfulProgressRationale.
+function assertReviewerOwnProperties(record, shape, label) {
+    for (const key of Object.keys(shape)) {
+        if (!Object.prototype.hasOwnProperty.call(record, key)) {
             throw new Error(`${label} is missing required property "${key}".`);
         }
     }
-    for (const key of Object.keys(value)) {
-        if (!requiredKeys.includes(key)) {
+    for (const key of Object.keys(record)) {
+        if (!Object.prototype.hasOwnProperty.call(shape, key)) {
             throw new Error(`${label} included unknown property "${key}".`);
         }
     }
 }
-function requireReviewerString(value, fieldPath) {
-    if (typeof value !== 'string') {
-        throw new Error(`${fieldPath} must be a string.`);
-    }
-    return value;
-}
-function requireReviewerEnum(value, fieldPath, allowedValues) {
-    if (typeof value !== 'string' || !allowedValues.includes(value)) {
-        throw new Error(`${fieldPath} must be exactly one of: ${allowedValues.join(', ')}.`);
+function validateReviewerFindingSequential(finding, index) {
+    const label = `Reviewer payload.findings[${index}]`;
+    const record = requireRecordSequential(reviewerFindingSchema, finding, label);
+    const shape = reviewerFindingSchema.shape;
+    assertReviewerOwnProperties(record, shape, label);
+    // Historical order and access pattern: the files array-ness check read
+    // `files` before severity (or any other declared field) was read, and the
+    // items mapping below RE-READS the property after severity, so a stateful
+    // accessor's second read supplies the validated items.
+    const filesProbe = record.files;
+    if (!Array.isArray(filesProbe)) {
+        throw new Error(firstSchemaIssueMessage(shape.files, filesProbe, `${label}.files`));
     }
-    return value;
-}
-export function buildPlanReviewerSchema() {
     return {
-        type: 'object',
-        properties: {
-            summary: { type: 'string' },
-            executionShape: { type: 'string', enum: ['one_shot', 'multi_scope', 'multi_scope_unknown'] },
-            findings: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    properties: {
-                        severity: { type: 'string', enum: ['blocking', 'non_blocking'] },
-                        files: { type: 'array', items: { type: 'string' } },
-                        claim: { type: 'string' },
-                        requiredAction: { type: 'string' },
-                    },
-                    required: ['severity', 'files', 'claim', 'requiredAction'],
-                    additionalProperties: false,
-                },
-            },
-        },
-        required: ['summary', 'executionShape', 'findings'],
-        additionalProperties: false,
+        severity: validateFieldSequential(shape.severity, record.severity, `${label}.severity`),
+        files: record.files.map((file, fileIndex) => validateFieldSequential(shape.files.element, file, `${label}.files[${fileIndex}]`)),
+        claim: validateFieldSequential(shape.claim, record.claim, `${label}.claim`),
+        evidence: validateFieldSequential(shape.evidence, record.evidence, `${label}.evidence`),
+        requiredAction: validateFieldSequential(shape.requiredAction, record.requiredAction, `${label}.requiredAction`),
     };
 }
-export function buildBlockedAdjudicatorSchema() {
+export function validateReviewerPayload(payload) {
+    const record = requireRecordSequential(reviewerPayloadSchema, payload, 'Reviewer payload');
+    const shape = reviewerPayloadSchema.shape;
+    assertReviewerOwnProperties(record, shape, 'Reviewer payload');
+    // Historical access pattern: the array-ness check performs its own read,
+    // and the mapping below re-reads the property (after summary), so a
+    // stateful accessor's second read is the one validated and normalized.
+    const findingsProbe = record.findings;
+    if (!Array.isArray(findingsProbe)) {
+        throw new Error(firstSchemaIssueMessage(shape.findings, findingsProbe, 'Reviewer payload.findings'));
+    }
     return {
-        type: 'object',
-        properties: {
-            recoverable: { type: 'boolean' },
-            triageCategory: {
-                type: 'string',
-                enum: ['misunderstanding', 'authorization', 'external_precondition', 'impossible_task'],
-            },
-            resolutionDirective: { type: 'string' },
-            targetCanonicalIds: { type: 'array', items: { type: 'string' } },
-            rationale: { type: 'string' },
-        },
-        required: ['recoverable', 'triageCategory', 'resolutionDirective', 'rationale'],
-        additionalProperties: false,
+        summary: validateFieldSequential(shape.summary, record.summary, 'Reviewer payload.summary'),
+        findings: record.findings.map((finding, index) => validateReviewerFindingSequential(finding, index)),
+        meaningfulProgressAction: validateFieldSequential(shape.meaningfulProgressAction, record.meaningfulProgressAction, 'Reviewer payload.meaningfulProgressAction'),
+        meaningfulProgressRationale: validateFieldSequential(shape.meaningfulProgressRationale, record.meaningfulProgressRationale, 'Reviewer payload.meaningfulProgressRationale'),
     };
 }
-// Validates a read-only review_stuck arbiter verdict. Exactly one triage
+// --- permissive validators ----------------------------------------------------
+// Validates a read-only review_stuck consultant verdict. Exactly one triage
 // category is autonomously recoverable: `misunderstanding` requires
 // recoverable=true plus a non-empty resolutionDirective; the three genuine-wall
 // categories (`authorization`, `external_precondition`, `impossible_task`)
 // require recoverable=false. Anything else (recoverable=true with another
 // triage, or recoverable=false paired with `misunderstanding`) is rejected so a
 // malformed verdict can never drive an autonomous recovery.
-export function validateBlockedAdjudicatorVerdictPayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Review-stuck arbiter payload');
+export function validateConsultantVerdictPayload(rawPayload) {
+    const parsed = parsePayload(consultantPayloadSchema, rawPayload, 'Consultant payload');
     const payload = {
-        recoverable: requirePayloadBoolean(value.recoverable, 'Review-stuck arbiter payload.recoverable'),
-        triageCategory: requirePayloadEnum(value.triageCategory, 'Review-stuck arbiter payload.triageCategory', [
-            'misunderstanding',
-            'authorization',
-            'external_precondition',
-            'impossible_task',
-        ]),
-        resolutionDirective: requirePayloadString(value.resolutionDirective, 'Review-stuck arbiter payload.resolutionDirective'),
+        recoverable: parsed.recoverable,
+        triageCategory: parsed.triageCategory,
+        resolutionDirective: parsed.resolutionDirective,
         // The verdict's targetCanonicalIds is optional: a coder/split-plan block has
         // no reviewer findings to point at, so an absent value defaults to [].
-        targetCanonicalIds: value.targetCanonicalIds === undefined
-            ? []
-            : requirePayloadStringArray(value.targetCanonicalIds, 'Review-stuck arbiter payload.targetCanonicalIds'),
-        rationale: requirePayloadString(value.rationale, 'Review-stuck arbiter payload.rationale'),
+        targetCanonicalIds: parsed.targetCanonicalIds ?? [],
+        rationale: parsed.rationale,
     };
     if (!payload.rationale.trim()) {
-        throw new Error('Review-stuck arbiter returned an empty rationale.');
+        throw new Error('Consultant returned an empty rationale.');
     }
     if (payload.recoverable) {
         if (payload.triageCategory !== 'misunderstanding') {
-            throw new Error('Review-stuck arbiter returned recoverable=true with a triageCategory other than misunderstanding.');
+            throw new Error('Consultant returned recoverable=true with a triageCategory other than misunderstanding.');
         }
         if (!payload.resolutionDirective.trim()) {
-            throw new Error('Review-stuck arbiter returned recoverable=true without a non-empty resolutionDirective.');
+            throw new Error('Consultant returned recoverable=true without a non-empty resolutionDirective.');
         }
     }
     else if (payload.triageCategory === 'misunderstanding') {
-        throw new Error('Review-stuck arbiter returned recoverable=false paired with triageCategory=misunderstanding.');
+        throw new Error('Consultant returned recoverable=false paired with triageCategory=misunderstanding.');
     }
     return payload;
 }
 export function validatePlanReviewerPayload(payload) {
-    const value = requirePayloadObject(payload, 'Plan reviewer payload');
+    const parsed = parsePayload(planReviewerPayloadSchema, payload, 'Plan reviewer payload');
     return {
-        summary: requirePayloadString(value.summary, 'Plan reviewer payload.summary'),
-        executionShape: requirePayloadEnum(value.executionShape, 'Plan reviewer payload.executionShape', [
-            'one_shot',
-            'multi_scope',
-            'multi_scope_unknown',
-        ]),
-        findings: requirePayloadObjectArray(value.findings, 'Plan reviewer payload.findings').map((finding, index) => ({
-            severity: requirePayloadEnum(finding.severity, `Plan reviewer payload.findings[${index}].severity`, [
-                'blocking',
-                'non_blocking',
-            ]),
-            files: requirePayloadStringArray(finding.files, `Plan reviewer payload.findings[${index}].files`),
-            claim: requirePayloadString(finding.claim, `Plan reviewer payload.findings[${index}].claim`),
+        summary: parsed.summary,
+        executionShape: parsed.executionShape,
+        findings: parsed.findings.map((finding) => ({
+            severity: finding.severity,
+            files: finding.files,
+            claim: finding.claim,
+            // Plan-review findings carry no evidence field; the normalized finding
+            // always forces an empty string.
             evidence: '',
-            requiredAction: requirePayloadString(finding.requiredAction, `Plan reviewer payload.findings[${index}].requiredAction`),
+            requiredAction: finding.requiredAction,
+            // Default only the absent case to plan_correctness (the fail-safe class).
+            // A present-but-invalid class was already rejected upstream in parsePayload,
+            // so this never silently downgrades a bad value.
+            findingClass: finding.findingClass ?? 'plan_correctness',
         })),
     };
 }
-export function buildCoderResponseSchema() {
-    return {
-        type: 'object',
-        properties: {
-            outcome: { type: 'string', enum: ['responded', 'blocked', 'split_plan'] },
-            summary: { type: 'string' },
-            blocker: { type: 'string' },
-            derivedPlan: { type: 'string' },
-            responses: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    properties: {
-                        id: { type: 'string' },
-                        decision: { type: 'string', enum: ['fixed', 'rejected', 'deferred'] },
-                        summary: { type: 'string' },
-                    },
-                    required: ['id', 'decision', 'summary'],
-                    additionalProperties: false,
-                },
-            },
-        },
-        required: ['outcome', 'summary', 'blocker', 'derivedPlan', 'responses'],
-        additionalProperties: false,
-    };
-}
-export function buildCoderBlockedRecoveryDispositionSchema() {
-    return {
-        type: 'object',
-        properties: {
-            action: {
-                type: 'string',
-                enum: ['resume_current_scope', 'replace_current_scope', 'stay_blocked', 'terminal_block'],
-            },
-            summary: { type: 'string' },
-            rationale: { type: 'string' },
-            blocker: { type: 'string' },
-            replacementPlan: { type: 'string' },
-        },
-        required: ['action', 'summary', 'rationale', 'blocker', 'replacementPlan'],
-        additionalProperties: false,
-    };
-}
-export function buildCoderPlanResponseSchema() {
-    return {
-        type: 'object',
-        properties: {
-            outcome: { type: 'string', enum: ['responded', 'blocked'] },
-            summary: { type: 'string' },
-            blocker: { type: 'string' },
-            responses: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    properties: {
-                        id: { type: 'string' },
-                        decision: { type: 'string', enum: ['fixed', 'rejected', 'deferred'] },
-                        summary: { type: 'string' },
-                    },
-                    required: ['id', 'decision', 'summary'],
-                    additionalProperties: false,
-                },
-            },
-        },
-        required: ['outcome', 'summary', 'blocker', 'responses'],
-        additionalProperties: false,
-    };
-}
-export function buildCoderPlanSchema() {
-    return {
-        type: 'object',
-        properties: {
-            action: { type: 'string', enum: ['ready_for_review', 'blocked'] },
-            message: { type: 'string' },
-            executionShape: { type: 'string', enum: ['one_shot', 'multi_scope', 'multi_scope_unknown'] },
-            planBody: { type: 'string' },
-            blockedReason: { type: 'string' },
-        },
-        required: ['action', 'message', 'executionShape', 'planBody', 'blockedReason'],
-        additionalProperties: false,
-    };
-}
-export function buildCoderScopeSchema() {
-    const manualGateResumeCheckSchema = {
-        type: 'object',
-        properties: {
-            type: { type: 'string', enum: ['command'] },
-            name: { type: 'string' },
-            command: {
-                type: 'array',
-                items: { type: 'string' },
-            },
-            cwd: { type: ['string', 'null'], enum: ['repo', 'run_dir', null] },
-            timeoutMs: { type: ['number', 'null'] },
-        },
-        required: ['type', 'name', 'command', 'cwd', 'timeoutMs'],
-        additionalProperties: false,
-    };
-    return {
-        type: 'object',
-        properties: {
-            action: { type: 'string', enum: ['continue', 'scope_done', 'done', 'blocked', 'split_plan', 'manual_gate'] },
-            message: { type: 'string' },
-            progress: buildExecuteScopeProgressSchema(),
-            manualGate: {
-                type: ['object', 'null'],
-                properties: {
-                    id: { type: 'string' },
-                    title: { type: 'string' },
-                    reason: { type: 'string' },
-                    instructionsMarkdown: { type: 'string' },
-                    resumeChecks: {
-                        type: 'array',
-                        items: manualGateResumeCheckSchema,
-                    },
-                },
-                required: ['id', 'title', 'reason', 'instructionsMarkdown', 'resumeChecks'],
-                additionalProperties: false,
-            },
-            derivedPlan: { type: 'string' },
-            blockedReason: { type: 'string' },
-        },
-        required: ['action', 'message', 'progress', 'manualGate', 'derivedPlan', 'blockedReason'],
-        additionalProperties: false,
-    };
-}
-export function buildExecuteScopeProgressSchema() {
-    return {
-        type: 'object',
-        properties: {
-            milestoneTargeted: { type: 'string' },
-            newEvidence: { type: 'string' },
-            whyNotRedundant: { type: 'string' },
-            nextStepUnlocked: { type: 'string' },
-        },
-        required: ['milestoneTargeted', 'newEvidence', 'whyNotRedundant', 'nextStepUnlocked'],
-        additionalProperties: false,
-    };
-}
-export function buildFinalCompletionSummarySchema() {
-    return {
-        type: 'object',
-        properties: {
-            planGoalSatisfied: { type: 'boolean' },
-            whatChangedOverall: { type: 'string' },
-            verificationSummary: { type: 'string' },
-            remainingKnownGaps: {
-                type: 'array',
-                items: { type: 'string' },
-            },
-        },
-        required: ['planGoalSatisfied', 'whatChangedOverall', 'verificationSummary', 'remainingKnownGaps'],
-        additionalProperties: false,
-    };
-}
-export function buildFinalCompletionReviewerSchema() {
-    return {
-        type: 'object',
-        properties: {
-            action: { type: 'string', enum: ['accept_complete', 'continue_execution', 'block_for_operator'] },
-            summary: { type: 'string' },
-            rationale: { type: 'string' },
-            missingWork: {
-                type: ['object', 'null'],
-                properties: {
-                    summary: { type: 'string' },
-                    requiredOutcome: { type: 'string' },
-                    verification: { type: 'string' },
-                },
-                required: ['summary', 'requiredOutcome', 'verification'],
-                additionalProperties: false,
-            },
-            squashCommitMessage: {
-                description: 'Project-facing Git history metadata used only when action is accept_complete; set null for continue_execution or block_for_operator.',
-                type: ['object', 'null'],
-                properties: {
-                    subject: {
-                        description: 'Concise project-facing commit subject summarizing code or product behavior, not plan documents, paths, scopes, Neal mechanics, provider process, reviewer process, or final cleanup.',
-                        type: 'string',
-                    },
-                    bullets: {
-                        description: 'Two to five project-facing Git history bullets summarizing behavior changes; avoid plan paths, markdown plan filenames, temporary run paths, scope wording, Neal mechanics, provider process, or reviewer process.',
-                        type: 'array',
-                        minItems: 2,
-                        maxItems: 5,
-                        items: { type: 'string' },
-                    },
-                },
-                required: ['subject', 'bullets'],
-                additionalProperties: false,
-            },
-        },
-        required: ['action', 'summary', 'rationale', 'missingWork', 'squashCommitMessage'],
-        additionalProperties: false,
-    };
-}
 function parseJsonPayload(raw, label) {
     try {
         return JSON.parse(raw);
@@ -435,54 +598,15 @@ function extractDelimitedPayload(raw, label) {
     };
 }
 function requireNonEmptyString(value, field, label) {
-    if (typeof value !== 'string' || value.trim().length === 0) {
+    // Base string-ness is enforced by the field's zod node from
+    // executeScopeProgressSchema; the non-empty rule, trimming, and the pinned
+    // delimiter-protocol message (shared by missing, wrong-typed, and blank
+    // values) are runtime semantics layered on top.
+    const parsed = executeScopeProgressSchema.shape[field].safeParse(value);
+    if (!parsed.success || parsed.data.trim().length === 0) {
         throw new Error(`${label} returned an empty or missing ${field} field in the progress-justification payload.`);
     }
-    return value.trim();
-}
-function requirePayloadObject(value, label) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error(`${label} must be a non-null object.`);
-    }
-    return value;
-}
-function requirePayloadString(value, fieldPath) {
-    if (typeof value !== 'string') {
-        throw new Error(`${fieldPath} must be a string.`);
-    }
-    return value;
-}
-function requirePayloadBoolean(value, fieldPath) {
-    if (typeof value !== 'boolean') {
-        throw new Error(`${fieldPath} must be a boolean.`);
-    }
-    return value;
-}
-function requirePayloadStringArray(value, fieldPath) {
-    if (!Array.isArray(value)) {
-        throw new Error(`${fieldPath} must be an array.`);
-    }
-    return value.map((item, index) => requirePayloadString(item, `${fieldPath}[${index}]`));
-}
-function requirePayloadObjectArray(value, fieldPath) {
-    if (!Array.isArray(value)) {
-        throw new Error(`${fieldPath} must be an array.`);
-    }
-    return value.map((item, index) => requirePayloadObject(item, `${fieldPath}[${index}]`));
-}
-function requirePayloadEnum(value, fieldPath, allowedValues) {
-    if (typeof value !== 'string' || !allowedValues.includes(value)) {
-        throw new Error(`${fieldPath} must be exactly one of: ${allowedValues.join(', ')}.`);
-    }
-    return value;
-}
-function validateCoderFindingResponse(value, fieldPath) {
-    const response = requirePayloadObject(value, fieldPath);
-    return {
-        id: requirePayloadString(response.id, `${fieldPath}.id`),
-        decision: requirePayloadEnum(response.decision, `${fieldPath}.decision`, ['fixed', 'rejected', 'deferred']),
-        summary: requirePayloadString(response.summary, `${fieldPath}.summary`),
-    };
+    return parsed.data.trim();
 }
 // Legacy marker-protocol compatibility for active legacy_marker_v1 execution
 // sessions. New primary execution sessions use CoderScopePayload instead.
@@ -507,18 +631,7 @@ export function stripExecuteScopeProgressPayload(raw) {
     return before || after;
 }
 export function validateCoderResponsePayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Coder response round payload');
-    const payload = {
-        outcome: requirePayloadEnum(value.outcome, 'Coder response round payload.outcome', [
-            'responded',
-            'blocked',
-            'split_plan',
-        ]),
-        summary: requirePayloadString(value.summary, 'Coder response round payload.summary'),
-        blocker: requirePayloadString(value.blocker, 'Coder response round payload.blocker'),
-        derivedPlan: requirePayloadString(value.derivedPlan, 'Coder response round payload.derivedPlan'),
-        responses: requirePayloadObjectArray(value.responses, 'Coder response round payload.responses').map((response, index) => validateCoderFindingResponse(response, `Coder response round payload.responses[${index}]`)),
-    };
+    const payload = parsePayload(coderResponsePayloadSchema, rawPayload, 'Coder response round payload');
     const derivedPlan = payload.derivedPlan?.trim() ?? '';
     if (payload.outcome === 'split_plan' && !derivedPlan) {
         throw new Error('Coder response round returned outcome=split_plan without a derivedPlan payload.');
@@ -529,33 +642,10 @@ export function validateCoderResponsePayload(rawPayload) {
     return payload;
 }
 export function validateCoderPlanResponsePayload(payload) {
-    const value = requirePayloadObject(payload, 'Planner plan-response round payload');
-    return {
-        outcome: requirePayloadEnum(value.outcome, 'Planner plan-response round payload.outcome', [
-            'responded',
-            'blocked',
-        ]),
-        summary: requirePayloadString(value.summary, 'Planner plan-response round payload.summary'),
-        blocker: requirePayloadString(value.blocker, 'Planner plan-response round payload.blocker'),
-        responses: requirePayloadObjectArray(value.responses, 'Planner plan-response round payload.responses').map((response, index) => validateCoderFindingResponse(response, `Planner plan-response round payload.responses[${index}]`)),
-    };
+    return parsePayload(coderPlanResponsePayloadSchema, payload, 'Planner plan-response round payload');
 }
 export function validateCoderPlanPayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Planner plan round payload');
-    const payload = {
-        action: requirePayloadEnum(value.action, 'Planner plan round payload.action', [
-            'ready_for_review',
-            'blocked',
-        ]),
-        message: requirePayloadString(value.message, 'Planner plan round payload.message'),
-        executionShape: requirePayloadEnum(value.executionShape, 'Planner plan round payload.executionShape', [
-            'one_shot',
-            'multi_scope',
-            'multi_scope_unknown',
-        ]),
-        planBody: requirePayloadString(value.planBody, 'Planner plan round payload.planBody'),
-        blockedReason: requirePayloadString(value.blockedReason, 'Planner plan round payload.blockedReason'),
-    };
+    const payload = parsePayload(coderPlanPayloadSchema, rawPayload, 'Planner plan round payload');
     const planBody = payload.planBody.trim();
     const blockedReason = payload.blockedReason.trim();
     if (payload.action === 'ready_for_review' && !planBody) {
@@ -567,29 +657,36 @@ export function validateCoderPlanPayload(rawPayload) {
     if (payload.action === 'blocked' && !blockedReason) {
         throw new Error('Planner plan round returned action=blocked without a blockedReason payload.');
     }
+    // The refined plan is persisted over the plan document and sent straight to
+    // plan review, so it must satisfy the plan contract here — inside the
+    // structured-output validator — where a failure triggers the repair loop
+    // (the planner gets the errors and retries) instead of burning a reviewer
+    // round on an invalid document. Split-plan payloads already have this gate
+    // (validateSplitPlanPayload); a live run persisted a planner payload whose
+    // planBody was a 39-line refinement summary declaring multi_scope with no
+    // Execution Queue, and the reviewer round was spent rediscovering that.
+    if (payload.action === 'ready_for_review') {
+        const normalizedBody = normalizeExecutionShapeDeclaration(planBody, payload.executionShape);
+        const validation = validatePlanDocument(normalizedBody);
+        if (!validation.ok) {
+            throw new Error(`Planner plan round returned a planBody that is not a valid Neal plan document: ${validation.errors.join('; ')}. ` +
+                'Return the complete refined plan document, not a summary of the refinement.');
+        }
+    }
     return {
         ...payload,
         message: payload.message.trim(),
     };
 }
 export function validateCoderScopePayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Coder scope round payload');
+    const parsed = parsePayload(coderScopeParseSchema, rawPayload, 'Coder scope round payload');
     const payload = {
-        action: requirePayloadEnum(value.action, 'Coder scope round payload.action', [
-            'continue',
-            'scope_done',
-            'done',
-            'blocked',
-            'split_plan',
-            'manual_gate',
-        ]),
-        message: requirePayloadString(value.message, 'Coder scope round payload.message'),
-        progress: requirePayloadObject(value.progress, 'Coder scope round payload.progress'),
-        manualGate: value.manualGate === null
-            ? null
-            : requirePayloadObject(value.manualGate, 'Coder scope round payload.manualGate'),
-        derivedPlan: requirePayloadString(value.derivedPlan, 'Coder scope round payload.derivedPlan'),
-        blockedReason: requirePayloadString(value.blockedReason, 'Coder scope round payload.blockedReason'),
+        action: parsed.action,
+        message: parsed.message,
+        progress: parsed.progress,
+        manualGate: parsed.manualGate,
+        derivedPlan: parsed.derivedPlan,
+        blockedReason: parsed.blockedReason,
     };
     const progress = {
         milestoneTargeted: requireNonEmptyString(payload.progress?.milestoneTargeted, 'milestoneTargeted', 'Coder scope round'),
@@ -622,10 +719,10 @@ export function validateCoderScopePayload(rawPayload) {
         if (blockedReason) {
             throw new Error('Coder scope round returned a blockedReason payload with action=manual_gate.');
         }
-        const id = requireNonEmptyManualGateString(manualGate.id, 'manualGate.id');
-        const title = requireNonEmptyManualGateString(manualGate.title, 'manualGate.title');
-        const reason = requireNonEmptyManualGateString(manualGate.reason, 'manualGate.reason');
-        const instructionsMarkdown = requireNonEmptyManualGateString(manualGate.instructionsMarkdown, 'manualGate.instructionsMarkdown');
+        const id = requireNonEmptyManualGateString(manualGateSchema.shape.id, manualGate.id, 'manualGate.id');
+        const title = requireNonEmptyManualGateString(manualGateSchema.shape.title, manualGate.title, 'manualGate.title');
+        const reason = requireNonEmptyManualGateString(manualGateSchema.shape.reason, manualGate.reason, 'manualGate.reason');
+        const instructionsMarkdown = requireNonEmptyManualGateString(manualGateSchema.shape.instructionsMarkdown, manualGate.instructionsMarkdown, 'manualGate.instructionsMarkdown');
         const resumeChecks = validateManualGateResumeChecks(manualGate.resumeChecks);
         return {
             ...payload,
@@ -649,39 +746,72 @@ export function validateCoderScopePayload(rawPayload) {
         progress,
     };
 }
-function requireNonEmptyManualGateString(value, fieldPath) {
-    if (typeof value !== 'string' || value.trim().length === 0) {
+// Base-constraint nodes for the resume-check cwd/timeoutMs fields, unwrapped
+// from the emitted schema's nullable wrappers. Runtime optionality
+// intentionally differs from the emitted schema's requiredness (the runtime
+// validator accepts absence where the emitted schema requires the key), and
+// the historical validator performed ONE property read per comparison and
+// re-read the property for the normalized output — stateful accessors
+// legitimately observe multiple short-circuited reads. The membership
+// literals are therefore destructured from the zod enum node (one comparison
+// per option, per read, as historically), and number-ness parses through the
+// zod number node at its historical read position.
+const resumeCheckCwdOptions = manualGateResumeCheckSchema.shape.cwd.unwrap().options;
+const resumeCheckTimeoutMsNumberSchema = manualGateResumeCheckSchema.shape.timeoutMs.unwrap();
+function requireNonEmptyManualGateString(fieldSchema, value, fieldPath) {
+    // Base string-ness is enforced by the field's zod node; the non-empty rule,
+    // trimming, and the pinned message (shared by missing, wrong-typed, and
+    // blank values) are runtime semantics layered on top.
+    const parsed = fieldSchema.safeParse(value);
+    if (!parsed.success || typeof parsed.data !== 'string' || parsed.data.trim().length === 0) {
         throw new Error(`Coder scope round returned an empty or missing ${fieldPath} field.`);
     }
-    return value.trim();
+    return parsed.data.trim();
 }
 function validateManualGateResumeChecks(value) {
+    // The at-least-one-command rule is runtime-only semantics (the emitted
+    // schema does not constrain resumeChecks length), and its pinned message
+    // covers the array-ness base constraint too.
     if (!Array.isArray(value) || value.length === 0) {
         throw new Error('Coder scope round returned manualGate.resumeChecks without at least one command check.');
     }
+    const checkShape = manualGateResumeCheckSchema.shape;
     return value.map((check, index) => {
         const fieldPath = `manualGate.resumeChecks[${index}]`;
+        // Historical container gate with its pinned message; array items
+        // intentionally fall through to the type check below, exactly as the
+        // old typeof-based gate behaved.
         if (check === null || typeof check !== 'object') {
             throw new Error(`Coder scope round returned invalid ${fieldPath}.`);
         }
         const candidate = check;
-        if (candidate.type !== 'command') {
+        if (!checkShape.type.safeParse(candidate.type).success) {
             throw new Error(`Coder scope round returned ${fieldPath}.type that is not "command".`);
         }
-        const name = requireNonEmptyManualGateString(candidate.name, `${fieldPath}.name`);
+        const name = requireNonEmptyManualGateString(checkShape.name, candidate.name, `${fieldPath}.name`);
+        // Emptiness is runtime-only semantics with a pinned message that also
+        // covers array-ness; each part's base string-ness routes through the
+        // command element's zod node below.
         if (!Array.isArray(candidate.command) || candidate.command.length === 0) {
             throw new Error(`Coder scope round returned ${fieldPath}.command without a non-empty string array.`);
         }
-        const command = candidate.command.map((part, commandIndex) => requireNonEmptyManualGateString(part, `${fieldPath}.command[${commandIndex}]`));
+        const command = candidate.command.map((part, commandIndex) => requireNonEmptyManualGateString(checkShape.command.element, part, `${fieldPath}.command[${commandIndex}]`));
+        // Historical access semantics preserved exactly: one property read per
+        // comparison with short-circuiting, and fresh reads for the normalized
+        // output below. The undefined/null comparisons carry the runtime
+        // optionality; membership tests one zod enum option per read; the
+        // positive-safe-integer rule stays explicit runtime semantics.
         if (candidate.cwd !== undefined &&
             candidate.cwd !== null &&
-            candidate.cwd !== 'repo' &&
-            candidate.cwd !== 'run_dir') {
+            candidate.cwd !== resumeCheckCwdOptions[0] &&
+            candidate.cwd !== resumeCheckCwdOptions[1]) {
             throw new Error(`Coder scope round returned ${fieldPath}.cwd that is not "repo" or "run_dir".`);
         }
         if (candidate.timeoutMs !== undefined &&
             candidate.timeoutMs !== null &&
-            (typeof candidate.timeoutMs !== 'number' || !Number.isSafeInteger(candidate.timeoutMs) || candidate.timeoutMs < 1)) {
+            (!resumeCheckTimeoutMsNumberSchema.safeParse(candidate.timeoutMs).success ||
+                !Number.isSafeInteger(candidate.timeoutMs) ||
+                candidate.timeoutMs < 1)) {
             throw new Error(`Coder scope round returned ${fieldPath}.timeoutMs that is not a positive safe integer.`);
         }
         return {
@@ -693,23 +823,8 @@ function validateManualGateResumeChecks(value) {
         };
     });
 }
-function nonEmptyTrimmedItems(items) {
-    return items.map((item) => item.trim()).filter((item) => item.length > 0);
-}
 export function validateCoderBlockedRecoveryDispositionPayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Coder blocked-recovery payload');
-    const payload = {
-        action: requirePayloadEnum(value.action, 'Coder blocked-recovery payload.action', [
-            'resume_current_scope',
-            'replace_current_scope',
-            'stay_blocked',
-            'terminal_block',
-        ]),
-        summary: requirePayloadString(value.summary, 'Coder blocked-recovery payload.summary'),
-        rationale: requirePayloadString(value.rationale, 'Coder blocked-recovery payload.rationale'),
-        blocker: requirePayloadString(value.blocker, 'Coder blocked-recovery payload.blocker'),
-        replacementPlan: requirePayloadString(value.replacementPlan, 'Coder blocked-recovery payload.replacementPlan'),
-    };
+    const payload = parsePayload(coderBlockedRecoveryDispositionPayloadSchema, rawPayload, 'Coder blocked-recovery payload');
     const blocker = payload.blocker.trim();
     const replacementPlan = payload.replacementPlan.trim();
     if (payload.action === 'replace_current_scope' && !replacementPlan) {
@@ -724,13 +839,7 @@ export function validateCoderBlockedRecoveryDispositionPayload(rawPayload) {
     return payload;
 }
 export function parseFinalCompletionSummaryPayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Final completion summary payload');
-    const payload = {
-        planGoalSatisfied: requirePayloadBoolean(value.planGoalSatisfied, 'Final completion summary payload.planGoalSatisfied'),
-        whatChangedOverall: requirePayloadString(value.whatChangedOverall, 'Final completion summary payload.whatChangedOverall'),
-        verificationSummary: requirePayloadString(value.verificationSummary, 'Final completion summary payload.verificationSummary'),
-        remainingKnownGaps: requirePayloadStringArray(value.remainingKnownGaps, 'Final completion summary payload.remainingKnownGaps'),
-    };
+    const payload = parsePayload(finalCompletionSummaryPayloadSchema, rawPayload, 'Final completion summary payload');
     const whatChangedOverall = payload.whatChangedOverall.trim();
     const verificationSummary = payload.verificationSummary.trim();
     const remainingKnownGaps = payload.remainingKnownGaps
@@ -756,37 +865,41 @@ export function parseFinalCompletionSummaryPayload(rawPayload) {
     };
 }
 export function parseFinalCompletionReviewerPayload(rawPayload) {
-    const value = requirePayloadObject(rawPayload, 'Final completion reviewer verdict payload');
-    const action = requirePayloadEnum(value.action, 'Final completion reviewer verdict payload.action', [
-        'accept_complete',
-        'continue_execution',
-        'block_for_operator',
-    ]);
-    const missingWorkValue = value.missingWork;
-    const missingWorkShape = missingWorkValue === null
+    // Historical sequential order (pinned by test/agent-payload-schemas.test.ts,
+    // a deliberate deviation from shape order): action, missingWork
+    // object-ness, summary, rationale, missingWork nested fields, then
+    // squashCommitMessage object-ness. Each step short-circuits before any
+    // later property is read.
+    const label = 'Final completion reviewer verdict payload';
+    const record = requireRecordSequential(finalCompletionReviewerParseSchema, rawPayload, label);
+    const shape = finalCompletionReviewerParseSchema.shape;
+    const missingWorkSchema = finalCompletionReviewerPayloadSchema.shape.missingWork.unwrap();
+    const action = validateFieldSequential(shape.action, record.action, `${label}.action`);
+    const missingWorkValue = record.missingWork;
+    const missingWorkRecord = missingWorkValue === null
         ? null
-        : requirePayloadObject(missingWorkValue, 'Final completion reviewer verdict payload.missingWork');
+        : requireRecordSequential(missingWorkSchema, missingWorkValue, `${label}.missingWork`);
+    const summaryValue = validateFieldSequential(shape.summary, record.summary, `${label}.summary`);
+    const rationaleValue = validateFieldSequential(shape.rationale, record.rationale, `${label}.rationale`);
     const payload = {
         action,
-        summary: requirePayloadString(value.summary, 'Final completion reviewer verdict payload.summary'),
-        rationale: requirePayloadString(value.rationale, 'Final completion reviewer verdict payload.rationale'),
-        missingWork: missingWorkShape === null
+        summary: summaryValue,
+        rationale: rationaleValue,
+        missingWork: missingWorkRecord === null
             ? null
-            : {
-                summary: requirePayloadString(missingWorkShape.summary, 'Final completion reviewer verdict payload.missingWork.summary'),
-                requiredOutcome: requirePayloadString(missingWorkShape.requiredOutcome, 'Final completion reviewer verdict payload.missingWork.requiredOutcome'),
-                verification: requirePayloadString(missingWorkShape.verification, 'Final completion reviewer verdict payload.missingWork.verification'),
-            },
-        squashCommitMessage: value.squashCommitMessage === null || value.squashCommitMessage === undefined
+            : walkObjectSequential(missingWorkSchema, missingWorkRecord, `${label}.missingWork`),
+        // Historical access pattern: the null test, the undefined test, and the
+        // object-ness validation each read the property (three reads for a
+        // present draft, short-circuiting for null). Only object-ness is checked
+        // here — via the parse-variant zod node — because the advisory draft
+        // routes through the validate/repair post-parse step below.
+        squashCommitMessage: (record.squashCommitMessage === null || record.squashCommitMessage === undefined
             ? null
-            : requirePayloadObject(value.squashCommitMessage, 'Final completion reviewer verdict payload.squashCommitMessage'),
+            : requireRecordSequential(shape.squashCommitMessage, record.squashCommitMessage, `${label}.squashCommitMessage`)),
     };
     const summary = payload.summary.trim();
     const rationale = payload.rationale.trim();
     const squashCommitMessageValue = payload.squashCommitMessage ?? null;
-    if (!['accept_complete', 'continue_execution', 'block_for_operator'].includes(payload.action)) {
-        throw new Error(`Final completion reviewer verdict returned unsupported action ${JSON.stringify(payload.action)}.`);
-    }
     if (!summary) {
         throw new Error('Final completion reviewer verdict returned an empty summary field.');
     }
@@ -818,7 +931,7 @@ export function parseFinalCompletionReviewerPayload(rawPayload) {
                 label: 'Final completion reviewer squashCommitMessage',
             });
         }
-        catch (error) {
+        catch {
             squashCommitMessage = repairReviewerSquashMessageDraft(squashCommitMessageValue);
         }
     }