codex-orchestrator 0.1.36 → 0.1.39

package/docs/deep-dive.md

@@ -242,6 +242,36 @@ text or changed paths indicate UI, API, worker, CLI, or smoke-verifiable work.
 `reviewGates.acceptanceProof` is canonical; `reviewGates.visualProof` remains a
 configuration migration adapter for existing screenshot and mobile proof policy.
 
+The risk-routing gate checks declared review metadata instead of inferring risk
+with an LLM. `reviewGates.riskRouting` defaults to enabled `warn` mode so older
+repositories surface findings without unexpected publication blocks. In
+`block` mode, the same findings become publication blockers.
+
+For scoped runs, risk routing checks the completion report `reviewHandoff`:
+
+- required handoff fields must be present and non-empty;
+- low-risk claims must use an allowed low-risk flow;
+- configured `riskyChangedPathGlobs` can flag low-risk claims that changed
+  risky paths;
+- high-risk claims require passed code-review validation when
+  `highRiskRequiresCodeReview` is true.
+
+Low-risk routing never weakens existing quality, acceptance proof, visual proof,
+deny, or configured-check gates. It can only add warnings or blockers.
+Scoped risk-routing blockers are retryable only when
+`loopPolicy.rework.retryableBlockers` explicitly includes
+`risk-routing-policy`.
+
+For parent `agent:plan-auto` runs, risk routing checks the planning report after
+it is read and before parent content or child issues are mutated. Parent
+`sizeRisk` must partition every child stable id exactly once across
+`small`, `medium`, and `high`; `parentReviewHandoff` must include risks, proof
+strategy, and human review focus. In warn mode, findings render under
+`Risk routing warnings` in the parent PR body and review report while execution
+continues. In block mode, the parent stops at that point and does not create
+child issues, execute children, create a draft PR, or attempt parent planning
+rework.
+
 ## Acceptance Proof
 
 Acceptance proof is intentionally runner-owned. Codex can implement product
@@ -373,7 +403,11 @@ Setup now uses the package-owned
 `codex-orchestrator visual-proof auto --issue ${issueNumber}` command. Auto
 dispatch uses one shared policy owner: web/frontend paths route to browser
 proof, while Android, iOS, Flutter, and mobile app paths remain device-backed.
-Explicit legacy proof command overrides are preserved.
+When acceptance proof is required but the changed paths are backend/API/CLI-only
+and visual proof is not desirable, auto proof does not force a browser or mobile
+target; the runner evaluates the prepared machine-readable
+`acceptance-proof-report.json` and its non-visual artifacts instead. Explicit
+legacy proof command overrides are preserved.
 
 For web UI work, `codex-orchestrator visual-proof browser` reads a proof-owned
 browser scenario, drives Playwright Core against an explicit base URL, and
@@ -520,8 +554,13 @@ Recoverable runs are classified with explicit states:
 - `completed-pending-handoff` means the completed report, worktree, branch, and
   base evidence are sufficient to retry runner-owned publication.
 - `failed-pending-block` means the stale runner-owned run cannot satisfy
-  publication preconditions and should be moved to `agent:blocked` with
-  concrete evidence.
+  publication preconditions and should be moved to `agent:blocked` with concrete
+  evidence. Missing completion reports get one bounded recovery retry first when
+  `missing-completion-report` is configured as retryable, the stale attempt has
+  remaining rework budget, same-host stale ownership is proven, and the branch
+  has no committed, staged, unstaged, or untracked changes since the recovered
+  base SHA. If any of those checks fail, recovery blocks instead of resetting or
+  building on unreported work.
 - `unknown-or-foreign` means ownership or safety cannot be proven, so the runner
   does not mutate GitHub.
 
@@ -566,7 +605,7 @@ The top-level config areas are:
 - `project` for config and prompt directories;
 - `workflows` for prompt or skill routing;
 - `checks` and `checksPolicy` for validation commands;
-- `reviewGates` for quality and acceptance proof requirements;
+- `reviewGates` for quality, risk-routing, and acceptance proof requirements;
 - `loopPolicy` for issue selection, rework, review, summaries, and suggestions;
 - `deny` for secret and unsafe-action protection;
 - `branches` for branch templates;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-orchestrator",
-  "version": "0.1.36",
+  "version": "0.1.39",
   "description": "Reusable GitHub Issues runner for Codex.",
   "type": "module",
   "license": "MIT",

package/prompts/workflows/breakdown-review.md

@@ -24,6 +24,7 @@ Use or request:
 - **Source-of-truth risk:** flag duplicated business rules, competing ownership, or repeated normalization, dispatch, persistence, or compatibility logic across issues.
 - **Parallelization risk:** flag issues likely to collide if assigned to agents in the same wave.
 - **Spec proportionality:** flag repeated issue-level spec gates when one shared wave-level spec would be safer.
