codex-orchestrator 2.0.10 → 2.0.12

package/docs/deep-dive.md

@@ -120,7 +120,9 @@ After claim and worktree creation, the Runner invokes `triage` against the froze
 
 The route report records inspected evidence, explicit assumptions, and route-specific details. The Runner hashes the report and persists a route receipt bound to the workflow generation.
 
-A malformed triage report has one report repair budget. A clean transport failure has one separate transport retry. These retries do not become implementation cycles.
+A malformed triage report consumes the route-owned report-repair budget. Infrastructure failures before a recoverable report do not consume that semantic budget and are deferred to a later Runner tick; routing does not own a transport retry counter.
+
+`triage`, `ambiguity-review`, `spec-author`, `spec-review`, and `code-review` share one canonical durable report invocation mechanism. It durably binds the exact attempt, immutable workflow generation, an opaque hash of the phase-owned prompt facts, report path, worktree baseline, and host/boot/PID/process-start/process-group fence. Report-only operations run against an attempt-owned read view; `spec-author` instead receives only its attempt-owned target-state directory and may create the correlated immutable revision there. Recovery observes the exact attempt-owned report before considering relaunch, distinguishes a positively absent report from an uncertain read, and adopts output only after process and process-group absence are positive. Prompt-fact drift, uncertain report reads, or uncertain process identity retain the fence and fail closed. Attempt-owned read views are removed before adoption or abandonment; cleanup failure is infrastructure deferral and does not consume a phase semantic budget.
 
 An `awaiting-user` proposal is privileged because it pauses autonomous work. It must describe at least two materially different observable product outcomes and prove that repository authority does not select between them. A separate `ambiguity-review` worker receives the candidate and either approves or rejects it. Only one candidate review is allowed. A rejected candidate can use the single triage repair path; an approved candidate becomes the durable route receipt.
 
@@ -152,7 +154,7 @@ Complexity, cross-cutting behavior, or insufficient executable detail makes dire
 4. The same reviewer session performs closure review against the affected defects.
 5. Only an approved revision with resolved blockers is frozen.
 
-Prepared and launched invocation records are persisted before and after process launch. Recovery proves process-group absence before replacing an uncertain invocation. Malformed reports and transport retries are bounded; exhaustion becomes a typed blocker rather than an unbounded author/reviewer loop.
+Both `spec-author` and `spec-review` use the canonical invocation mechanism above. The specification state owns author and reviewer sessions, reviewer independence, revision and target/Closure correlation, malformed-report repair, defect ledger, repair-cycle budget, provenance, and terminal mapping. Each phase session is persisted atomically with canonical prepare, so restart reconstructs byte-identical prompt facts and adopts the exact attempt-owned report and revision before any relaunch. Infrastructure failure before recoverable output consumes no semantic budget; recovered malformed author or review output consumes the existing matching report-repair budget exactly once.
 
 The terminal result for this route is `spec-frozen` with an immutable `FrozenSpecReceipt`. The current runtime does not silently continue from a newly authored specification into implementation. That boundary keeps specification approval separately auditable.
 
@@ -192,7 +194,9 @@ An `implementation` worker receives the current cycle and any findings from prio
 - inventories tracked, staged, unstaged, untracked, and denied-path state;
 - requires the reported changed-file list to equal the observed change set.
 
-A clean implementation transport failure receives one separate retry only if the complete Git freshness baseline is unchanged. Any unexplained mutation converts that retry into a safety block.
+Qualification repair, implementation/rework, and trusted review-feedback implementation share one canonical mutable-worktree invocation mechanism. It durably owns attempt identity, prepared/launched/adopted state, host/boot/PID/process-start/process-group fencing, the launch baseline, the exact attempt-owned report, and the adopted result snapshot. Recovery performs one bounded observation per Runner tick and adopts the exact report and worktree result before any relaunch. A positively absent report and positively absent process/group permit abandonment only when the worktree still equals the launch baseline; uncertain ownership, report reads, or effects retain the fence and yield issue-locally without publication.
+
+Each caller supplies an opaque correlation over its authoritative prompt facts. Qualification keeps scoped failures and denied-path correlation; implementation keeps claim/issue/head, frozen criteria, cycle, mutable provenance, and candidate binding; review feedback keeps its trusted batch, source authorization, round, and target. Correlation drift never adopts stale output or authorizes a replacement launch. Infrastructure failure before recoverable output consumes no semantic budget. Once an adopted output is classified as malformed, rejected, or needing work, the owning phase clears the invocation and spends exactly its existing semantic budget in the same state transition, so replay cannot spend twice.
 
 Before configured checks, a separate `code-review` worker reviews a fingerprint of the complete implementation target. The fingerprint binds Git freshness, changed files, route decision, workflow generation, cycle, and frozen criteria. Full review covers at least acceptance criteria, correctness, and test quality; cleanup is a lens within this final review.
 
