@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/builtin/shared-prompts.ts

@@ -1,116 +1,163 @@
+/**
+ * Steering propagation is a whole-repository pattern, not a per-workflow
+ * option: every builtin stage prompt carries STEERING_PROPAGATION_CONTRACT
+ * through `withSteeringPropagation`, and `test/unit/builtin-workflow-steering-propagation.test.ts`
+ * fails when a stage prompt omits it.
+ *
+ * A run's contract can change mid-flight, but only the user may change it. A
+ * steered amendment that stays inside one stage's session is invisible to every
+ * later stage, so the implementer builds to the amended contract while reviewers
+ * still score the launch contract and mark the added work as unrequested scope.
+ * Each stage therefore restates the amendments it received in its own handoff.
+ */
+export const STEERING_PROPAGATION_CONTRACT = [
+  "Steering propagation contract:",
+  "- Mid-run user messages (steering, follow-ups, resume text) are authoritative and may amend this run's objective or acceptance criteria. Adopt an amendment as required behavior from the moment you receive it.",
+  "- An amendment that stays in your session is lost. Restate every objective-relevant steering message in your final report or handoff artifact, verbatim when short, under an explicit `Contract amendments received` heading.",
+  "- Keep user-authored amendments visibly separate from your own observations, so later stages can tell a required clause from an agent proposal.",
+  "- Treat amendments inherited from an upstream stage as contract clauses. Cover them in acceptance and traceability work; never classify inherited user amendments as beyond_objective, unrequested scope, or speculative expansion.",
+  "- If an amendment is ambiguous, or conflicts with the launch contract or another amendment, resolve it before implementing: ask through `intercom` when a supervisor or originating stage is reachable, otherwise state the conflict in your report and implement the narrowest reading consistent with the launch contract.",
+  "- Propagate nothing else this way. Guidance about how to work, tool preferences, and your own improvement ideas are not amendments; those follow the scope discipline contract.",
+].join("\n");
+
+/**
+ * Add the steering propagation contract to a stage prompt. Builtin runners wrap
+ * every `ctx.task` / `ctx.parallel` / `ctx.chain` prompt with this so the pattern
+ * cannot be forgotten when a stage is added.
+ *
+ * Stage prompts in this package deliberately end with their `<instruction>`
+ * section, which carries the strongest positional weight. The contract is
+ * inserted immediately before that closing section rather than after it, so a
+ * stage's final words remain its instruction.
+ */
+export function withSteeringPropagation(prompt: string): string {
+  if (prompt.includes("<steering_propagation>")) return prompt;
+  const tagged = `<steering_propagation>\n${STEERING_PROPAGATION_CONTRACT}\n</steering_propagation>`;
+  const instructionAt = prompt.lastIndexOf("\n\n<instruction>");
+  if (instructionAt === -1) return `${prompt}\n\n${tagged}`;
+  return `${prompt.slice(0, instructionAt)}\n\n${tagged}${prompt.slice(instructionAt)}`;
+}
+
 export const WORKER_PREFLIGHT_CONTRACT = [
-  "Before normal implementation delegation, determine whether this checkout appears initialized for its actual language, framework, and build system.",
-  "Do not rely on hard-coded assumptions about JavaScript, TypeScript, Python, Rust, Go, Java, mobile, or any other ecosystem. Infer the project type and setup requirements from repository evidence.",
-  "Inspect source layout, setup docs, package/build manifests, lockfiles, toolchain files, generated-artifact conventions, CI workflows, workflow configuration, and package scripts or equivalent task definitions.",
-  "Look for evidence that dependencies, generated files, local toolchains, submodules, codegen outputs, or other project-specific initialization artifacts are missing for this checkout.",
-  "When repository evidence shows missing initialization, run or delegate the appropriate documented setup command before implementation work.",
-  "You are responsible for initializing the checkout when setup commands are documented; missing dependencies, generated files, or local toolchains are setup work, not user handoff work.",
-  "Once setup succeeds, continue normal implementation orchestration. Do not treat missing dependencies or generated setup artifacts in a fresh worktree as implementation failures.",
-  "If setup requirements cannot be determined confidently, delegate a focused discovery task before implementation instead of guessing.",
-  "If setup remains blocked after evidence-based discovery and setup attempts, report the blocker with commands tried and the exact evidence needed to continue.",
+  "Before implementation delegation, infer the checkout's language, framework, build system, and setup requirements from repository evidence rather than ecosystem assumptions.",
+  "Inspect source layout, setup docs, manifests, lockfiles, toolchain and codegen files, CI/workflow configuration, scripts, and generated-artifact conventions for missing dependencies, generated files, toolchains, submodules, or other initialization artifacts.",
+  "When setup is missing, run or delegate the documented setup before implementation; missing initialization is setup work, not a user handoff or implementation failure.",
+  "If requirements are unclear, delegate focused discovery rather than guessing. If evidence-based discovery and setup attempts remain blocked, report the commands tried and exact evidence needed to continue.",
 ].join("\n");
 
 export const E2E_VERIFICATION_GUIDANCE = [
-  "Verify correctness end-to-end whenever practical for user-visible behavior; do not rely only on code inspection, unit tests, or stage summaries when an executable user scenario can prove the outcome.",
-  "For web or frontend flows — including frontend changes whose correctness depends on backend/API behavior — use the playwright-cli skill, or delegate to a subagent with `skill: \"playwright-cli\"`, to drive the application like a user and capture snapshot, screenshot, DOM, or network evidence when that proves the objective.",
-  "For TUI or terminal-app flows, use the tmux skill, or delegate to a subagent with `skill: \"tmux\"`, to launch the app in an isolated tmux session, send keys, capture pane output, and simulate the scenario end to end.",
-  "Assume credentials, auth, and environment access for playwright-cli/tmux E2E testing exist until a concrete attempt proves otherwise; never skip E2E based only on an assumed missing prerequisite.",
-  "Before declaring E2E impractical, do cheap non-destructive checks first (existing sessions, config files, env vars, CLI auth status), then actually attempt to launch the app or flow.",
-  "If end-to-end verification is not practical in this checkout, record the exact command(s) attempted, observed failure output, smallest missing prerequisite, and narrower validation run instead; an unattempted assumption is never valid grounds to skip.",
+  "Verify correctness end-to-end whenever practical for user-visible behavior; an executable scenario is stronger proof than code inspection, unit tests, or stage summaries alone.",
+  "For web or frontend flows, including frontend changes whose correctness depends on backend/API behavior, use the playwright-cli skill or delegate with `skill: \"playwright-cli\"`; capture snapshot, screenshot, DOM, or network evidence suited to the objective.",
+  "For TUI/terminal flows, use the tmux skill or delegate with `skill: \"tmux\"` to exercise the scenario and capture pane output.",
+  "Assume credentials, auth, and environment access for playwright-cli/tmux E2E exist until a concrete attempt proves otherwise. Before calling E2E impractical, check existing sessions, config, env vars, and CLI auth, then attempt the launch or flow.",
+  "If E2E remains impractical, record the commands attempted, observed failure output, smallest missing prerequisite, and narrower validation run; an unattempted assumption is never valid grounds to skip.",
 ].join("\n");
 
 export function renderE2eQaVideoReviewGuidance(
   knownVideoPath?: string,
 ): string {
   const target = knownVideoPath === undefined || knownVideoPath.length === 0
-    ? "Look for QA E2E video references in the goal ledger, worker receipt, implementation notes, orchestrator report, or other review context artifacts."
+    ? "Look for QA E2E video references in the goal ledger, implementation receipt, implementation notes, orchestrator report, or other review context artifacts."
     : `Known QA E2E video path for this run: ${knownVideoPath}`;
   return [
     target,
-    "When a QA E2E video exists or is claimed as evidence, inspect the actual video before approving; do not treat a path, filename, transcript summary, or stage claim as proof by itself.",
-    "Use available video/file tooling such as `fetch_content` on the local video path with a prompt focused on whether the recording proves the required user scenario, or inspect representative frames/metadata when full video analysis is unavailable.",
-    "Check that the video reflects the current repository/application state, exercises the objective-relevant user path, shows the expected final behavior, and does not visibly hide errors, stale UI, broken loading states, or skipped steps.",
-    "For UI-applicable or full-stack changes, treat a missing, stale, unreadable, or inconclusive QA video as missing E2E evidence unless the receipt or implementation notes justify why no video applies and provide adequate alternate end-to-end proof.",
-    "Treat skipped E2E due to assumed-missing credentials, auth, or environment access as missing evidence unless the worker actually checked credential/auth state, attempted the launch/flow, and reported exact commands plus observed failure output.",
+    "Inspect the actual video before approving any claimed QA E2E evidence; a path, filename, transcript summary, or stage claim is not proof.",
+    "Use available video/file tooling such as `fetch_content` on the local video path with an objective-focused prompt, or inspect representative frames and metadata when full analysis is unavailable.",
+    "Confirm the video reflects the current repository/application state, exercises the objective-relevant user path through its expected result, and does not hide errors, stale UI, broken loading states, or skipped steps.",
+    "For UI-applicable or full-stack changes, missing, stale, unreadable, or inconclusive video is missing E2E evidence unless the receipt or notes explain why video does not apply and provide adequate alternate end-to-end proof.",
+    "Treat E2E skipped for assumed-missing credentials, auth, or environment access as missing evidence unless the implementation agent checked that state, attempted the launch or flow, and reported exact commands plus observed failure output.",
   ].join("\n");
 }
 