+- **Risk/proof routing:** flag small issues that are over-orchestrated instead of routed to `small-task-implementer`, and risky issues that lack spec gates, review focus, or proof strategy.
 - **Final coverage:** complex plans should include a final integration/regression slice when individual slices do not prove the full scenario together.
 
 ## Decision Rules
@@ -41,7 +42,7 @@ Always answer in this structure:
 3. `Blockers before publishing` with concrete findings and failure mechanics.
 4. `Split / Merge / Reorder` with exact issue-level changes.
 5. `Acceptance Criteria fixes` with criteria that need to become more testable.
-6. `AFK readiness and orchestration risk` with collision risks, spec-gate proportionality, and safer wave order.
+6. `AFK readiness and orchestration risk` with collision risks, spec-gate proportionality, risk/proof routing, and safer wave order.
 7. `Hard questions` with only questions that block publication.
 
 If there are no blockers, say so explicitly. Avoid generic praise and speculative objections.

package/prompts/workflows/issue-breakdown.md

@@ -46,6 +46,16 @@ Consider a spec gate when the slice involves:
 - required browser, mobile, manual, or live smoke validation;
 - known rejected approaches or unresolved product or technical decisions.
 
+## Size / Risk
+
+Each child issue must declare the intended implementation path:
+
+- `Small / low risk`: use `small-task-implementer`; keep the issue narrow, deterministic, and directly verifiable.
+- `Medium`: use scoped implementation with TDD and configured review gates.
+- `High risk`: require issue-level or wave-level spec gates before implementation.
+
+Do not split a small issue into a parent orchestration tree just to satisfy process. Do not mark risky shared-contract work as small to avoid review.
+
 ## Review Gate
 
 Before publishing child issues, run an issue-breakdown-review pass over the proposed breakdown. The review must check tracer-bullet quality, dependency correctness, AFK readiness, acceptance criteria, scope control, source-of-truth risk, spec proportionality, and orchestration risk.
@@ -58,6 +68,7 @@ Present the proposed breakdown as a numbered list. For each slice include:
 
 - **Title**
 - **Type**: AFK or HITL
+- **Size / Risk**: small / medium / high, with intended path (`small-task-implementer`, scoped implementation, issue-level spec, or wave-level spec)
 - **Blocked by**
 - **User stories covered** when available
 - **Spec required**: none / issue-level / wave-level, with one short reason
@@ -93,6 +104,16 @@ Reason:
 
 - One concise reason, or "None - straightforward implementation with existing local patterns."
 
+## Size / risk
+
+Size: small / medium / high
+
+Intended path: small-task-implementer / scoped implementation / issue-level spec / wave-level spec
+
+Reason:
+
+- One concise reason tied to ownership, contracts, and validation.
+
 ## External contracts
 
 Status: confirmed / needs proof / not applicable
@@ -104,11 +125,21 @@ Status: confirmed / needs proof / not applicable
 
 ## Verification
 
+- Proof Strategy: auto / visual / browser-visual / mobile-visual / non-visual-smoke / none
 - Automated:
 - Architecture:
 - Manual/live:
 - Required fixtures or files:
 
+Choose a concrete proof strategy for every AFK issue:
+
+- `non-visual-smoke` for backend, CLI, telemetry, analytics, event dispatch, data, logging, or workflow behavior where tests, command output, logs, API responses, or machine-readable artifacts are the proof surface.
+- `browser-visual` for web UI/layout/copy/responsive behavior.
+- `mobile-visual` for Android/iOS/Flutter UI behavior where device-backed launch, screenshot, UI dump, or logs are the proof surface.
+- `visual` when visual proof is required but browser vs mobile should be selected from changed paths.
+- `none` only when normal tests/checks are sufficient and no extra acceptance proof artifacts are required.
+- `auto` when no stronger explicit choice is known.
+
 ## codex-orchestrator metadata
 
 Ownership:

package/prompts/workflows/issue-tree-orchestration.md

@@ -37,7 +37,8 @@ Allowed proof includes test result, smoke result, command output, API or browser
 4. Build a dependency graph: ready, blocked, final integration/regression.
 5. Identify protected paths, likely source-of-truth owners, and files that must not be edited concurrently.
 6. Extract each issue's spec gate metadata.
-7. Mark unresolved external contracts, credentials, live fixtures, or human-only decisions as blocked until proven or cleared.
+7. Extract each issue's size/risk and intended path (`small-task-implementer`, scoped implementation, issue-level spec, or wave-level spec).
+8. Mark unresolved external contracts, credentials, live fixtures, or human-only decisions as blocked until proven or cleared.
 
 ## Plan Waves
 
@@ -49,6 +50,7 @@ Create the smallest safe parallel wave first:
 - keep final cross-cutting regression or cleanup issues for the last wave;
 - define each wave exit gate: worker reports, integration diff review, combined validation, and blocker reconciliation;
 - decide whether the wave requires a spec gate.