@@ -200,35 +204,69 @@ Review maintains an append-preserving defect ledger. If review returns `needs-wo
 
 Coverage text is descriptive, not an identity contract: Closure may paraphrase or omit it. Stable defect and repair-finding IDs, target revision, target fingerprint, and Closure hash carry correlation. Each target revision receives up to four report-only format repairs. Starting a new Closure revision resets that local budget. An eligible legacy terminal malformed-review report can resume only when its evidence ID proves that cause, its per-revision budget remains, and issue authorization, trusted claim, worktree identity, head, changed files, and target fingerprint still match. Current exhausted revisions remain terminal and replay without new effects.
 
-Review invocation intent, process IDs, report hashes, transport retries, report repairs, target revisions, and target fingerprints are durable. A crash after launch cannot cause a replacement review until process absence is proven. Review target drift after approval is a safety failure.
+Canonical review invocation identity, process fencing, prompt correlation, and attempt-owned report recovery are durable. Direct-review state separately owns report repairs, target revisions, target fingerprints, reviewer independence, defect meaning, and terminal mapping; it has no review transport retry counter. A crash after launch cannot cause a replacement review until process and process-group absence are proven and its read view is settled. Review target or authoritative prompt-fact drift is a safety failure.
+
+The run-store performs one bounded canonicalization for active states written by the replaced route/direct-review/spec-author/spec-review lifecycle owners. Safely convertible ready/completed or prepared/no-effect states are rewritten once with the removed fields absent and exact source bytes backed up. An old launched or otherwise ambiguous owner that lacks PID-reuse-resistant process identity is converted to an issue-local non-resumable safety outcome; it is never silently deleted or relaunched. Canonical validators remain exact and do not retain a legacy reader or dual-write path.
 
 ## 8. Issue-scoped checks and `CheckedChange`
 
 For a new direct run, the Runner resolves its finite check policy from the frozen issue body. A command-only `Verification:` or `## Verification:` section replaces repository-wide checks with deterministic `issue-verification-NNN` entries. Scoped entries are limited to `npm [--prefix <repository-relative-path>] test ...` and `npm [--prefix <repository-relative-path>] run <script> ...`; the Runner parses them to argv and executes them without a shell. Interpreter eval, package-exec, nested-shell, shell-composition, malformed, duplicate, mixed-validity, and ambiguous sections fail closed before any check runs. The triage worker's free-text verification output is never command authority. `config.checks` is used only when the frozen issue has no Verification section.
 
-Before the issue implementation starts, the Runner executes the resolved policy as a qualification gate. If any command fails, a separate sealed qualification-repair operation receives the scoped failures but not the issue acceptance criteria, and may repair the files needed to make the policy green. The Runner reruns the complete policy after each repair. Qualification repairs have their own bounded launched-attempt counter and do not consume the issue's implementation-cycle budget. Their cumulative files remain in the worktree and are included in the later implementation report, independent review, final checks, proof, and PR.
+Before the issue implementation starts, the Runner executes the resolved policy as a qualification gate. If any command fails, a separate sealed qualification-repair operation receives the scoped failures but not the issue acceptance criteria, and may repair the files needed to make the policy green. The Runner reruns the complete policy after each adopted repair. Qualification repairs have their own bounded semantic repair budget and do not consume the issue's implementation-cycle budget. Their cumulative files remain in the worktree and are included in the later implementation report, independent review, final checks, proof, and PR.
 
-A qualification process that cannot start returns a resumable transport outcome without consuming either budget. Once launched, its existing prepared/launched receipt reserves one repair attempt; restart proves process absence and recovers its report, or requires an unchanged launch baseline before retrying. A dirty resumed worktree does not skip qualification. The main implementation cycle advances only after its own launch is durably recorded. Timeout and cancellation retain ownership until the complete process group is proven absent. Unprovable process-group quiescence or an unreported changed worktree fails closed. Invalid scoped policy remains a resumable no-effect outcome so a package-side policy correction can continue the existing run instead of replaying a terminal failure.
+A qualification process that cannot start returns a resumable transport outcome without consuming either budget. Launch does not reserve or spend a semantic repair. Restart reconstructs the persisted scoped failures and correlation, observes the canonical invocation, and either adopts its exact report/result or retains the fence. The main implementation cycle likewise advances only for phase-owned semantic rework, never for transport. Timeout and cancellation retain ownership until the complete process group is proven absent; an unreported changed worktree remains fenced without relaunch. Invalid scoped policy remains a resumable no-effect outcome so a package-side policy correction can continue the existing run instead of replaying a terminal failure.
 
 Once qualification is green, the issue implementation starts. After independent review clears, the Runner executes the same policy against the complete change. Every final check must pass; a nonzero result becomes a durable task-owned repair finding and starts another implementation cycle if the five-cycle budget remains. There is no output-hash attribution and no `unchanged-failure` success state. Passed final results are reused on a safe resume, while any new repair cycle clears stale final-check and proof bindings.
 