-
 export const LITERAL_OBJECTIVE_CONTRACT = [
   "Literal objective contract:",
-  "- The objective and acceptance criteria are the sole and LITERAL source of truth for required behavior.",
-  "- Acceptance criteria are the immutable task contract; the run objective is a delta that must not contradict them.",
-  "- If the objective and acceptance criteria conflict, do not implement the contradiction. Surface it as a blocker or reviewer finding instead.",
-  "- When external knowledge (language specs, upstream issues, in-repo comments, general best practice, or prior reviewer speculation) conflicts with explicit objective wording, the objective/acceptance criteria win.",
-  "- Never silently resolve such a conflict in favor of external knowledge. Surface the conflict clearly.",
-  "- Prefer loud errors over silent reinterpretation: when the objective/acceptance criteria enumerate required error conditions, messages, or rejections, give each enumerated error the widest plausible trigger surface. When the contract leaves an input ambiguous or unspecified near an enumerated error case, prefer raising that error over silently reinterpreting the input as different valid behavior, even when external spec knowledge says the input is valid.",
-  "- Only narrow an enumerated error's trigger surface when the objective, acceptance criteria, or pre-existing required tests explicitly require the ambiguous input to be accepted. Widening an enumerated error to nearby ambiguous inputs is applying the contract, not adding beyond it.",
-  "- Do not add behaviors, restrictions, error conditions, or follow-up requirements beyond what the objective/acceptance criteria require.",
-  "- The loud-error preference applies ONLY to error conditions the objective/acceptance criteria enumerate. For anything the contract does not enumerate, the default is the opposite: accept permissively and never invent a new validation error, required field, uniqueness constraint, or rejection the contract does not name.",
-  "- When the contract names a concrete type, shape, or format ('returns a dict', 'a list of strings', a JSON object with named keys), produce exactly that — no defensive substitutes such as read-only proxies, frozen collections, tuples-for-lists, or wrapper subclasses unless the contract requires them. Consumers may check type identity literally.",
-  "- Where behavior is unspecified, prefer the choice that preserves input verbatim over one that normalizes, deduplicates, reorders, or rewrites it; transform only what the contract says to transform.",
+  "- The objective and acceptance criteria are the sole literal source of required behavior; the run objective must not contradict them.",
+  "- Only the user may change the contract. A mid-run user message — steering, a follow-up, or resume text — is authoritative: adopt it as required behavior from that point on, and carry it forward under the steering propagation contract. You may never widen the contract yourself; an improvement you thought of is deferred work, not a new criterion.",
+  "- Surface objective/criteria conflicts as blockers or findings. When explicit wording conflicts with specs, upstream issues, comments, best practice, or reviewer speculation, the objective/criteria control; do not silently favor external knowledge.",
+  "- For an enumerated error, message, or rejection, prefer the widest plausible trigger over silently reinterpreting ambiguous nearby input. Narrow it only when the contract or pre-existing required tests explicitly require acceptance.",
+  "- That loud-error preference applies only to enumerated errors. Otherwise accept permissively: do not invent behavior, restrictions, validation errors, required fields, uniqueness/format constraints, or follow-up requirements.",
+  "- Produce named types, shapes, and formats exactly; do not substitute proxies, frozen collections, tuples-for-lists, or wrappers unless required because consumers may check identity.",
+  "- Where behavior is unspecified, preserve input verbatim rather than normalizing, deduplicating, reordering, or rewriting it.",
 ].join("\n");
 
 export const REVIEWER_SPEC_VS_OBJECTIVE_GUARD =