+- keep small low-risk children on the compact `small-task-implementer` path when their ownership and validation are genuinely narrow.
 
 ## Spec Gates
 
@@ -78,6 +80,7 @@ For each issue in the active wave, assign one worker with a narrow ownership sco
 - accepted implementation spec reference when a spec gate was run;
 - repo policy and relevant docs to read;
 - instruction to use TDD for behavior changes;
+- instruction to use `$small-task-implementer` only for child issues explicitly classified as small/low-risk, and to escalate if hidden risk appears;
 - exact ownership boundaries;
 - warning that other agents may be editing the repo;
 - instruction not to revert or overwrite user or worker changes;
@@ -85,6 +88,7 @@ For each issue in the active wave, assign one worker with a narrow ownership sco
 - required preconditions and verification commands;
 - stop conditions;
 - required final report: changed files, proof per acceptance criterion, tests run, skipped checks, risks, blockers, and unresolved acceptance criteria.
+- required `reviewHandoff`: flow used, risk level, implemented contract, proof by acceptance criterion, review focus, and human review checklist.
 
 While workers run, the integrator should do non-overlapping work: read docs, inspect ownership, map integration points, and prepare validation. Do not duplicate a worker's implementation.
 
@@ -98,14 +102,15 @@ Treat each wave as a hard execution gate:
 4. Remove duplicated logic, competing source-of-truth changes, and workaround-shaped code.
 5. Check for architecture drift: shallow modules, one-adapter seams, duplicated rules, or tests coupled to implementation details.
 6. Reconcile every active child issue as complete, blocked with evidence, or deferred.
-7. Verify TDD evidence for behavior-changing issues.
-8. Run the smallest meaningful combined validation for the wave.
-9. Run repo architecture checks when available and applicable.
-10. Verify implementation stayed inside the accepted spec, or document why a spec amendment was required.
-11. Run cleanup-review and code-review when repo policy or change size requires them.
-12. Fix high-confidence review findings and rerun validation.
-13. Create focused commits for completed child issues, or one documented wave commit when safe separation is impossible.
-14. Update the dependency graph before starting the next wave.
+7. Verify each child's declared path: small-task-implementer stayed compact, and medium/high-risk work satisfied spec/review/proof expectations.
+8. Verify TDD evidence for behavior-changing issues.
+9. Run the smallest meaningful combined validation for the wave.
+10. Run repo architecture checks when available and applicable.
+11. Verify implementation stayed inside the accepted spec, or document why a spec amendment was required.
+12. Run cleanup-review and code-review when repo policy or change size requires them.
+13. Fix high-confidence review findings and rerun validation.
+14. Create focused commits for completed child issues, or one documented wave commit when safe separation is impossible.
+15. Update the dependency graph before starting the next wave.
 
 If a worker reports an ambiguous or risky decision, pause and ask the user a targeted question.
 
@@ -117,12 +122,13 @@ After all child issues are implemented, blocked, or deferred:
 2. Reconcile all child acceptance criteria, skipped checks, blockers, and out-of-scope protections.
 3. Run cleanup-review before final code-review when repo policy requires it.
 4. Fix grounded findings and rerun relevant checks.
-5. Summarize completed issues, verification, skipped checks, and follow-up risks.
-6. Comment on completed child issues with result summaries and verification.
-7. Close completed child issues only after completion evidence is posted.
-8. Comment on the parent with completed children, validation, out-of-scope items preserved, and residual risks.
-9. Open or prepare a pull request when requested or expected by repo workflow.
-10. Stop before any human-only action such as PR approval, merge, product decision, manual validation, missing access, or secrets.
+5. Write a Parent Risk/Proof Mini-Report summarizing child outcomes, flow used per child, risk levels, proof coverage, skipped checks, and the exact human review focus.
+6. Summarize completed issues, verification, skipped checks, and follow-up risks.
+7. Comment on completed child issues with result summaries and verification.
+8. Close completed child issues only after completion evidence is posted.
+9. Comment on the parent with completed children, validation, Parent Risk/Proof Mini-Report, out-of-scope items preserved, and residual risks.
+10. Open or prepare a pull request when requested or expected by repo workflow.
+11. Stop before any human-only action such as PR approval, merge, product decision, manual validation, missing access, or secrets.
 
 ## Stop Conditions
 

package/prompts/workflows/prd.md

@@ -53,6 +53,16 @@ List testing decisions. Include:
 - required smoke, browser, mobile, API, or live validation;
 - cases where a deterministic test seam is missing and must be created or explicitly accepted as risk.
 