-Once no task-owned check failure remains, the Runner fingerprints the reviewed files and content, stages the complete validated change, and verifies that staging did not change either binding. It then mints a `CheckedChange` capability containing:
+Once no task-owned check failure remains, the Runner captures the reviewed bytes
+twice with a private index initialized from expected HEAD. Tracked deletions,
+mode changes, symlinks, and non-ignored untracked files enter the candidate;
+ignored untracked files and only the configured untracked proof root do not. The
+two trees and canonical path sets must match. The shared index is unchanged.
+
+The stable tree is pinned by a synthetic single-parent commit under a
+package-owned candidate ref. Direct review, each qualification/final check, and
+Acceptance Proof run in a fresh detached worktree at that commit. A durable lease
+records preparation and, before child execution proceeds, PID/process-group
+ownership. Results are accepted only after HEAD, tree, and non-proof changes are
+still exact.
+
+Legacy `CheckedChange` V1 keeps its original mutable snapshot semantics. New
+runs mint V2 with:
 
 - canonical repository, run ID, issue number, and cycle;
-- base and head SHA;
-- index tree SHA;
-- tracked and untracked content hashes;
-- worktree identity;
+- base SHA and the complete candidate binding (binding ID, expected HEAD,
+  candidate commit/tree, candidate ref, changed files, and worktree identity);
 - exact changed files;
 - passed check records and check-policy hash;
 - package and proof schema versions.
 
-Any later change to Git, the index, tracked or untracked content, worktree identity, changed files, or check policy invalidates the capability.
+V2 freshness compares candidate binding/tree and check policy, so unrelated
+shared-index edits cannot invalidate or authorize the proof input.
 
 ## 9. Acceptance Proof
 
 Acceptance Proof is independent from both implementation and code review. The `acceptance-proof` worker receives the frozen issue criteria and a nominal checked-change capability. It runs in a separate contained process and may write only below its proof-owned artifact root.
 
+Its proof record embeds the canonical durable invocation fence: exact attempt,
+workflow generation, prompt facts, host/boot/PID/process-start/PGID identity,
+report path, and proof-safe worktree baseline. Restart performs one report and
+process observation per tick, adopts only the exact attempt-owned report and
+hash-bound artifacts, and never relaunches while ownership is live or unknown.
+Infrastructure uncertainty spends no proof repair budget. Runner-classified
+malformed output spends the single existing report-repair bit exactly once and
+binds the complete pre-repair artifact inventory so report-only repair cannot
+modify or manufacture evidence. Immutable runner-owned iOS helper, lease,
+owner, xcrun, runtime, and device-type facts are part of the same invocation
+correlation and proof binding.
+Proof Reports cannot claim completed checks; only the nominal `CheckedChange`
+receipts can satisfy check evidence references.
+
+For V2, proof runs against its own candidate materialization. Publishable
+artifacts are hash-validated and copied back idempotently without following
+symlinks; product bytes remain immutable. The same candidate tree then becomes
+the durable commit intent and the observed publication commit tree.
+
 The Runner validates:
 
 - the exact Proof Report schema and status semantics;
@@ -247,7 +285,7 @@ Local command output and static-inspection evidence may contain machine paths be
 
 Browser proof validates current workflow evidence rather than accepting an isolated screenshot. For a configured Android surface, the trusted Runner durably reserves preparation before starting the configured AVD on an unused port with a clean ephemeral data directory. The lease records both PID and process-start identity so replay cleanup never kills a foreign emulator after port reuse, and ownership is rechecked throughout boot, install, navigation, and capture. The Runner removes any prior APK target, executes only a bounded, cancellable, process-group-owned `flutter build apk` recipe, snapshots the fresh no-symlink result outside the worker-writable tree, and installs only that exact digest-bound snapshot. It launches the application, retries exact accessibility-label navigation within configured bounds, and captures proof-bound screenshot, validated UI hierarchy, PID-scoped log, and lease. The contained proof worker can inspect immutable-digest-bound worktree artifacts but cannot invoke `adb`, the emulator, Flutter, or an Android lease helper. Terminal or exceptional proof settlement performs replay-safe lease cleanup, stops only the same Runner-created process, and removes only its validated temporary data directory. Existing physical devices, user emulators, IDE sessions, and Flutter processes are observed but never taken over. Android infrastructure or startup failure is recorded as an unfinished-UI-proof warning and does not alone block delivery; successful Android proof remains strict and cannot be claimed without the complete validated artifact set.
 