-  "Do not use external spec/standard conformance alone to flag a wide trigger surface for an error condition the objective/acceptance criteria enumerate; the contract prefers loud errors over silent reinterpretation of ambiguous inputs, so classify such spec-vs-objective tension as beyond_objective rather than a blocking defect.";
+  "External spec/standard conformance alone does not make a wide trigger for an enumerated error defective; classify that spec-vs-objective tension as beyond_objective, not blocking.";
 
 export const REVIEWER_OVERIMPLEMENTATION_GUARD =
-  "Hunt over-implementation as seriously as gaps: any validation error, required field, uniqueness/format constraint, immutability wrapper, or normalization the contract does not require is a defect that rejects inputs or produces shapes the contract permits — classify it required_by_objective. Probe at least one contract-permitted input the worker's own tests do not exercise before approving.";
+  "Treat unrequired validation errors, required fields, uniqueness/format constraints, immutability wrappers, and normalization as required_by_objective defects when they reject permitted inputs or change permitted shapes. Probe at least one contract-permitted input absent from implementation-authored tests.";
 
 export const ACCEPTANCE_MATRIX_CONTRACT = [
-  "Acceptance/contract matrix:",
-  "- Before implementing, derive an observable acceptance matrix from the literal objective and acceptance criteria: one row per explicit clause, requirement, named artifact, command, gate, invariant, and deliverable, each mapped to the concrete observable check (command, test, executable scenario, artifact inspection, or state assertion) that would prove it in the current checkout.",
-  "- Record the matrix in the receipt/implementation notes on the first turn and keep it current as work proceeds; every later completion claim must map back to matrix rows with current evidence.",
-  "- The matrix inherits the literal contract's scope: do not add rows for behavior the objective/acceptance criteria do not require, and do not drop rows because they are inconvenient to prove.",
-  "- Add one row per literal example in the objective/acceptance criteria (sample inputs/outputs, rendered text, file contents), checked character-for-character rather than paraphrased.",
-  "- Add explicit rows for each interface decision the contract constrains: return/field types by identity, required-vs-optional per field, duplicate handling, ordering, and raw-vs-normalized text. When the contract leaves such a decision open, record the permissive/preserving default chosen.",
-  "",
-  "Stateful behavior modeling:",
-  "- When the work involves stateful behavior (lifecycles, sessions, caches, persisted data, protocols, retries, concurrency, or multi-step flows), model the state space explicitly before implementing: enumerate the states, the legal transitions between them, the invariants that must hold in every state, and how illegal transitions or unexpected inputs are handled.",
-  "- Tie matrix rows for stateful clauses to specific states, transitions, and invariants so their checks exercise transitions and invariant preservation, not just happy-path end states.",
+  "Acceptance matrix:",
+  "- Derive one row per explicit objective/criteria clause, requirement, named artifact, command, gate, invariant, deliverable, and literal example; map each to a current-checkout command, test, scenario, artifact inspection, or state assertion. Check literal examples character-for-character.",
+  "- Record it in the first receipt/implementation notes, keep it current, map completion claims to current evidence, and neither add out-of-contract rows nor omit inconvenient ones.",
+  "- Include constrained interface decisions: exact return/field identity, required versus optional fields, duplicate handling, ordering, and raw versus normalized text; when open, record the permissive/preserving choice.",
+  "- For stateful work, enumerate states, legal transitions, cross-state invariants, and handling of illegal transitions/unexpected inputs; tie relevant rows to transition and invariant checks, not only happy-path end states.",
 ].join("\n");
 
 export const CONTRACT_FIDELITY_AUDIT = [
-  "Adversarial divergence pass:",
-  "- After checks are green and before claiming readiness for review, re-read the literal objective/acceptance criteria and ask for each clause: what plausible independent check of this clause would my implementation fail?",
-  "- Probe the recurring divergence categories specifically: (1) type-identity assertions on returned values, (2) inputs with optional fields omitted, (3) duplicated or aliased inputs, (4) ordering assumptions, (5) text expected verbatim where the implementation normalizes it, and (6) any raised error the contract does not enumerate.",
-  "- Fix each divergence or record its justification in the receipt/implementation notes; an unexamined divergence category is unfinished verification, not a nice-to-have.",
+  "Contract-fidelity risk classes:",
+  "- Select only classes supported by the literal contract and repository: exact public API/type identity; positive and negative build tags/features/configuration variants; schemas/generated artifacts and omitted/zero-value fields; states/transitions/invariants; configurable paths, working directories, precedence, and caller-controlled state; low-level APIs across feature flags; permitted omitted, empty, zero, duplicate, aliased, ordered, unusual, or verbatim-text inputs; and unenumerated errors.",
+  "- Before claiming readiness, probe each applicable class against the current checkout. Fix divergence or record its evidence-based justification in the receipt/notes; do not manufacture requirements outside the literal contract.",
 ].join("\n");
 
 export const REVIEWER_INTERCOM_COORDINATION_PROTOCOL = [
-  "Concurrent reviewer coordination protocol:",
-  "- At review start, use Intercom to initialize/check coordination and discover sibling reviewers participating in the same workflow run.",
-  "- Tell those sibling reviewers your validation plan and intended check ownership before running checks. Claim ownership before starting any expensive, lock-prone, or potentially conflicting command that uses a shared checkout or shared environment.",
-  "- Coordinate and serialize conflicting shared-checkout or shared-environment commands, including full test suites, build or test commands, package-manager operations, browser or E2E sessions, migrations, and generated-artifact steps. Announce each coordinated check when it starts and finishes. Release every claimed resource when finished, then send siblings an explicit resource-release update. Share reusable command outcomes and evidence so siblings can avoid redundant execution where appropriate.",
-  "- Operational coordination does not make the review collective: independently inspect the patch, perform your own analysis, and produce your own verdict. Never copy or defer to a sibling reviewer's conclusions.",
+  "Concurrent reviewer coordination:",
+  "- At review start, use Intercom to discover sibling reviewers and share validation plans and check ownership.",
+  "- Claim, serialize, announce, and release expensive or conflicting shared-checkout/environment work such as suites, builds, package operations, browser/E2E sessions, migrations, and generated-artifact steps; share reusable command evidence.",
+  "- Coordination is operational only: inspect independently and return your own verdict rather than copying or deferring to sibling conclusions.",
 ].join("\n");
 
 export const REVIEWER_INDEPENDENT_VERIFICATION_CONTRACT = [
-  "Independent verification derivation:",
-  "- Before relying on the worker receipt, worker-authored tests, or any prior reviewer output, derive your own adversarial check list from the literal objective and acceptance criteria alone: per-clause observable checks plus boundary, edge, negative, and invalid-input probes; contract-permitted-input probes (permissive inputs the implementation might wrongly reject: optional fields omitted, duplicates or aliases present, unusual-but-allowed values) and exact type/shape/text-identity probes for anything the contract names; and state/transition/invariant probes for stateful behavior.",
-  "- Execute or delegate the highest-value derived checks against the current repository state before mapping worker evidence to requirements.",
-  "- Worker-authored tests, snapshots, and receipts corroborate your derived checks; they never substitute for them. Passing worker-authored tests is circular evidence for the clauses those tests were written from.",
-  "- Keep derived checks inside the literal contract's scope; do not manufacture requirements beyond the objective/acceptance criteria.",
+  "Independent verification:",
+  "- Before reading receipts, implementation-authored tests, or prior reviews, derive per-clause observable checks from the literal objective/criteria, including supported boundary, edge, negative, invalid, permitted-input, exact type/shape/text, and state-transition probes.",
+  CONTRACT_FIDELITY_AUDIT,
+  "- Execute or delegate every applicable material probe before mapping implementation evidence. Report each command or scenario and observed result in the narrative and requirements_traceability fields.",
+  "- Implementation-authored tests, snapshots, and receipts corroborate but never replace independently derived checks; exact API, build, or schema clauses require the applicable independent compile, type, build-variant, or schema probe.",
+  "- A missing applicable compile/type/build/schema probe remains missing in requirements_traceability; explain it, add an objective-aligned finding when materially deficient, and set stop_review_loop=false.",
+  "- For any missing, blocked, or failed material probe, record its command/scenario and observed result or limitation in overall_explanation and requirements_traceability, use the remaining-verification or finding fields, and set stop_review_loop=false. If tools or dependencies still prevent necessary verification after reasonable recovery, populate reviewer_error.",
+  "- Before stop_review_loop=true, require overall_correctness to be patch is correct, every objective-relevant implementation and validation requirements_traceability entry proven, no blocking objective-aligned finding, direct evidence or a clear not-applicable justification for each applicable risk, and reviewer_error null or omitted. Otherwise set stop_review_loop=false and report the gap consistently.",
 ].join("\n");
 
 export const REGRESSION_EVIDENCE_CONTRACT = [
   "Durable regression evidence:",
-  "- When a defect or reviewer finding has been reproduced (observed through a command, test, or executable scenario), its fix is complete only with durable regression evidence: a focused test or repeatable check persisted in the repository's test suite where project norms allow, otherwise an exact re-runnable command with its observed output recorded in the receipt/notes.",
-  "- Treat a reproduced finding whose fix lacks durable regression evidence as unresolved; a one-off manual re-check is not durable evidence.",
-  "- Match the regression check to the reproduction: it must demonstrably cover the failing scenario (fail before the fix or provably exercise it) and pass after the fix.",
+  "- A reproduced defect is fixed only when a focused test or repeatable check covers the failing scenario and passes after the fix (and fails before it or demonstrably exercises it). Persist it in the test suite where norms allow; otherwise record an exact rerunnable command and observed output in the receipt/notes.",
+  "- Keep a reproduced finding unresolved when its fix has only a one-off manual check.",
 ].join("\n");
 
 export const FINDINGS_CONSOLIDATION_CONTRACT = [
-  "Consolidated findings batch:",
-  "- Treat the latest review round as one consolidated batch of findings, not a queue to repair one item per turn.",
-  "- Read every blocking finding first, group findings that share a root cause, plan the batch, then repair the full batch in this turn together with the validation and durable regression evidence each fix needs.",
-  "- Only defer a finding out of the batch when it is genuinely blocked or it contradicts the literal contract; record the reason in the receipt.",
+  "Treat the latest review round as one consolidated batch: read all blocking findings, group shared root causes, and repair the full batch with validation and durable regression evidence in this turn.",
+  "Defer only a genuinely blocked or contract-contradicting finding, recording the reason in the receipt.",
+].join("\n");
+
+export const SCOPE_DISCIPLINE_CONTRACT = [
+  "Scope discipline:",
+  "- Before writing code, state the goal in one sentence and list the acceptance criteria. That list is the contract. Freeze it.",
+  "- Done means the contract, not \"good.\" When all criteria pass, stop. Polish, refactors, and \"while I'm here\" fixes are new work, not this work.",
+  "- Every addition must trace to a criterion. If you cannot point at the criterion a change serves, do not make it. Log it instead.",
+  "- Keep a deferred list, not a growing diff. When you notice a bug, smell, or missing feature outside the contract, write one line in a deferred note and move on. Surface it at the end.",
+  "- Distinguish blockers from improvements. Change scope only if a criterion is impossible or wrong as written — and say so explicitly before proceeding; never silently absorb the work.",
+  "- Watch for the tells. \"It would be cleaner if...\", \"we should also...\", \"this really ought to...\" mean you are about to move the goalpost. Stop and check the contract.",
+  "- Prefer the smallest diff that satisfies the contract: fewer files touched, fewer abstractions introduced, no speculative generality for futures nobody asked for.",
+  "- Report three things at the end: what the contract was, evidence each criterion passes, and the deferred list. Scope changes belong in the report, never in the diff.",
 ].join("\n");
 
 export const EVIDENCE_CLOSURE_POLICY = [
   "Convergence flag (stop_review_loop):",
-  "- The reviewer's stop_review_loop boolean is the single authoritative convergence signal. The harness gates approval on that flag deterministically and does not recompute approval from findings arrays, priorities, or requirements_traceability statuses — derive the flag carefully because it is trusted as-is.",
-  "- Derive stop_review_loop=false while any objective-relevant blocking work remains: any P0/P1/P2 finding, any required_by_objective finding at any priority (P3 included — severity labels alone never dismiss objective-relevant findings), or any unproven implementation/validation requirement.",
-  "- Derive stop_review_loop=true when independent verification proves the implementation and validation requirements and everything left is non-blocking: consistent_with_objective P3 nice-to-haves, beyond_objective/contradicts_objective observations, an explicitly authorized post-approval final action such as PR/MR/review creation, or the multi-reviewer quorum process itself. Never hold the flag at false for those items — quorum is counted by the harness across reviewers and is not an implementation gap any single reviewer can prove.",
-  "- The loop is bounded: when the turn budget ends before convergence, the run stops with the unresolved findings and remaining work recorded for a human instead of relabeling them away.",
+  "- stop_review_loop is the single authoritative convergence signal; the harness trusts it without recomputing approval from findings, priorities, or requirements_traceability.",
+  "- Derive stop_review_loop=false while any objective-relevant blocking work remains: a P0/P1/P2 finding, a required_by_objective finding at any priority including P3, or an unproven implementation/validation requirement.",
+  "- Derive stop_review_loop=true when independent verification proves implementation and validation and only non-blocking items remain: consistent_with_objective P3 items, beyond_objective/contradicts_objective observations, an authorized post-approval PR/MR/review action, or reviewer quorum. Never hold it false for those items.",
+  "- If the bounded loop ends first, preserve unresolved findings and remaining work for a human rather than relabeling them.",
+].join("\n");
+
+export const WORKTREE_DISCIPLINE_CONTRACT = [
+  "Work in the workflow-designated checkout. Do not create another worktree, clone, or repository copy unless the task requests it; conflicts, locks, dirty state, and failed commands do not authorize one.",
+  "Bring required work found elsewhere into this checkout by applying, cherry-picking, or replaying it before continuing.",
+].join("\n");
+
+export const REVIEW_CODE_DELTA_CONTRACT = [
+  "Code delta integrity:",
+  "- Inspect the delivered checkout with version-control tooling (for git: `git worktree list`, `git status --short`, baseline diff, staged diff, and untracked files) and prove an objective-related delta exists before trusting receipts.",
+  "- If summaries claim implementation but the checkout lacks it, return a blocking [P0] required_by_objective finding and require the work to be brought here. Never set stop_review_loop=true for an empty or unrelated implementation delta.",
+  "- Unless the objective forbids committing, uncommitted claimed-ready work remains work: require a commit or intentional discard so delivery is durable.",
+  "- Treat modification, rename, or deletion of pre-existing tests or test functions as a finding requiring literal-contract justification; validating existing tests means running, not editing, them.",
 ].join("\n");