+### Risk And Proof
+
+Classify the initiative so downstream automation can choose the right implementation path:
+
+- small low-risk work that should stay on the Small Task Implementer path;
+- medium scoped implementation work that needs TDD and review gates;
+- high-risk contracts that need issue-level or wave-level spec gates before coding.
+
+List the proof strategy a maintainer should expect after implementation: tests, smoke checks, artifacts, review focus, and any proof that cannot be automated locally.
+
 ### Out of Scope
 
 List adjacent behavior that should not be included in this PRD.
@@ -65,5 +75,6 @@ Record open questions, migration notes, rollout notes, compatibility concerns, a
 
 - The PRD must be durable: useful even if files move.
 - The PRD must be specific enough to break into vertical implementation issues.
+- The PRD must make risk and proof expectations explicit enough that small tasks are not over-orchestrated and risky work is not under-specified.
 - Do not hide unresolved decisions inside implementation work.
 - Do not mark work as agent-ready when the PRD still depends on unconfirmed external contracts, credentials, manual design decisions, or ambiguous acceptance criteria.

package/prompts/workflows/scoped-implementation.md

@@ -12,6 +12,16 @@ Implement one scoped issue or approved implementation spec. Follow the issue, re
 6. Do not add pass-through modules, one-adapter seams, or test-only helpers unless they improve real locality or leverage.
 7. Add comments only where they clarify non-obvious behavior.
 
+## Task Sizing
+
+Before editing, classify the issue:
+
+- `Small / low risk`: clear behavior, narrow ownership, no schema/persistence/auth/background/shared-contract change, and a targeted validation path exists. Use the Small Task Implementer path (`$small-task-implementer`): compact contract, smallest edit, targeted proof, explicit escalation if hidden risk appears.
+- `Medium`: behavior-changing runtime work that touches shared flow, multiple files, or meaningful tests, but does not require a parent issue tree. Use this scoped implementation workflow with TDD and the configured review gates.
+- `High risk`: schemas, persistence, queues, retries, idempotency, auth, permissions, billing, caching, external contracts, multi-service work, or broad source-of-truth changes. Use the scoped/spec path only if the issue already provides deterministic contracts; otherwise return `needs-promotion` with evidence.
+
+Do not run a heavy plan/spec process for a genuinely small task. Do not force a small task path when the change reveals hidden shared-contract or validation risk.
+
 ## TDD And Behavior Proof
 
 For runtime behavior changes, use strict TDD red-to-green:
@@ -44,6 +54,17 @@ Run code-review before completion when the issue or repo policy requires it, or
 
 For compact low-risk changes, focused validation plus a clear completion report is enough unless repo policy says otherwise.
 
+## Review Handoff
+
+For completed work, include `reviewHandoff` in the runner JSON report:
+
+- `flowUsed`: `small-task-implementer`, `scoped-implementation`, `spec-implementer`, `issue-tree-child`, or `other`;
+- `riskLevel`: `low`, `medium`, or `high`;
+- `implementedContract`: what behavior or invariant changed;
+- `proofByAcceptanceCriteria`: acceptance criteria mapped to test/smoke/artifact evidence;
+- `reviewFocus`: the exact files, states, contracts, or edge cases a human should inspect;
+- `humanReviewChecklist`: the shortest useful manual review path.
+
 ## Acceptance Proof
 
 Prepare runner-owned acceptance proof artifacts when configured. For visual work,
@@ -97,5 +118,5 @@ Do not mark the issue complete until:
 - validation commands and behavior proof have run, or skipped checks have concrete reasons;
 - applicable cleanup-review and code-review gates have run;
 - protected paths stayed untouched and rejected approaches were avoided;
-- changed files, validation, skipped checks, residual risks, and blockers are reported;
+- changed files, validation, review handoff, skipped checks, residual risks, and blockers are reported;
 - the structured completion report is written exactly where the runner requested it.

package/prompts/workflows/triage.md

@@ -79,6 +79,17 @@ Describe what should happen, including edge cases and error conditions.
 - Interface or contract name - what needs to change and why
 - Config shape or command - expected behavior
 
+**Proof strategy:**
+Proof Strategy: auto / visual / browser-visual / mobile-visual / non-visual-smoke / none
+
+Choose the explicit strategy from the acceptance criteria:
+- `non-visual-smoke` for backend, CLI, telemetry, analytics, event dispatch, data, or logging work where tests, command output, logs, API responses, or machine-readable artifacts prove behavior better than screenshots.
+- `browser-visual` for web UI/layout/copy/responsive work.
+- `mobile-visual` for Android/iOS/Flutter UI behavior where device-backed launch, screenshot, UI dump, or logs are the proof surface.
+- `visual` when visual proof is required but browser vs mobile should be selected from changed paths.
+- `none` only when normal tests/checks are sufficient and no extra acceptance proof artifacts are required.
+- `auto` when no stronger explicit choice is known.
+
 **Acceptance criteria:**
 - [ ] Specific, testable criterion
 - [ ] Specific, testable criterion