-`needs-rework` findings return to the same implementation loop and consume another cycle. External, safety, malformed, quiescence, or exhausted outcomes are mapped to typed run results. Only `passed` proof produces a proof receipt and permits publication.
+`needs-rework` findings return to the same implementation loop and consume another cycle. External, safety, malformed, quiescence, or exhausted outcomes are mapped to typed run results. A passed receipt is persisted before candidate cleanup and remains monotonic while cleanup's existing effect/postcondition settlement retries; publication remains forbidden until cleanup is proven settled.
 
 ## 10. Runner-owned publication
 
@@ -378,6 +416,6 @@ npm pack --dry-run --json
 
 The build deletes `dist` before TypeScript compilation so removed modules cannot survive in tests or the tarball. `prepack` verifies the committed workflow and rebuilds from a clean output directory.
 
-`npm run smoke:live` packs and installs the exact package bytes into a temporary consumer and mutates only the configured scratch GitHub repository. The default `core-release` profile proves package installation through real model-backed operations, browser evidence, and a safety-negative path. Cleanup verifies that run-owned issues, PRs, branches, labels, worktrees, and temporary directories are absent.
+`npm run smoke:live` packs and installs the exact package bytes into a temporary consumer and mutates only the configured scratch GitHub repository. The default `core-release` profile proves package installation through real model-backed operations, browser evidence, and a safety-negative path. The supplemental `authoritative-candidate-publication` scenario injects a stale shared-index entry and proves that V3 candidate-bound checks, the exact published tree, pin release, and immutable execution cleanup all converge on final worktree bytes. Cleanup verifies that run-owned issues, PRs, branches, labels, worktrees, and temporary directories are absent.
 
 Live smoke is not a normal local test and must run only with explicit authorization. Release publication is owned by the GitHub release workflow after the release commit reaches `main`.

package/internal-workflow/docs/agents/bug-workflow-routing.md

@@ -4,21 +4,23 @@ Use the bug skills by user intent and feedback-loop quality:
 
 - `bug-root-cause-explainer`: diagnosis-only. Use when the user asks why, wants root cause, options, or no edits. Stop before implementation.
 - `diagnosing-bugs`: feedback-loop builder. Use when the bug is hard, flaky, unclear, performance-related, or cannot be proven with a tight red/green signal.
-- `code-debugger`: implementation. Use when the user asks to fix, chose a fix path, or the bug is obvious and reproducible.
+- `implement`: implementation. Use when the user asks to fix, chose a fix path, or the bug is obvious and reproducible.
 
 Handoffs:
 
 - Explainer -> Diagnosing Bugs when root cause cannot be proven without a reliable loop.
-- Explainer -> Code Debugger after the user chooses a fix path.
-- Code Debugger -> Diagnosing Bugs when implementation discovers the bug is unclear, flaky, or lacks a red-capable signal.
-- Diagnosing Bugs -> original intent: return diagnosis to the explainer path, or apply the fix through Code Debugger.
+- Explainer -> Implement after the user chooses a fix path.
+- Implement -> Diagnosing Bugs when implementation discovers the bug is unclear, flaky, or lacks a reliable signal.
+- Diagnosing Bugs -> original intent: return diagnosis to the explainer path, or apply the fix through Implement.
 
 Inside an active user-authorized implementation/TDD flow, keep a reviewer repair
 in that same TDD activation only when the defect is high-confidence,
 source-required, inside the approved behavior/Seam, and has bounded trigger,
 cause, and repair. Group related cases by protected invariant before one
-consolidated repair batch. New product intent, a new Seam, or a risky trade-off
-stops for user approval. A separately authorized fix with no active flow, or an
-ambiguous reproduction/cause/repair, still routes through `code-debugger`.
+consolidated repair batch for the current reviewed revision. Continue repair,
+affected proof, and targeted Review until approval. New product intent, a new
+Seam, or a risky trade-off stops for user approval. A separately authorized fix with no active flow routes
+through `implement`; ambiguous reproduction/cause/repair first routes through
+`diagnosing-bugs`.
 
 Do not collapse diagnosis-only, feedback-loop construction, and implementation into one response unless the user explicitly asked for that full flow.