package/dist/builtin/workflows/builtin/steering-context.ts

@@ -0,0 +1,51 @@
+/**
+ * Steering propagation wrapper for builtin workflow run contexts.
+ *
+ * Every builtin workflow wraps its run context once, at the definition entry
+ * point, so each `ctx.task` / `ctx.chain` / `ctx.parallel` prompt carries the
+ * steering propagation contract. Wrapping the context rather than every call
+ * site means a stage added later inherits the pattern instead of silently
+ * dropping user amendments on the floor.
+ *
+ * The wrapper delegates through the prototype chain rather than spreading:
+ * the runtime context exposes `cwd` as a getter that resolves the workflow's
+ * current working directory on each read, and a spread would snapshot it.
+ *
+ * cross-ref:
+ *   - builtin/shared-prompts.ts (STEERING_PROPAGATION_CONTRACT)
+ *   - test/unit/builtin-workflow-steering-propagation.test.ts (enforcement)
+ */
+import type {
+  WorkflowInputValues,
+  WorkflowOutputValues,
+  WorkflowRunContext,
+  WorkflowTaskOptions,
+  WorkflowTaskStep,
+} from "../src/shared/types.js";
+import { withSteeringPropagation } from "./shared-prompts.js";
+
+function withPromptContract(options: WorkflowTaskOptions): WorkflowTaskOptions {
+  return options.prompt === undefined
+    ? options
+    : { ...options, prompt: withSteeringPropagation(options.prompt) };
+}
+
+function withStepContract(step: WorkflowTaskStep): WorkflowTaskStep {
+  const withPrompt = step.prompt === undefined
+    ? step
+    : { ...step, prompt: withSteeringPropagation(step.prompt) };
+  return withPrompt.task === undefined
+    ? withPrompt
+    : { ...withPrompt, task: withSteeringPropagation(withPrompt.task) };
+}
+
+export function withSteeringPropagationContext<
+  TInputs extends WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues,
+>(ctx: WorkflowRunContext<TInputs, TOutputs>): WorkflowRunContext<TInputs, TOutputs> {
+  const wrapped = Object.create(ctx) as WorkflowRunContext<TInputs, TOutputs>;
+  wrapped.task = (name, options) => ctx.task(name, withPromptContract(options));
+  wrapped.chain = (steps, options) => ctx.chain(steps.map(withStepContract), options);
+  wrapped.parallel = (steps, options) => ctx.parallel(steps.map(withStepContract), options);
+  return wrapped;
+}

