loopforge 3.9.2 → 4.0.7

package/dist/submission-guidance.js

@@ -11,47 +11,58 @@
  */
 import { deriveConfiguredCapability, getPolicy, } from "./policy.js";
 import { deriveRoundFacts, NO_IN_FLIGHT_ROUND } from "./round-facts.js";
+import { deriveCriterionStatuses } from "./criterion-status.js";
 import { deriveSubGoals } from "./subgoal-state.js";
+import { verificationActionFor } from "./verification-actions.js";
+import { deriveContractRequirement } from "./contract-requirement.js";
 /** Field order used by the prompt, guidance and receipts. Core fields first,
  *  then the execution report, then contract/sub-goal state, then the
  *  cognitive/report fields, then terminal fields. Deterministic by design. */
+/** v4.0.3: THE four structural evaluation fields. The MCP input schema, the
+ *  prompt template and field accounting read this one set. */
+export const CORE_SELF_EVALUATION_FIELDS = new Set([
+    "outcome",
+    "output_summary",
+    "constraint_violations",
+    "should_continue",
+]);
 export const FIELD_ORDER = [
-    "success",
+    "outcome",
     "output_summary",
     "constraint_violations",
     "should_continue",
     "execution_report.files_changed",
-    "execution_report.tests_reported",
-    "execution_report.contract_item_claims",
-    "execution_report.criterion_claims",
+    "execution_report.claims",
+    "objective_refinement",
     "subgoal_updates",
     "emerged_subtasks",
     "discovered_constraints",
     "wrong_assumptions",
-    "objective_refinement",
+    "open_questions",
+    "resolved_open_question_ids",
     "retracted_constraints",
-    "revised_success_criteria",
     "round_contract",
     "worker_results",
-    "prompt_requests",
-    "compression_checkpoint",
-    "checkpoint_label",
+    "subtask_boundary",
+    "subtask_boundary_label",
     "retroactiveClaims",
     "gate_ids",
-    "outcome",
     "blocker",
-    "stop_reason",
     "no_change_reason",
 ];
 const GUIDES = [
     {
-        path: "success",
-        purpose: "Whether the whole objective and every hard constraint are satisfied.",
-        when: "Every round. Use true only when the full goal is achieved and verified.",
+        path: "outcome",
+        purpose: "The ONE round conclusion.",
+        when: "Every round. success requires should_continue=false; blocked requires " +
+            "should_continue=false and a blocker; partial/failed may continue or stop.",
         nature: "claim",
-        downstream: "Stop decision, success trajectory, verification posture.",
-        toolDescription: "true ONLY if all hard constraints were met AND the task goal was achieved. " +
-            "This is a claim; a machine observation is what backs it.",
+        downstream: "Stop decision, success trajectory, verification posture, and every read " +
+            "surface. It is a claim; a machine observation is what backs it.",
+        toolDescription: "Required. success | partial | failed | blocked. success requires " +
+            "should_continue=false; blocked requires should_continue=false and a " +
+            "non-empty blocker. partial/failed may continue or stop. This is the ONE " +
+            "round conclusion.",
         core: true,
     },
     {
@@ -59,13 +70,15 @@ const GUIDES = [
         purpose: "What was actually done this round, not what was attempted.",
         when: "Every round.",
         nature: "report",
-        downstream: "Rolling summary, focus/handoff projection, backtrack failed-approach list.",
+        downstream: "Committed record, state file, audit/replay/explain, and backtrack " +
+            "failed-approach facts — never machine evidence or a current-prompt narrative.",
         toolDescription: "Specific, actionable summary of what was DONE this round — not what was " +
             "attempted. Do not restate the plan.",
         core: true,
     },
     {
         path: "constraint_violations",
+        array: true,
         purpose: "Hard constraints actually violated this round.",
         when: "Every round; empty when none were violated.",
         nature: "report",
@@ -86,6 +99,7 @@ const GUIDES = [
     },
     {
         path: "execution_report.files_changed",
+        array: true,
         purpose: "The boundary net change: paths whose content or file type differs between " +
             "round preparation and this submission, including deleted paths.",
         when: "Every round that changed the workspace. A commit alone adds no entry when content is unchanged.",
@@ -98,42 +112,43 @@ const GUIDES = [
         reportOnly: false,
     },
     {
-        path: "execution_report.tests_reported",
-        purpose: "The agent's own test counts.",
-        when: "When tests were run (or a test run is relevant to the claim).",
-        nature: "report",
-        downstream: "Compared with parsed command output when available; never converted into a verification verdict.",
-        toolDescription: "Self-reported test counts. Informational: the runtime never translates " +
-            "an exit code into a test count, and the receipt shows self-report and " +
-            "command observation separately.",
-    },
-    {
-        path: "execution_report.contract_item_claims",
-        purpose: "Claims about items of the ACTIVE Round Contract.",
-        when: "Only when an active contract is open; cite the rci-XXXXXXXX ids rendered in the prompt.",
+        path: "execution_report.claims",
+        array: true,
+        purpose: "Claims about objective criteria and ACTIVE contract items, in one channel.",
+        when: "When you want to declare which criteria or active contract items are met " +
+            "or still remaining; cite real cr-/rci- ids from this prompt.",
         nature: "claim",
-        decision: "Claim completed items of the active contract with their real rci- ids",
-        downstream: "Starts machine evaluation of the item; the item becomes verified only when its bound commands pass.",
-        toolDescription: "Claims about items of the ACTIVE contract, cited by the rci-XXXXXXXX id " +
-            "the prompt rendered. A claim never verifies anything by itself — the " +
-            "runtime marks an item verified only when its bound commands are observed " +
-            "passing. Unknown ids or illegal outcomes are contract_invalid.",
+        decision: "Claim criteria or active contract items with their real cr-/rci- ids",
+        compact: true,
+        promptRank: 10,
+        downstream: "`cr-` advisory; `rci-` strict; only machine commands verify.",
+        toolDescription: "One claims channel. Each entry is { id, outcome } where id is a " +
+            "cr-XXXXXXXX objective criterion id or an rci-XXXXXXXX item id of the " +
+            "ACTIVE contract, and outcome is met | remaining. cr- claims are " +
+            "advisory (unknown/malformed entries are dropped); rci- claims are strict " +
+            "(unknown/duplicate ids are contract_invalid). A claim never verifies " +
+            "anything by itself — the runtime marks an item verified only when its " +
+            "bound commands are observed passing.",
     },
     {
-        path: "execution_report.criterion_claims",
-        purpose: "Advisory claims about objective criteria.",
-        when: "When you want to state which criteria are met or still remaining.",
-        nature: "claim",
-        decision: "You can state which criteria are met or still outstanding",
-        promptLevels: ["l1", "l2"],
-        promptRank: 10,
-        downstream: "Advisory only: unbacked claims warn; they never upgrade a criterion to verified.",
-        toolDescription: "Advisory claims about objective criteria. LENIENT: unknown or malformed " +
-            "ids are dropped with a diagnostic, never a rejection. A criterion claim " +
-            "never becomes machine-verified by itself.",
+        path: "objective_refinement",
+        purpose: "The Agent's working version of the OVERALL starting objective — not the " +
+            "current round, not the contract.",
+        when: "Only when the overall objective genuinely evolved. Omit when unchanged; " +
+            "this is event-driven, not a per-round field.",
+        nature: "report",
+        decision: "Overall objective genuinely evolved (omit when unchanged)",
+        compact: true,
+        promptRank: 15,
+        downstream: "Updates the working objective text; never acceptance, criteria or constraints.",
+        toolDescription: "Optional, at most 1000 chars. A refined statement of the OVERALL " +
+            "starting objective when understanding genuinely changed. It never " +
+            "rewrites the operator acceptance, criteria or hard constraints, and it " +
+            "is not the round task or contract. Omit when the objective is unchanged.",
     },
     {
         path: "subgoal_updates",
+        array: true,
         purpose: "Explicit status transitions for existing sub-goals.",
         when: "When an active sg-XXXXXXXX sub-goal starts, is blocked, completes, or is canceled.",
         nature: "transition",
@@ -147,142 +162,171 @@ const GUIDES = [
     },
     {
         path: "emerged_subtasks",
-        purpose: "New sub-problems that surfaced during execution.",
-        when: "When a new work item appears or an existing one must be split.",
+        array: true,
+        purpose: "New execution-plan work that the active criteria/contract do not already cover.",
+        when: "Only when new work appears or an existing work item must be split. Zero " +
+            "is correct when the current criteria/contract already cover the round.",
         nature: "transition",
         decision: "A new sub-problem surfaced (plain text, never sg- ids)",
-        promptLevels: ["l1", "l2"],
+        compact: true,
         promptRank: 40,
         downstream: "The only sub-goal creation channel; the runtime derives stable sg- ids.",
-        toolDescription: "Sub-problems that surfaced during execution. The ONLY sub-goal creation " +
-            "channel. Plain descriptions, never sg-XXXXXXXX ids.",
+        toolDescription: "New work that surfaced during execution and was not already covered by " +
+            "the active criteria or current contract. The ONLY sub-goal creation " +
+            "channel. Plain descriptions, never sg-XXXXXXXX ids. Do not restate the " +
+            "criteria as sub-goals; zero entries is a valid result.",
     },
     {
         path: "discovered_constraints",
+        array: true,
         purpose: "New constraints that later rounds must respect.",
         when: "When this round discovered a limit that was not known before.",
         nature: "report",
         decision: "You discovered a limit later rounds must respect",
-        promptLevels: ["l0", "l1", "l2"],
+        compact: true,
         promptRank: 20,
-        downstream: "Merged into the active constraint set by the compiler (bounded per round).",
+        downstream: "Merged into the active constraint set by the compiler; entries over " +
+            "max_discovered_constraints_per_round are diagnosed and dropped at the " +
+            "submission boundary.",
         toolDescription: "New constraints that must apply to later rounds. This is the ONLY " +
             "promotion channel for a worker-discovered constraint: a worker result " +
             "stays a report until the main agent states the constraint here.",
     },
     {
         path: "wrong_assumptions",
+        array: true,
         purpose: "Assumptions from earlier rounds that this round falsified.",
         when: "When evidence proved an earlier assumption wrong; omit when none.",
         nature: "report",
         decision: "Evidence falsified an earlier assumption",
-        promptLevels: ["l0", "l1", "l2"],
+        compact: true,
         promptRank: 30,
-        downstream: "State-file 'Corrected assumption', recovery brief, and backtrack wrong-assumption facts.",
+        downstream: "Bounded Working Memory (fresh prompts and the committed projection), " +
+            "recovery brief, replay and explain. Only committed reports reach the " +
+            "next prompt.",
         toolDescription: "Assumptions from earlier rounds that turned out to be wrong. Record one " +
             "only when this round actually falsified it; otherwise omit. This is not " +
             "a reflection quota.",
     },
     {
-        path: "objective_refinement",
-        purpose: "A deeper or more accurate understanding of the objective.",
-        when: "When this round changed your understanding of what the task needs.",
+        path: "open_questions",
+        array: true,
+        purpose: "Unresolved questions that still affect later slices (a question list, " +
+            "not a todo list).",
+        when: "Only when a real open question affects how later work should proceed; " +
+            "omit when none.",
         nature: "report",
-        downstream: "Appended to the objective with a version bump; never replaces the original objective.",
-        toolDescription: "Optional. A refinement or deepening of the task objective based on this " +
-            "round's discoveries. Appended, never substituted for the original goal.",
+        reportOnly: true,
+        decision: "A question remains open that later slices must resolve",
+        compact: true,
+        promptRank: 35,
+        downstream: "Bounded Working Memory (fresh prompts and the committed projection), " +
+            "replay and explain. Strictly report-only: it never enters the " +
+            "verification gate, success, contract closure or machine evidence.",
+        toolDescription: "Optional. At most 3 unresolved questions, 300 chars each. Record only " +
+            "questions that still affect later slices — not a todo list, not a " +
+            "completion checklist, and not a substitute for a blocker or decision. " +
+            "Report-only: LoopForge never acts on these entries.",
     },
     {
-        path: "retracted_constraints",
-        purpose: "Existing constraints that are no longer correct or relevant.",
-        when: "When a prior constraint is proven wrong or obsolete.",
+        path: "resolved_open_question_ids",
+        array: true,
+        purpose: "Open-question ids that this round resolved.",
+        when: "When a previously rendered open question is no longer unresolved.",
         nature: "report",
-        downstream: "Retired from the active set (with the configured retirement window for plan/hard constraints).",
-        toolDescription: "Optional. Constraints the agent now believes are wrong or irrelevant, by " +
-            "c-XXXXXXXX id or exact text. Omit when none.",
+        reportOnly: true,
+        decision: "A rendered open question was resolved",
+        compact: true,
+        promptRank: 36,
+        downstream: "Working Memory removes the cited question; replay and explain retain the report.",
+        toolDescription: "Optional. Use only stable oq-... ids rendered beside open questions in " +
+            "Working Memory or the state file. Report-only; it never changes the " +
+            "verification gate or acceptance criteria.",
     },
     {
-        path: "revised_success_criteria",
-        purpose: "Success criteria that need reformulation.",
-        when: "When the original criterion was incorrect or unmeasurable.",
+        path: "retracted_constraints",
+        array: true,
+        purpose: "Existing constraints that are no longer correct or relevant.",
+        when: "When a prior constraint is proven wrong or obsolete.",
         nature: "report",
-        downstream: "Applied to the Loop Objective with a version bump.",
-        toolDescription: "Optional. Success criteria that need reformulation: each entry has the " +
-            "old and new wording.",
+        downstream: "Only active Agent-discovered constraints (including recovery-preserved " +
+            "discoveries) are retractable, by c-XXXXXXXX id or normalized-exact text. " +
+            "Operator criteria/hard constraints and plan constraints are rejected. " +
+            "Unknown/inactive targets are no-ops with a diagnostic.",
+        toolDescription: "Optional. Active Agent-discovered constraints that are no longer valid, " +
+            "by c-XXXXXXXX id or exact text. Operator criteria/hard constraints and " +
+            "plan constraints cannot be retracted. Omit when none.",
     },
     {
         path: "round_contract",
-        purpose: "A proposal for the NEXT round's evidence-bound contract.",
-        when: "When no contract is active and a contract command is available; while a " +
-            "contract is open, omit it (or restate it unchanged) unless this round " +
-            "closes it and declares a successor.",
+        purpose: "THE contract channel: the NEXT round's bounded deliverable and its " +
+            "acceptance conditions.",
+        when: "When contract coverage requires a next-round contract, or when you want " +
+            "to start or replace a slice. With after-capable commands, a continuing " +
+            "round with a successor available must leave an active contract; omit to " +
+            "continue the current one. The final configured round has no successor.",
         nature: "proposal",
-        decision: "No active contract: if the next slice is machine-checkable, declare it",
+        decision: "The Agent decides the next slice; LoopForge only validates the declaration",
         downstream: "Becomes active only after this round commits; item ids rci-XXXXXXXX are " +
-            "derived by the runtime.",
-        toolDescription: "Proposal for the NEXT round's contract (items + verify_with + scope). " +
-            "Declared here, it becomes the ACTIVE contract only after this round " +
-            "commits. While it is open, omitting it continues the contract; a " +
-            "different proposal is ignored (contract_premature). DECLARATION IS " +
-            "STRICT: an item with no bound command, an unknown/disabled command, a " +
-            "scope entry outside the workspace, a malformed reference, or a count " +
-            "over the limits returns contract_invalid.",
+            "derived by the runtime. `scope` is a report-only intent statement and " +
+            "never rejects or blocks a round. `supersedes` closes the named ACTIVE " +
+            "contract as `superseded` and activates this proposal next round.",
+        toolDescription: "THE contract channel for the NEXT round. work_item is the bounded " +
+            "deliverable this slice produces (an outcome, not an activity) and is " +
+            "required for a new proposal. items are acceptance conditions; each item " +
+            "binds its own verify_with commands and may cite cr- ids in " +
+            "criterion_refs. scope is an OPTIONAL, report-only declaration of " +
+            "intended files — it is not enforced and is not part of the rc- id. " +
+            "While a contract is open, omit this field to continue it unchanged. To " +
+            "replace the active slice, add supersedes { contract_id, reason? } with " +
+            "the active rc- id and different acceptance items. If the active " +
+            "contract closes this round and a successor is available, a successor " +
+            "is REQUIRED. The final configured round has no successor consumer. " +
+            "DECLARATION IS STRICT: a missing work_item, an item with no bound " +
+            "command, an unknown/disabled command, a malformed reference, an " +
+            "unknown field, or a count over the limits returns contract_invalid.",
     },
     {
         path: "worker_results",
+        array: true,
         purpose: "Results of sub-agent / worker delegations.",
         when: "Only when work was actually delegated.",
         nature: "report",
         decision: "You delegated work",
-        promptLevels: ["l1", "l2"],
+        compact: true,
         promptRank: 50,
-        downstream: "Saved with its source and written to the delegation journal; worker " +
-            "discoveredConstraints is NOT auto-promoted.",
+        downstream: "Saved inside the committed transaction as an audit report. A worker " +
+            "finding is not auto-promoted.",
         toolDescription: "Optional. Results of sub-agent / Worker delegations this round. Each " +
             "entry must declare an outcome. Entries without a valid outcome are " +
-            "dropped with a diagnostic. A worker's discoveredConstraints stays in " +
-            "this report; to make it a global constraint, submit it in top-level " +
-            "discovered_constraints.",
+            "dropped with a diagnostic. To make a worker finding a global " +
+            "constraint, submit it in top-level discovered_constraints.",
         reportOnly: true,
     },
     {
-        path: "prompt_requests",
-        purpose: "Information needs for the next round's prompt.",
-        when: "When you know what context the next round will need.",
-        nature: "control",
-        decision: "You know what the next prompt needs",
-        promptLevels: ["l1", "l2"],
-        promptRank: 70,
-        downstream: "Matched exactly against state items; applied to the next prompt only " +
-            "(L0 ignores it). Unmatched entries have no effect.",
-        toolDescription: "Optional. Information needs for the NEXT prompt. emphasize entries are " +
-            "matched by stable id or normalized-exact text; a paraphrase matches " +
-            "nothing. confusion_points are echoed at the top. L0 retry prompts ignore " +
-            "both arms. This never becomes long-term knowledge.",
-    },
-    {
-        path: "compression_checkpoint",
+        path: "subtask_boundary",
         purpose: "Mark a meaningful work boundary.",
-        when: "At a phase/subtask boundary worth a full-state milestone.",
+        when: "At a subtask boundary that warrants an L2 rehydration.",
         nature: "report",
-        decision: "This round reached a real phase boundary; pair with checkpoint_label",
-        promptLevels: ["l1", "l2"],
+        decision: "This round reached a real phase boundary; pair with subtask_boundary_label",
+        compact: true,
         promptRank: 60,
-        downstream: "Creates an agent-declared milestone and forces an L2 rehydration boundary.",
-        toolDescription: "Optional. true at a subtask boundary to create a recoverable milestone " +
-            "and force a full-state checkpoint. Pair with checkpoint_label.",
+        downstream: "Forces an L2 rehydration boundary. It creates no milestone or phase narrative.",
+        toolDescription: "Optional. true at a subtask boundary to force an L2 rehydration boundary. " +
+            "Pair with subtask_boundary_label.",
     },
     {
-        path: "checkpoint_label",
-        purpose: "A human-readable label for the checkpoint.",
-        when: "Only together with compression_checkpoint=true.",
+        path: "subtask_boundary_label",
+        purpose: "A human-readable label for the subtask boundary.",
+        when: "Only together with subtask_boundary=true.",
         nature: "report",
-        downstream: "Milestone heading in later prompts and the state file.",
-        toolDescription: "Optional. Short label for the checkpoint (for example " +
-            "'core-model-complete'). Meaningful only when compression_checkpoint=true.",
+        downstream: "Stored on the committed report; it does not create a later prompt heading.",
+        toolDescription: "Optional. Short label for the subtask boundary (for example " +
+            "'core-model-complete'). Meaningful only when subtask_boundary=true.",
     },
     {
         path: "retroactiveClaims",
+        array: true,
         purpose: "A claim that an earlier round satisfied a criterion.",
         when: "When you can point at an earlier round's evidence.",
         nature: "claim",
@@ -293,6 +337,7 @@ const GUIDES = [
     },
     {
         path: "gate_ids",
+        array: true,
         purpose: "Approved gate ids this round's work depended on.",
         when: "Only when policy.gate.enabled is true and an approval was actually obtained.",
         nature: "control",
@@ -301,34 +346,16 @@ const GUIDES = [
             "Enforced only when policy.gate.enabled: a cited, unapproved gate rejects " +
             "the round. Without the gate layer this is saved but has no effect.",
     },
-    {
-        path: "outcome",
-        purpose: "The declared round outcome.",
-        when: "When the round is partial, failed, or blocked (success is derivable).",
-        nature: "claim",
-        downstream: "Wins over `success` for the stop decision and success-class checks.",
-        toolDescription: "Optional. success | partial | failed | blocked. When absent, derived " +
-            "from success. A declared non-success outcome suppresses the " +
-            "success-class checks even when success=true.",
-    },
     {
         path: "blocker",
         purpose: "A concrete description of what blocks the work.",
-        when: "Required when outcome=blocked; useful with stop_reason=blocked.",
+        when: "Required when outcome=blocked; ignored (with a diagnostic) otherwise.",
         nature: "report",
-        downstream: "Stop decision, handoff open risks, and gate classification when enabled.",
-        toolDescription: "Optional. A flat blocker description, required when outcome=blocked. " +
-            "State what cannot proceed and why; do not use it as a substitute for " +
-            "`success=false`.",
-    },
-    {
-        path: "stop_reason",
-        purpose: "Why the agent is stopping.",
-        when: "Only when should_continue=false and success=false.",
-        nature: "control",
-        downstream: "blocked/needs_human_input stop without claiming success; gave_up is the default stop behavior.",
-        toolDescription: "Optional. Why the agent is stopping: gave_up | blocked | needs_human_input. " +
-            "Only meaningful when should_continue=false and success=false.",
+        downstream: "Stop reason, blocked-contract closure, and gate classification when enabled. " +
+            "When work needs human input, say so here with outcome=blocked.",
+        toolDescription: "Required when outcome=blocked (trim non-empty, at most 500 chars). State " +
+            "what cannot proceed and why. When another outcome is declared it is " +
+            "dropped with a diagnostic and never rejects the round.",
     },
     {
         path: "no_change_reason",
@@ -343,13 +370,31 @@ const GUIDES = [
     },
 ];
 const GUIDE_BY_PATH = new Map(GUIDES.map((guide) => [guide.path, guide]));
+/** v4.0.3: array-valued evaluation paths, derived from the SAME field
+ *  metadata the prompt, MCP schema and receipts read. Field accounting uses
+ *  this set instead of a second hardcoded list. */
+export const ARRAY_SELF_EVALUATION_FIELDS = new Set(GUIDES.filter((guide) => guide.array === true).map((guide) => guide.path));
 /** Fields that existed in earlier releases and are now unknown. A diagnostic
  *  for one of these names explains the removal instead of silently dropping. */
 const RETIRED_FIELDS = {
     progress_estimate: "removed in 3.9.0 — progress is machine-derived; remove this field",
     progress_at_boundary: "removed in 3.9.0 — milestones render a round range, not a percentage",
-    success_criteria_remaining: "removed in 3.8 — report criterion claims under execution_report.criterion_claims",
+    success_criteria_remaining: "removed in 3.8 — report criterion claims under execution_report.claims",
     next_action: "removed in 3.8 — the agent plans; LoopForge does not accept a next-action field",
+    revised_success_criteria: "removed in 3.9.6 — operator acceptance is immutable; report a conflict in " +
+        "wrong_assumptions or stop with outcome=blocked/needs_human_input",
+    prompt_requests: "removed in 4.0.1 — the next prompt is compiled from committed facts; " +
+        "there is no per-round prompt-steering channel",
+    success: "removed in 4.0.6 — use `outcome` (success | partial | failed | blocked)",
+    agent_stop_reason: "removed in 4.0.6 — use outcome=blocked with `blocker`; stop with " +
+        "outcome=failed and should_continue=false",
+    contract_transition: "removed in 4.0.6 — use round_contract.supersedes { contract_id, reason? }",
+    tests_reported: "removed in 4.0.6 — command observations are the test fact; do not report counts",
+    criterion_claims: "removed in 4.0.6 — use execution_report.claims with cr- ids",
+    contract_item_claims: "removed in 4.0.6 — use execution_report.claims with rci- ids",
+    "execution_report.tests_reported": "removed in 4.0.6 — command observations are the test fact; remove tests_reported",
+    "execution_report.criterion_claims": "removed in 4.0.6 — move these claims into execution_report.claims with cr- ids",
+    "execution_report.contract_item_claims": "removed in 4.0.6 — move these claims into execution_report.claims with rci- ids",
 };
 export function fieldGuide(path) {
     return GUIDE_BY_PATH.get(path);
@@ -375,24 +420,21 @@ function firstActiveSubGoal(subGoals) {
  *  never invents an sg-/rci- reference. */
 export function fieldExample(path, ctx) {
     switch (path) {
-        case "success": return false;
+        case "outcome": return "partial";
         case "output_summary": return "<what was done and how it was verified>";
         case "constraint_violations": return [];
         case "should_continue": return true;
         case "execution_report.files_changed":
             return ["<path whose content or type differs from round start>"];
-        case "execution_report.tests_reported":
-            return { passed: 0, failed: 0, skipped: 0 };
-        case "execution_report.contract_item_claims": {
+        case "execution_report.claims": {
             const item = firstActiveItem(ctx.activeContract);
-            return item ? [{ item_id: item.id, outcome: "met" }] : null;
-        }
-        case "execution_report.criterion_claims": {
+            if (item)
+                return [{ id: item.id, outcome: "met" }];
             const criterion = ctx.criteria?.[0];
-            return criterion
-                ? [{ criterion_id: criterion.id, outcome: "met" }]
-                : null;
+            return criterion ? [{ id: criterion.id, outcome: "met" }] : null;
         }
+        case "objective_refinement":
+            return "<the overall objective as it now stands>";
         case "subgoal_updates": {
             const subGoal = firstActiveSubGoal(ctx.activeSubGoals);
             return subGoal ? [{ id: subGoal.id, status: "done" }] : null;
@@ -403,58 +445,47 @@ export function fieldExample(path, ctx) {
             return ["<a constraint later rounds must respect>"];
         case "wrong_assumptions":
             return ["<an assumption from an earlier round that was falsified>"];
-        case "objective_refinement":
-            return "<what you now understand better about the objective>";
+        case "open_questions":
+            return ["<an unresolved question that still affects later slices>"];
+        case "resolved_open_question_ids":
+            return ["oq-<stable id rendered for a question>"];
         case "retracted_constraints":
             return ["<constraint text or c-XXXXXXXX id that is no longer valid>"];
-        case "revised_success_criteria":
-            return [{ old: "<old criterion>", new: "<new criterion>" }];
         case "round_contract": {
             if (!ctx.contractVerificationAvailable || ctx.commands.length === 0)
                 return null;
             return {
-                work_item: "<the next slice, in one line>",
+                work_item: "<bounded deliverable this slice produces>",
                 items: [{
-                        description: "<machine-checkable outcome for the next slice>",
+                        description: "<machine-checkable acceptance condition>",
                         criterion_refs: [],
-                        subgoal_refs: [],
                         verify_with: [ctx.commands[0]],
                     }],
-                scope: ["<workspace-relative file or directory>"],
             };
         }
         case "worker_results":
             return [{
                     agentId: "<worker id>",
-                    subAgentType: "general-purpose",
                     subTask: "<self-contained subtask you delegated>",
                     resultSummary: "<what the worker reported>",
                     outcome: "success",
-                    discoveredConstraints: [],
                 }];
-        case "prompt_requests":
-            return {
-                emphasize: ["<exact constraint text or stable id>"],
-                confusion_points: ["<what is unclear about the current state>"],
-            };
-        case "compression_checkpoint": return false;
-        case "checkpoint_label": return "<short phase label>";
+        case "subtask_boundary": return false;
+        case "subtask_boundary_label": return "<short phase label>";
         case "retroactiveClaims":
             return [{ round: 1, claim: "<what that earlier round satisfied>" }];
         case "gate_ids":
             return ["<approved gateId from loopforge_gate_check>"];
-        case "outcome": return "partial";
         case "blocker": return "<what cannot proceed and why>";
-        case "stop_reason": return "blocked";
         case "no_change_reason": return "<why no workspace change was needed>";
         default: return null;
     }
 }
-/** Semantic applicability — independent of prompt density. Core fields and
- *  the two baseline execution-report fields are always applicable; the rest
- *  depend on facts the runtime can actually observe. Future events
- *  (delegation, a checkpoint boundary, a falsified assumption) remain
- *  conditional opportunities, not render-time facts. */
+/** Semantic applicability — the ONE rule, deliberately independent of prompt
+ *  level. Core fields and the two baseline execution-report fields are always
+ *  applicable; the rest depend on facts the runtime can actually observe.
+ *  Future events (delegation, a subtask boundary, a falsified assumption)
+ *  remain conditional opportunities, not render-time facts. */
 export function isFieldApplicable(path, facts) {
     const guide = GUIDE_BY_PATH.get(path);
     if (!guide)
@@ -463,21 +494,18 @@ export function isFieldApplicable(path, facts) {
         return true;
     switch (path) {
         case "execution_report.files_changed":
-        case "execution_report.tests_reported":
             return true;
-        case "execution_report.contract_item_claims":
-            return facts.activeContract !== null;
-        case "execution_report.criterion_claims":
-            return (facts.criteria ?? []).length > 0;
+        case "execution_report.claims":
+            return facts.activeContract !== null || (facts.criteria ?? []).length > 0;
+        case "objective_refinement":
+            return true;
         case "subgoal_updates":
             return firstActiveSubGoal(facts.subGoals) !== null;
         case "round_contract":
-            // A first declaration needs no active contract and a usable command.
-            // While a contract is open, the dedicated active-contract block carries
-            // the successor instruction instead of a competing proposal example.
-            return facts.activeContract === null &&
-                facts.contractVerificationAvailable &&
-                facts.commands.length > 0;
+            // v4.0.6: the contract channel is usable whenever a contract can be
+            // verified. The dedicated contract block decides REQUIRED vs continue vs
+            // redirect for the current facts.
+            return facts.contractVerificationAvailable && facts.commands.length > 0;
         case "gate_ids":
             return facts.gateEnabled;
         case "no_change_reason":
@@ -486,13 +514,14 @@ export function isFieldApplicable(path, facts) {
             return true;
     }
 }
-/** Prompt density is a separate decision: which applicable fields the compact
- *  trigger checklist renders at this level. */
+/** Compact-checklist membership: the explicit `compact` marker plus semantic
+ *  applicability. The level is deliberately absent — L0/L1/L2 offer the same
+ *  evaluation fields; only state density changes. Dedicated renderer fields
+ *  (`round_contract`, `subgoal_updates`) are never compact members, so they
+ *  cannot duplicate their own blocks. */
 export function isFieldPrompted(path, facts) {
     const guide = GUIDE_BY_PATH.get(path);
-    if (!guide?.decision || !guide.promptLevels)
-        return false;
-    if (!guide.promptLevels.includes(facts.level))
+    if (!guide?.compact)
         return false;
     return isFieldApplicable(path, facts);
 }
@@ -508,10 +537,23 @@ function statusOfItem(itemId, statuses) {
 }
 function renderContractGuidance(ctx) {
     const contract = ctx.activeContract;
+    const hasCommand = ctx.contractVerificationAvailable && ctx.commands.length > 0;
+    // v4.0.6: coverage guidance uses the SAME shared rule as the submission
+    // boundary and the post-evidence gate. `proposalPresent:false` describes
+    // this prompt (no next-round proposal has been committed yet).
+    const requirement = deriveContractRequirement({
+        shouldContinue: true,
+        blocked: false,
+        proposalPresent: false,
+        activeContract: contract,
+        closure: ctx.itemStatuses?.closure ?? "open",
+        contractCapability: hasCommand,
+        successorRoundAvailable: ctx.maxRounds === undefined || ctx.round < ctx.maxRounds,
+    });
     if (contract) {
         const lines = [
-            "Active Round Contract — continue it; you do NOT need to restate it:",
-            `- ${contract.work_item ? `${contract.work_item} ` : ""}(${contract.id})`,
+            "Active Round Contract — it governs this round:",
+            `- Deliverable: ${contract.work_item ?? "(not named; legacy contract)"} (${contract.id})`,
         ];
         const shown = contract.items.slice(0, 5);
         for (const item of shown) {
@@ -522,37 +564,52 @@ function renderContractGuidance(ctx) {
         if (contract.items.length > shown.length) {
             lines.push(`  - … and ${contract.items.length - shown.length} more in the Current Task.`);
         }
-        const claimDecision = GUIDE_BY_PATH.get("execution_report.contract_item_claims")?.decision
-            ?? "Claim completed items of the active contract with their real rci- ids";
-        lines.push(`${claimDecision} via \`execution_report.contract_item_claims\`.`, "A claim alone leaves an item insufficient; its bound command must be observed", "passing. Omit `round_contract` to continue this contract; a different proposal", "is ignored (contract_premature). If this round closes the contract and another", "slice follows, declare the successor proposal here.");
+        const claimDecision = GUIDE_BY_PATH.get("execution_report.claims")?.decision
+            ?? "Claim criteria or active contract items with their real cr-/rci- ids";
+        lines.push(`${claimDecision} via \`execution_report.claims\`.`, "A claim alone leaves an item insufficient; its bound command must be observed", "passing. Omit `round_contract` to CONTINUE this contract unchanged — a", "different proposal without `supersedes` is rejected as contract_premature.", "To replace this slice, add `round_contract.supersedes` with", `{ contract_id: "${contract.id}" } and DIFFERENT acceptance items in the`, "same proposal. The old contract closes as superseded, its unverified items", "remain in the audit record, the workspace is not restored, and this round", "cannot be completed.", "`scope` is your declared intent — a report, not permission. It is not", "enforced and it is not part of the rc- id.");
+        if (requirement.reason === "no_contract_capability") {
+            lines.push("No enabled after-capable command is configured now, so this contract's", "items cannot be machine-verified this round and no successor is required.");
+        }
+        else if (requirement.reason === "no_successor_round") {
+            lines.push("This is the final configured round. Do not submit a successor " +
+                "round_contract; there is no next round to consume it.");
+        }
+        else if (requirement.reason === "active_contract_closed") {
+            lines.push("This contract is already closed. If you continue, a successor", "`round_contract` is REQUIRED for the next round.");
+        }
+        else {
+            lines.push("If this round closes the contract (every item verified) and you continue,", "a successor `round_contract` is REQUIRED for the next round.");
+        }
         return lines;
     }
-    if (!ctx.contractVerificationAvailable || ctx.commands.length === 0) {
+    if (requirement.reason === "no_contract_capability") {
         return [
-            "No enabled after-capable evidence command is configured. Contract items cannot",
-            "be machine-verified, so run without a contract and do not declare items.",
+            "No enabled after-capable evidence command is configured — no contract is possible.",
+            "If the OVERALL starting objective genuinely evolved, submit `objective_refinement`.",
+        ];
+    }
+    if (requirement.reason === "no_successor_round") {
+        return [
+            "This is the final configured round. Do not submit `round_contract`;",
+            "there is no successor round to consume a proposal.",
         ];
     }
     const commands = ctx.commands.slice(0, 3).join(", ");
-    const proposalDecision = GUIDE_BY_PATH.get("round_contract")?.decision
-        ?? "No active contract: if the next slice is machine-checkable, declare it";
+    const example = fieldExample("round_contract", {
+        activeContract: null,
+        activeSubGoals: ctx.subGoals,
+        commands: [...ctx.commands],
+        contractVerificationAvailable: true,
+        criteria: ctx.criteria,
+    });
     return [
-        `${proposalDecision} → proposal below:`,
+        "No active Round Contract. If you continue, one is REQUIRED for the next",
+        "round. You decide the slice and acceptance conditions; LoopForge validates",
+        "structure, references and command bindings. Legal shape:",
         "```json",
-        JSON.stringify({
-            round_contract: {
-                work_item: "<next slice, one line>",
-                items: [{
-                        description: "<machine-checkable outcome>",
-                        criterion_refs: [],
-                        subgoal_refs: [],
-                        verify_with: [ctx.commands[0]],
-                    }],
-                scope: ["<workspace-relative path>"],
-            },
-        }, null, 1),
+        JSON.stringify({ round_contract: example }, null, 1),
         "```",
-        `Usable commands: ${commands}. The proposal activates only after this round commits.`,
+        `Usable commands: ${commands}.`,
     ];
 }
 function renderSubGoalGuidance(ctx) {
@@ -593,7 +650,6 @@ function criteriaDetailLines(criteria) {
  *  per-field shapes remain in `submission_guidance`. */
 function renderCompactTriggers(ctx) {
     const facts = {
-        level: ctx.level,
         activeContract: ctx.activeContract,
         itemStatuses: ctx.itemStatuses,
         subGoals: ctx.subGoals,
@@ -615,37 +671,71 @@ function renderCompactTriggers(ctx) {
         if (!guide?.decision)
             continue;
         lines.push(`- ${guide.decision} → \`${path}\` → ${guide.downstream}`);
-        if (path === "execution_report.criterion_claims") {
+        if (path === "execution_report.claims") {
             lines.push(...criteriaDetailLines(ctx.criteria ?? []));
         }
     }
     return lines;
 }
-function renderFlagGuidance(flags, criteria = []) {
+/** Verification flags name the concrete evaluation field, which is often the
+ *  dotted path the Agent must fill. Normalize the legacy short names before
+ *  the guidance lookup so the prompt always names the real field. */
+const FLAG_FIELD_PATHS = {
+    files_changed: "execution_report.files_changed",
+    claims: "execution_report.claims",
+    criterion_claims: "execution_report.claims",
+    contract_item_claims: "execution_report.claims",
+};
+function flagFieldPath(field) {
+    return FLAG_FIELD_PATHS[field] ?? field;
+}
+function renderFlagGuidance(flags, criteria = [], level = "l1") {
     if (flags.length === 0)
         return [];
-    const fields = [...new Set(flags.map((flag) => flag.field).filter(Boolean))];
+    const fields = [
+        ...new Set(flags.map((flag) => flagFieldPath(flag.field)).filter(Boolean)),
+    ];
     const lines = [
-        "This submission is a retry or recovery. The previous findings name these fields:",
+        "Previous machine findings name these fields:",
         ...fields.slice(0, 8).map((field) => {
             const guide = GUIDE_BY_PATH.get(field);
             return `- \`${field}\`${guide ? ` — ${guide.purpose}` : ""}`;
         }),
     ];
-    const criterionFinding = flags.some((flag) => flag.field === "execution_report.criterion_claims" ||
+    // L0's Verification Gate deliberately stays compact and carries no action
+    // continuation. The evaluation block is the Agent's composition surface,
+    // so the concrete action belongs here. L1/L2 already render it once in the
+    // gate; do not duplicate it.
+    if (level === "l0") {
+        const actions = new Map();
+        for (const flag of flags) {
+            if (flag.severity === "info" || actions.has(flag.check))
+                continue;
+            actions.set(flag.check, {
+                label: flag.severity === "error" ? "Fix" : "Action",
+                action: verificationActionFor(flag.check),
+            });
+            if (actions.size >= 3)
+                break;
+        }
+        for (const [check, entry] of actions) {
+            lines.push(`  → ${entry.label}: ${entry.action} [${check}]`);
+        }
+    }
+    const criterionFinding = flags.some((flag) => flag.field === "execution_report.claims" ||
         flag.field === "criterion_claims" ||
         flag.check === "criteria_claims_unverified" ||
         flag.check === "success_with_remaining_criteria");
     if (criterionFinding && criteria.length > 0) {
         lines.push(...criteriaDetailLines(criteria));
     }
-    lines.push("Correct the relevant field(s) in the same round. If this attempt falsified an", "earlier assumption, record it in `wrong_assumptions`; otherwise omit it.");
+    lines.push("Correct the relevant field(s) in this round if the finding still applies.", "If this attempt falsified an earlier assumption, record it in", "`wrong_assumptions`; otherwise omit it.");
     return lines;
 }
 /** Render the evaluation block appended to every prompt. */
 export function renderSelfEvalBlock(ctx) {
     const base = {
-        success: false,
+        outcome: "partial",
         output_summary: "<what was done and how it was verified>",
         constraint_violations: [],
         should_continue: true,
@@ -667,26 +757,25 @@ export function renderSelfEvalBlock(ctx) {
         "```json",
         JSON.stringify(base, null, 2),
         "```",
-        "Add the execution report when the round changed files or ran tests:",
+        "Add the execution report when files changed or you claim items:",
         "```json",
         JSON.stringify({
             execution_report: {
                 files_changed: fieldExample("execution_report.files_changed", reportCtx),
-                tests_reported: fieldExample("execution_report.tests_reported", reportCtx),
+                claims: fieldExample("execution_report.claims", reportCtx) ?? [],
             },
         }, null, 1),
         "```",
-        "`files_changed` is the net boundary change from round start (content or",
-        "file type), including deletions. A commit alone adds no entry when content",
-        "is unchanged. Do not list gitignored paths merely to look complete.",
+        "`files_changed` is the net change from round start, including deletions.",
+        "A commit alone adds nothing; gitignored paths are outside the machine boundary.",
     ];
     lines.push(...renderCompactTriggers(ctx));
     lines.push(...renderContractGuidance(ctx));
     lines.push(...renderSubGoalGuidance(ctx));
     if (ctx.recovery || ctx.verificationFlags.length > 0) {
-        lines.push(...renderFlagGuidance(ctx.verificationFlags, ctx.criteria ?? []));
+        lines.push(...renderFlagGuidance(ctx.verificationFlags, ctx.criteria ?? [], ctx.level));
     }
-    lines.push("Never invent an id. Use only ids rendered in this prompt or", "`submission_guidance`; when an id is absent, omit the field rather than", "writing a placeholder id.");
+    lines.push("Never invent an id; use only ids rendered here or in `submission_guidance`", "and omit the field when an id is absent.");
     return lines.join("\n");
 }
 function activeSubGoals(subGoals) {
@@ -701,29 +790,31 @@ export function deriveSubmissionGuidance(session, options) {
     const commandNames = capability.commands
         .filter((command) => command.enabled)
         .map((command) => command.commandId);
-    const level = session.currentLevel === "l0" || session.currentLevel === "l1" ||
-        session.currentLevel === "l2"
-        ? session.currentLevel
-        : (session.roundSnapshot?.promptArtifact?.level ??
-            session.lastCompileResponse?.prompt_artifact?.level ?? "l2");
-    const subGoals = session.lastCompileResponse?.sub_goals ??
-        deriveSubGoals({
-            loopId: session.loopId,
-            currentRound: session.currentRound,
-            rounds: options.rounds,
-        });
+    // Never invent a prompt level. If no held artifact is observable, the
+    // level is unknown; the prompt itself is derived from current facts.
+    const level = session.roundSnapshot?.promptArtifact?.level ?? null;
+    const subGoals = deriveSubGoals({
+        loopId: session.loopId,
+        currentRound: session.currentRound,
+        rounds: options.rounds,
+    });
     const facts = deriveRoundFacts({
         rounds: options.rounds,
         currentRound: session.currentRound,
         inFlight: NO_IN_FLIGHT_ROUND,
-        subGoals,
         commands: commandsPolicy,
     });
     const activeContract = facts.activeContract;
     const itemStatuses = facts.itemStatuses;
-    const criteria = session.lastCompileResponse?.criterion_statuses ?? [];
+    const criteria = options.objective
+        ? deriveCriterionStatuses({
+            rounds: options.rounds,
+            currentRound: session.currentRound,
+            objective: options.objective,
+            criterionFacts: facts.criterionFacts,
+        })
+        : [];
     const guidanceFacts = {
-        level,
         activeContract,
         itemStatuses,
         subGoals,
@@ -739,16 +830,36 @@ export function deriveSubmissionGuidance(session, options) {
         contractVerificationAvailable: capability.contractVerificationAvailable,
         criteria,
     };
-    const artifact = session.roundSnapshot?.promptArtifact ??
-        session.lastCompileResponse?.prompt_artifact;
-    const roundId = session.roundSnapshot?.roundId ??
-        `loop:${session.loopId}:round:${session.currentRound}`;
+    const artifact = session.roundSnapshot?.promptArtifact;
     return {
-        round_id: roundId,
+        contract_requirement: (() => {
+            const requirement = deriveContractRequirement({
+                shouldContinue: true,
+                blocked: false,
+                proposalPresent: false,
+                activeContract,
+                closure: itemStatuses.closure,
+                contractCapability: capability.contractVerificationAvailable,
+                successorRoundAvailable: session.maxRounds === undefined || session.currentRound < session.maxRounds,
+            });
+            return {
+                required_on_continue: requirement.required,
+                successor_required_if_closed: activeContract !== null && capability.contractVerificationAvailable &&
+                    session.currentRound < (session.maxRounds ?? Number.POSITIVE_INFINITY),
+                reason: requirement.reason === "active_contract_closed" ||
+                    requirement.reason === "active_contract_continues" ||
+                    requirement.reason === "no_contract_capability" ||
+                    requirement.reason === "no_successor_round"
+                    ? requirement.reason
+                    : "no_active_contract",
+                active_contract_id: activeContract?.id ?? null,
+            };
+        })(),
         active_contract: activeContract
             ? {
                 id: activeContract.id,
                 ...(activeContract.work_item ? { work_item: activeContract.work_item } : {}),
+                scope: [...activeContract.scope],
                 declared_at_round: activeContract.declared_at_round,
                 items: activeContract.items.map((item) => ({
                     id: item.id,
@@ -770,13 +881,7 @@ export function deriveSubmissionGuidance(session, options) {
             text: criterion.text,
             status: criterion.status,
         })),
-        recovery: options.recovery ?? (session.backtrackTargetGitHead
-            ? {
-                required: true,
-                restore_point: Math.max(1, session.currentRound - 1),
-                target_head: session.backtrackTargetGitHead,
-            }
-            : null),
+        recovery: options.recovery ?? null,
         prompt: {
             level,
             dropped_sections: [...(artifact?.droppedSections ?? [])],
@@ -798,6 +903,7 @@ export function deriveSubmissionGuidance(session, options) {
             check: flag.check,
             severity: flag.severity,
             detail: flag.detail,
+            ...(flag.ref ? { ref: flag.ref } : {}),
         })),
     };
 }