package/internal-workflow/docs/agents/coding-skill-routing.md

@@ -1,123 +1,173 @@
 # Coding Skill Routing
 
-This file is the normative global route and ownership policy. Keep repository
-commands, domain facts, credentials, deployment assumptions, and product
-behavior in repository `AGENTS.md`, `CONTEXT.md`, ADRs, or local skills.
-
-## Ownership
-
-- Personal skills live only in `../../skills`.
-- `agents/openai.yaml` owns invocation metadata; `agents/*.toml` owns named-role
-  model and effort.
-- A shared rule has one owner. Callers link to it instead of copying its prose.
-- Skill-specific detail belongs in that skill's `references/` and loads only
-  when its branch is active.
-- Root owns the user dialogue, decisions, critical path, integration, and final
-  handoff. A reviewer child owns independent review.
-
-## Default Implementation Route
-
-`medium` is the default for behavior-changing implementation. Use:
-
-- `simple` only for a tiny local change with one obvious proof;
-- `medium` for a clear coherent outcome with settled authority, one ownership
-  path, and credible affected validation—even across several files, modules,
-  API, persistence, or shared state;
-- `high` only when a sensitive mechanism has both a material failure
-  consequence and an uncertainty amplifier such as unclear ownership,
-  cross-trust effects, non-local recovery, an unproven external contract, or
-  proof that cannot isolate the dangerous state.
-
-Prefer direct root implementation for `simple` and ordinary `medium` work. Use
-`$implementation-spec-maker` only for a real execution decision or coordination
-gap. Use `$tickets-orchestrator` only for an approved ticket graph, real delivery
-dependencies or disjoint parallel slices, or an explicit orchestration request.
-Do not manufacture PRDs, tickets, specs, agents, or review checkpoints from
-file count or generic risk labels.
-
-## Core Routes
-
-| Situation | Route |
+This file is the normative global coding route. Repository commands, product
+facts, runtime constraints, and domain language remain in repository policy.
+
+## Shared Kernel
+
+- **Authority** — perform only the requested outcome and actions authorized by
+  the user, Parent PRD, executable ticket, and repository policy. Planning or
+  publication never authorizes implementation. Normal direct and single-ticket
+  Implement authority includes one scoped local commit after proof and
+  applicable Review unless user or repository policy explicitly forbids or
+  reserves Git. Push and PR require separate authority.
+- **Preservation** — preserve unrelated and concurrent work plus user-owned
+  runtimes. Dirty overlapping or unisolatable scope blocks the affected write
+  and commit.
+- **Proof** — claim only the observable outcome proved through the real caller
+  seam. Missing required proof or independent-review approval blocks completion
+  and the affected commit.
+
+These principles are checks, not workflow state or durable artifacts.
+
+## Main Route
+
+The user-facing coding flow is Plan, Implement, Review.
+
+- [`$plan`](../../skills/plan/SKILL.md) owns product decisions and multi-ticket
+  planning composition. It is the sole planning-composition entrypoint.
+- [`$implement`](../../skills/implement/SKILL.md) is the single execution owner
+  for clear features, fixes, obvious local edits, and executable tickets.
+- [`$code-review`](../../skills/code-review/SKILL.md) is the direct Review
+  entrypoint.
+
+Direct non-ticket work stays in the current root context. Do not create a spec,
+ticket, or worker merely because a change spans files or touches an important
+contract. A real product or ownership decision gap returns to Plan. An approved
+multi-ticket dependency graph routes to `$tickets-orchestrator`; a single
+executable ticket never does.
+
+Grilling uses dependency-aware frontier rounds. `$grilling` is the model-invoked,
+write-free interview primitive; `$domain-modeling` is the model-invoked sole
+domain-document writer. `$grill-me`, `$grill-with-docs`, and `$wait-what` are
+explicit-only. Explicitly typed wrappers win: `$grill-me` remains write-free
+even when its prompt mentions terminology or ADRs, while `$grill-with-docs`
+keeps the whole `$grilling` interview write-free and invokes
+`$domain-modeling` only after an empty frontier and explicit confirmation.
+Implicit `$grilling` is write-free and cannot mutate domain docs.
+
+`$writing-for-agents` is a model-invoked discipline for agent-consumed
+documents and complements `$skill-creator`; it is not a router. Use
+`$resolving-merge-conflicts` only for actual Git conflicts or an explicit
+conflict-resolution request. It composes `$domain-modeling` as sole content
+writer for domain-document conflicts, while each Git operation remains gated by
+existing authority. `$documentation-gardener` may audit domain docs but routes
+every authorized domain-document mutation through `$domain-modeling`.
+
+Diagnosis-only work uses `$bug-root-cause-explainer`. Hard, flaky, unclear, or
+performance bugs use `$diagnosing-bugs` to establish a reliable signal, then
+return to Implement when a fix is authorized. External multi-source uncertainty
+uses `$research`. A requested throwaway logic or UI experiment uses `$prototype`
+to answer one bounded design question, then returns production delivery to
+Implement. Grilling, TDD, to-spec, to-tickets, diagnosis, research, prototype,
+and the graph-only Tickets Orchestrator are internal or side primitives.
+Specialized runtime and platform skills remain side tools and do not compete
+with the main flow.
+
+## Phase boundaries
+
+Make a context choice only when one phase has actually completed and another is
+about to begin; never interrupt a live phase merely because the conversation is
+long. Apply these conditions in order:
+
+1. **Continue** when the next phase uses the current conversation as a primary
+   source and the same active owner and authority still apply.
+2. **Use an existing fresh-context route** only when the active workflow already
+   requires one, such as the single-ticket implementer or independent Review.
+3. **Use an authorized stable-role child** only for bounded AFK work that the
+   active skill already permits; root retains dialogue and integration.
+4. **Compact through the platform** only when relevant same-owner work must
+   continue in the current conversation and observed context pressure makes a
+   lossless continuation unreliable.
+
+These are branch conditions, not a token threshold, a new handoff skill, or a
+competing router. Plan, Implement, Review, prototype, `$to-spec`, and
+`$to-tickets` keep their existing ownership and stop boundaries.
+
+## Implement Context
+
+- A direct request is implemented by root in the current context.
+- One executable ticket launches exactly one fresh `implementer` child. Root
+  supplies the complete ticket, Parent PRD, applicable repository policy, and
+  bounded write scope; verifies the child identity and completed wait; and
+  remains the only Git owner.
+- Multiple executable tickets are graph work and remain owned by
+  `$tickets-orchestrator`.
+
+Children do not talk to the user, spawn grandchildren, or perform Git actions.
+Root integrates only isolated worker output and never overwrites unrelated work.
+
+## TDD, Proof, And Review
+
+Use [`$tdd`](../../skills/tdd/SKILL.md) where possible: an observable behavior
+change has a natural public seam and a meaningful failing signal can precede
+the implementation. Otherwise use direct proof. Do not manufacture tests for
+docs, copy, formatting, mechanical config, deletion, or an outcome that cannot
+fail meaningfully before the edit.
+
+A change is substantial when its behavior or contract goes beyond an obvious
+local edit. This includes a public API, persistence, auth or payment,
+concurrency or shared state, and cross-module interaction. Substantial settled
+work launches one fresh `spec_reviewer` and one fresh `standards_reviewer` in
+parallel. Spec checks the result against the request, issue, or Parent PRD;
+Standards checks correctness, repository rules, cleanup, and legacy or duplicate
+ownership.
+
+The wait must complete and the coordinator must approve the settled diff from
+the completed independent evidence.
+Docs, copy, formatting, mechanical config, and an obvious local correction may
+finish with direct proof and no reviewer. Reviewer failure or timeout blocks
+approval; root does not replace independent review with self-review.
+
+A Review blocker requires a concrete defect or proof gap causally linked to an
+explicit obligation, existing invariant, or mandatory repository rule. The
+reviewer verdict is evidence, not authority: coordinator approval exists when
+the completed independent review has no verified blocker or required-proof
+gap. A Fowler smell, general improvement, preference, or uncertain concern is a
+non-blocking observation without that link. Review remains read-only. Initial
+Review runs both lenses; targeted Review runs only the affected lens, or both
+when the repair is mixed or cannot be isolated.
+
+For direct or single-ticket substantial work, Implement consolidates every
+verified blocker into one repair batch for that revision. The original
+Implement authority covers every verified repair that does not widen the
+authorized outcome without another user
+confirmation. After repair it reruns affected proof and launches the affected
+fresh reviewer or reviewer pair over only the repair delta, repaired blockers,
+direct impact cone, and affected proof. Untouched previously approved scope
+retains approval. This loop continues until approval; reviewer count is not a
+stop condition. A complete two-lens Review repeats only when repair impact
+cannot be isolated from previously approved scope.
+
+Graph children receive no per-ticket delivery Review. After every checkpoint,
+Tickets Orchestrator owns the initial cumulative review over the complete Parent
+range, then follows the same unlimited repair loop with targeted Review of each
+repair delta and directly affected Parent obligations.
+
+Proof and applicable review must approve before staging or commit. Direct and
+single-ticket Implement creates one scoped local commit by default when the
+worktree is isolatable. Explicit user or repository policy that forbids or
+reserves Git overrides that default. Push and PR always require separate
+authority.
+
+## Stable Roles
+
+Skills request only these stable roles; concrete model and reasoning effort are
+central configuration details:
+
+| Need | Role |
 | --- | --- |