package/dist/builtin/workflows/builtin/tournament-prompts.ts

@@ -1,5 +1,8 @@
 type PromptSection = readonly [tag: string, content: string];
 
+const GROUNDED_REPORTING = "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
+const READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
+
 function taggedPrompt(sections: readonly PromptSection[]): string {
   return sections
     .map(([tag, content]) => `<${tag}>\n${content.trim()}\n</${tag}>`)
@@ -9,16 +12,18 @@ function taggedPrompt(sections: readonly PromptSection[]): string {
 export function renderTournamentAttemptPrompt(task: string, attempt: number): string {
   return taggedPrompt([
     ["role", "You are an independent solution author competing on solution quality."],
-    ["objective", task],
     ["attempt", `Produce attempt ${attempt} without assuming another attempt's approach or conclusions.`],
+    ["success_criteria", "A judge can evaluate this artifact directly against correctness, completeness, evidence, and task fit."],
     ["requirements", [
       "Deliver a complete, self-contained solution rather than commentary about how to solve it.",
-      "Ground important claims in observable evidence, concrete reasoning, or executable checks.",
+      "Ground important claims in observable evidence or executable checks.",
       "State assumptions, limitations, and validation performed.",
       "Optimize for correctness and usefulness, not length.",
+      GROUNDED_REPORTING,
     ].join("\n")],
-    ["success_criteria", "A judge can evaluate this artifact directly against correctness, completeness, evidence, and task fit."],
-    ["output_format", "Markdown with Solution, Evidence and validation, Assumptions, and Residual risks."],
+    ["stop_rules", "Stop when the solution is complete, supported, validated where practical, and its residual risks are stated."],
+    ["output_format", `Markdown with Solution, Evidence and validation, Assumptions, and Residual risks. ${READABLE_REPORT}`],
+    ["objective", task],
   ]);
 }
 
@@ -30,26 +35,28 @@ export function renderPairwiseJudgePrompt(options: {
   readonly secondPath: string;
 }): string {
   return taggedPrompt([
-    ["role", "You are an impartial pairwise judge. Evaluate only the supplied artifacts."],
-    ["objective", options.task],
     ["candidates", [
       `First presentation: ${options.firstLabel} at ${options.firstPath}`,
       `Second presentation: ${options.secondLabel} at ${options.secondPath}`,
       "Read both files completely before deciding.",
     ].join("\n")],
+    ["role", "You are an impartial pairwise judge. Evaluate only the supplied artifacts."],
     ["rubric", [
       "1. Correctness: satisfies the task without material errors.",
       "2. Completeness: covers required outcomes and important edge cases.",
-      "3. Evidence: supports claims with concrete reasoning or checks.",
+      "3. Evidence: supports claims with observable evidence or checks.",
       "4. Task fit: is directly usable and avoids irrelevant work.",
     ].join("\n")],
     ["decision_rules", [
       "Choose exactly one presented candidate; do not merge or rewrite them.",
       "Ignore presentation order, writing length, and stylistic polish unless they affect the rubric.",
-      "Cite observable evidence from both artifacts and give a concise rationale.",
-      "Return the required structured decision.",
+      "Cite observable evidence from both artifacts and give concise criteria-based justification.",
+      GROUNDED_REPORTING,
     ].join("\n")],
     ["success_criteria", "The selected winner is traceable to short rubric-grounded evidence from both candidates."],
+    ["stop_rules", "Stop after selecting one candidate and supporting the choice against every rubric criterion."],
+    ["output_format", `Return only the required structured decision with winner, rationale, and evidence. ${READABLE_REPORT}`],
+    ["objective", options.task],
   ]);
 }
 
@@ -60,20 +67,22 @@ export function renderBracketReducerPrompt(options: {
   readonly winnerPath: string;
 }): string {
   return taggedPrompt([
-    ["role", "You are the tournament bracket reducer and final reporter."],
-    ["objective", options.task],
     ["artifacts", [
       `Bracket ledger: ${options.bracketPath}`,
       `Winning artifact (${options.winnerLabel}): ${options.winnerPath}`,
       "Read both files before reporting.",
     ].join("\n")],
+    ["role", "You are the tournament bracket reducer and final reporter."],
     ["requirements", [
       "Return the winning solution faithfully; do not silently combine losing material into it.",
       "Summarize why it advanced using the recorded pairwise rationale and evidence.",
       "Call out bracket byes and any limitations recorded by judges.",
       "Cite the bracket ledger and winning artifact paths.",
+      GROUNDED_REPORTING,
     ].join("\n")],
     ["success_criteria", "A reader can use the winning solution and audit every comparison that selected it."],
-    ["output_format", "Markdown with Winner, Winning solution, Decision trail, Evidence, and Residual risks."],
+    ["stop_rules", "Stop after faithfully presenting the winner and an auditable decision trail, including byes and limitations."],
+    ["output_format", `Markdown with Winner, Winning solution, Decision trail, Evidence, and Residual risks. ${READABLE_REPORT}`],
+    ["objective", options.task],
   ]);
 }

package/dist/builtin/workflows/builtin/tournament-runner.ts

@@ -173,6 +173,9 @@ export async function runTournament(ctx: WorkflowRunContext<TournamentInputs>) {
     context: "fresh",
     reads: [bracketPath, winner.path, ...judgeArtifactPaths],
     output: resultPath,
+    // Keep the reducer report out of the caller's context window; `result_path`
+    // below carries it for callers that want the contents.
+    outputMode: "file-only",
   });
 
   return {

package/dist/builtin/workflows/builtin/tournament.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runTournament } from "./tournament-runner.js";
 
 export default workflow({
@@ -21,7 +22,7 @@ export default workflow({
     }),
   },
   outputs: {
-    result: Type.String({ description: "Final reducer report containing the winning solution and decision trail." }),
+    result: Type.String({ description: "Compact reference to the final reducer report holding the winning solution and decision trail; read `result_path` for the full report." }),
     winner: Type.String({ description: "Stable attempt label selected as the tournament winner." }),
     winner_artifact_path: Type.String({ description: "Path to the original winning attempt artifact." }),
     result_path: Type.String({ description: "Path to the final reducer report artifact." }),
@@ -30,5 +31,5 @@ export default workflow({
     bracket_path: Type.String({ description: "Path to the durable JSON bracket with matches, byes, rationales, and winner." }),
     artifact_dir: Type.String({ description: "Run-specific directory containing tournament artifacts." }),
   },
-  run: async (ctx) => await runTournament(ctx),
+  run: async (ctx) => await runTournament(withSteeringPropagationContext(ctx)),
 });

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.10",
+  "version": "0.9.11-alpha.10",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -67,7 +67,7 @@
   },
   "pi": {
     "extensions": [
-      "./src/extension/index.ts"
+      "./src/extension/index.bundle.mjs"
     ],
     "builtin": [
       "./builtin"
@@ -79,11 +79,11 @@
   },
   "dependencies": {
     "jiti": "^2.7.0",
-    "typebox": "^1.3.6"
+    "typebox": "^1.3.7"
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.80.10"
+    "@earendil-works/pi-tui": "^0.83.0"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/workflows/skills/create-spec/SKILL.md

@@ -65,7 +65,7 @@ For each non-trivial entrypoint the spec introduces or changes, walk these in or
 - When writing the spec, DO NOT include information about concrete dates/timelines (e.g. # minutes, hours, days, weeks, etc.) and favor explicit phases (e.g. Phase 1, Phase 2, etc.).
 - The spec MUST treat its entrypoint set as a first-class artifact. Section 5 is built around the **doors** (typed signatures, named failures, refusals expressed in types) and must pass the rubric above. Do not let intent leak into mechanism: a reviewer should reconstruct the system's purpose from §4.4 and §5.1 alone.
 - If the spec is for a workflow with reviewer gates plus final actions (for example PR/MR/review creation, release tagging, deployment, or publication), explicitly separate implementation/review acceptance from those post-approval final actions. The workflow design should tell reviewers/reducers to approve and stop the implementation loop when implementation and validation criteria are proven and only an explicitly authorized final action remains; carry that remainder as a next action/final-action field instead of another implementation iteration.
-- If the spec is for a workflow or workflow prompt refactor, require local, action-oriented stage/reviewer/reducer prompts. A model stage sees its prompt, artifacts, tools, and reads — not the workflow graph's name or surrounding implementation details unless explicitly provided — so the spec should prefer instructions like "review the current code delta" or "create/update the review request" over labels such as "the create-PR workflow stage", "this Goal run", or "the Ralph reviewer" unless that name is user-visible context or materially changes behavior.
+- If the spec is for a workflow or workflow prompt refactor, require local, action-oriented stage/reviewer/reducer prompts. A model stage sees its prompt, artifacts, tools, and reads — not the workflow graph's name or surrounding implementation details unless explicitly provided — so prefer instructions like "review the current code delta" or "create/update the review request" over implementation-specific workflow nicknames unless a name is user-visible context or materially changes behavior.
 - Once the spec is generated ask questions one at a time OR in logical groups:
   - Refer to section "## 9. Open Questions / Unresolved Issues", go through each question one by one, and use **contrastive clarification** (presenting 2-3 specific options with concrete tradeoffs) rather than open-ended questions. This means presenting interpretations like "(A) Option X — tradeoff Y" and "(B) Option Z — tradeoff W" instead of asking "what do you think about X?". Update the spec with the user's answers as you walk through the questions.
   - Interview the user relentlessly about every aspect of this plan/spec until you reach a shared understanding with them. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer (i.e., **contrastive clarification**). Pay special attention to the **doors**: every disagreement about what a joint is, what a door promises, what it refuses, or where a dangerous effect is funneled is a question worth resolving with the user.