-| Tiny, clear, low-risk edit | `$small-task-implementer` after its Fit Gate |
-| Clear feature or fix | Apply the TDD Fit Gate; when it fits, use Root + one `$tdd` activation, otherwise affected validation |
-| Missing execution detail | `$implementation-spec-maker` -> artifact review -> `$spec-implementer` |
-| Approved implementation spec | `$spec-implementer` |
-| Approved dependency graph or explicit orchestration | `$tickets-orchestrator` |
-| Product discovery or ticket decomposition | `$to-spec`, `$spec-to-tickets`, or `$wayfinder` as applicable; stop before delivery |
-| Explain-only bug | `$bug-root-cause-explainer`; no edits |
-| Confirmed bounded bug fix | Apply the TDD Fit Gate, then `$tdd` + `$code-debugger` when it fits; otherwise `$code-debugger` + affected validation |
-| Hard, flaky, unclear, or performance bug | `$diagnosing-bugs` before the explain/fix route |
-| Review request | `$code-review` in the profile-selected reviewer child |
-| External multi-source uncertainty | `$research`; narrow documentation lookup stays inline |
-| Commit request | `$commit`; push/PR still require separate authority |
-
-Generated planning artifacts and labels never authorize implementation. One
-deterministic approved ticket may run directly; a graph follows the authorized
-delivery workflow.
-
-## TDD And Review
-
-Apply `$tdd` only when all three Fit Gate conditions hold:
-
-1. The change alters observable behavior.
-2. A natural public seam can prove that behavior.
-3. A new test will fail before the change for the intended behavioral reason.
-
-Otherwise use existing regression tests plus affected validation. Do not invoke
-TDD merely because implementation files change, and do not manufacture RED
-tests for behavior-preserving cleanup, dead-code deletion, documentation, copy,
-formatting, generated assets, package maintenance, simple config, builds, or
-read-only work. For mixed tasks, activate `$tdd` only for the behavioral slice.
-An absence or architecture guard added after cleanup is validation, not a TDD
-cycle.
-
-Review applicability lives in [`review-gates.md`](review-gates.md). Shared
-Full/Closure mechanics live in [`review-protocol.md`](review-protocol.md).
-Artifact review is owned by
-[`implementation-spec-review/references/review-loop.md`](../../skills/implementation-spec-review/references/review-loop.md);
-approved-spec implementation review is owned by
-[`spec-implementer/references/review-loop.md`](../../skills/spec-implementer/references/review-loop.md).
-
-Root never substitutes self-review for a required independent reviewer. Use one
-`reviewer_fast` for `simple`, one `reviewer_standard` for `medium`, and two
-disjoint `reviewer_deep` tracks for `high`. A reviewer Adapter executes inline
-only after it is already inside that assigned child.
-
-## Delegation
-
-Run work inline by default. Delegate only when the user, an invoked skill, or
-repository policy authorizes it and the task benefits from independent review,
-isolated deep analysis, or disjoint implementation ownership.
-
-| Need | Named role |
-| --- | --- |
-| Mechanical inventory | `explorer_quick` |
-| Bounded cross-module trace | `explorer_fast` |
-| Ambiguous architecture, contract, or cause | `analyst_deep` |
-| Primary-source external research | `researcher_standard` |
-| Independent review | `reviewer_fast`, `reviewer_standard`, or `reviewer_deep` by profile |
-| Approved isolated implementation slice | `implementer_standard`; `implementer_deep` only for material uncertainty |
-
-Keep the root critical path local. Use at most two explorers for disjoint
-questions and at most two parallel implementers with disjoint write scopes.
-Children do not conduct user dialogue or spawn grandchildren.
-
-## Validation And Runtime Safety
-
-Use targeted behavior proof plus the smallest affected integration check for
-simple and medium work. Run a full repository suite only when repository policy
-requires it, a broad shared contract cannot be isolated, or the task is `high`.
-
-For Flutter UI, follow [`tool-usage.md`](tool-usage.md): platform QA owns UI
-work and `$flutter-attach-session` is only the attach-safe runtime layer. Treat
-live app, IDE, VM Service, and `flutter run` sessions as user-owned.
-
-Read local evidence before external search: applicable `AGENTS.md`, `CONTEXT.md`,
-ADRs, manifests, lockfiles, tests, scripts, and code owners. Mark missing facts
-unconfirmed rather than inventing them.
-
-Contract-risk implementation uses
-[`contract-test-ledger.md`](contract-test-ledger.md) only for material
-invariants. Long framework lenses, examples, and recipes remain skill-local and
-load on demand.
+| Root dialogue, integration, and Git ownership | `root` |
+| One isolated executable ticket | `implementer` |
+| Requirement fidelity and scope drift | `spec_reviewer` |
+| Correctness and repository standards | `standards_reviewer` |
+| Bounded repository exploration | `explorer` |
+| Independent bounded design alternative | `explorer` |
+| Primary-source external research | `researcher` |
+
+## Runtime Safety
+
+For Flutter UI, follow [`tool-usage.md`](tool-usage.md). Treat live app, IDE, VM
+Service, and `flutter run` sessions as user-owned. Use the documented
+non-destructive attach path only after ownership discovery; never replace or
+terminate a user-owned session without explicit authority.

package/internal-workflow/docs/agents/tool-usage.md

@@ -4,13 +4,13 @@
 
 Local Flutter UI work always uses a platform QA skill plus the runtime ownership gate:
 
-- Android emulator: use `$flutter-android-debug` as the lifecycle orchestrator and
-  `test-android-apps:android-emulator-qa` for navigation, interaction, UI trees,
-  screenshots, and logcat.
+- Android emulator: always use `$flutter-android-debug` as the lifecycle orchestrator
+  and `test-android-apps:android-emulator-qa` for navigation, interaction, UI trees,
+  screenshots, and logcat, including inspection-only and screenshot-only requests.
 - iOS Simulator: use `$flutter-ios-debug` for environment/login gates, navigation,
   interaction, screenshots, and visual comparison.
-- Use `$flutter-attach-session` only to discover the runtime owner and perform
-  reload/restart when that session is safe for this agent to control.
+- Use `$flutter-attach-session` to discover the runtime owner and perform
+  reload/restart against the selected live session.
 
 Before any install, launch, attach, reload, restart, terminate, or force-stop:
 
@@ -18,17 +18,28 @@ Before any install, launch, attach, reload, restart, terminate, or force-stop:
    owner, and expected backend/environment.
 2. Treat any live PID, VM Service, IDE debug adapter, `flutter run`, or visible app as
    user-owned state.
-3. If an IDE/debug adapter or machine run owns DevFS, do not create a second attach
-   controller. Use the owning IDE/terminal reload action or ask the user to trigger it.
-   A standalone interactive terminal run is the only exception, and only when
-   discovery marks it attach-safe and the helper receives its confirmed PID.
+3. If an IDE/debug adapter or machine run owns DevFS, never attach a second Flutter
+   compiler/controller. Preserve the session, continue only with inspection or in-app
+   navigation, and ask the user to trigger `r`/`R` through the owning controller when
+   reload/restart is necessary. Unknown owners remain blocked.
 4. Use `r` for widget/layout/style/rendering changes and `R` for startup state,
    dependency injection, providers, globals, routes, or initialization changes.
-5. For a safely attachable standalone runtime, pass the PID confirmed by
-   `discover --json` as `--expected-pid`; never execute the raw discovered attach command.
-6. Verify that the same PID and expected environment remain after each runtime or
+5. Always pass the PID confirmed by `discover --json` as `--expected-pid`; never
+   execute the raw discovered attach command.
+6. Confirm that the generated attach command preserves the selected run's effective
+   target and every `--dart-define` / `--dart-define-from-file`. Missing compile
+   identity must block runtime control rather than fall back to defaults.
+   Treat raw define values as sensitive; inspect only the helper's redacted display.
+7. Verify that the same PID and expected environment remain after each runtime or
    navigation action.
 
+The bundled `flutter_session_ctl.py` helper is the only allowed reload/restart
+transport for safely attachable standalone sessions. Never activate, open, focus, or
+automate an IDE for this purpose. Do not use IDE menus, Command Palette, keyboard
+shortcuts, `osascript`, System Events, or other GUI automation. If the helper fails or
+times out, preserve the app process and report its exact failure; do not fall back to
+the IDE.
+
 Requests to inspect, debug, navigate, capture screenshots, or verify UI do not authorize
 build/install, uninstall, app-data clearing, force-stop, process termination, replacement
 launch, or a new `flutter run`. Use those only when no live target exists and the user