nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/skills/nobrainer-tech-flow/references/delivery.md

@@ -0,0 +1,243 @@
+# Deliver the agreed outcome
+
+Read for non-trivial delivery and before reporting a blocker. Ordinary autopilot
+uses this contract. `yolo` or `yolo mode`, when explicitly requested for this
+workflow, is an alias for persistent execution of authorized work. It changes
+neither permissions, model, budget nor the host's safety controls. It is not a
+CLI flag or another skill.
+
+## Establish the goal without another prompt
+
+For substantial implementation, automatically derive an observable outcome and
+DoD from the owner's request before editing. Reuse the existing tracker; if work
+needs durable state, write a short task-local Markdown goal. Keep only acceptance,
+current progress, authority and the next useful step. Do not ask the owner to
+name the file or restate an already clear goal. Small answers need no artifact.
+
+Prefer a current short-term goal linked to the owner's long-term direction or
+maintained roadmap. Partition accepted outcomes into visible milestones, keep
+the whole goal open while a required item remains, and choose the next ready
+unit as each stage closes. Do not invent an LDD method when the acronym or
+source is unresolved.
+
+A native goal is separate: create it only when explicitly requested and supported
+under the host tool contract. Reuse an existing goal; never replace an unfinished
+goal or invent a token budget. Read back native goal creation before claiming it.
+A Markdown goal does not promise scheduled continuation or automatically press
+START. When START is owner-only, explain that requirement once; never claim it
+was resumed. Within available execution time, continue useful authorized work.
+
+When the owner requests an end-to-end result, including an idea that becomes
+an SDD, bind one overarching goal to all of that SDD's acceptance IDs. An explicit
+"execute the whole SDD" request has the same effect. Do not substitute a local milestone, plan approval,
+or test suite for the whole outcome. Automatically maintain a visible TODO:
+`[x] accepted with evidence`, `[>] executing`, `[ ] remaining`, `[!] blocked`.
+After each accepted stage, update the canonical tracker, show the changed TODO
+items and move to the next ready stage without requesting "continue". Keep
+blocked IDs open while independent stages advance. Use short stage labels; link
+long evidence. No phase silently disappears from the full-scope acceptance set.
+
+A request to set a goal or execute the whole SDD with a goal authorizes native
+goal creation when the host permits it. If the host requires an explicit native
+goal request and the wording does not meet that requirement, maintain the
+Markdown goal and ask once in BUDDY if native continuation is wanted. Never imply
+that a Markdown file activated host scheduling. Update the file after each stage;
+use native updates only for operations the actual tool supports. A host that only
+supports complete/blocked must not receive invented native progress updates.
+
+Carry authority across turns. Translate "go ahead" against the immediately
+proposed concrete action and preserve its target and exclusions. Do not ask for
+permission again for that action. New consequences outside that scope still need
+approval. A worker's completion is one milestone, not completion of the goal.
+
+## BUDDY: collect the permission package once
+
+After initial read-only discovery, identify the concrete actions needed to finish
+the whole scope. Classify each as already authorized, routine/reversible within
+scope, or requiring a missing owner decision. Resolve routine implementation
+choices yourself. Ask one bundled, plain-language question only for missing
+consequential permissions. Name exact projects/targets and effects: for example
+merge these changes, deploy this service, or create this paid resource within a
+specified ceiling. Include browser actions when they carry those effects; merely
+opening a page is not a separate permission category.
+
+Record the answer and any exclusions in the existing tracker. Do not seek a blank
+check to spend, message people, delete data or bypass controls. Unforeseen new
+consequences still need consent. Preserve refusals and ceilings across stages.
+If a late gate is unavoidable, finish its preparation first and continue any
+independent work while the question is pending.
+
+## Short work communication
+
+Use terse, natural progress text: result, TODO delta, next action. Avoid repeated
+skill announcements, schema dumps and unchanged polling narration. Do not enforce
+a word count that loses conditions, errors, commands or required human actions.
+Keep authored documents and product copy complete and natural.
+
+For a true owner blocker, say: `Blocked: <acceptance item>. Tried: <method/result>.
+You: <exact action and destination>. Then: <how work can resume>.` Include an
+exact link or copy-ready command when verified. Do not ask the owner to invent
+the next diagnostic step. A paused native goal with an owner-only START requires
+an explicit START callout, not a claim of automatic resumption.
+
+## Resolve an obstacle before escalating it
+
+Separate authority from capability: a permitted action may lack a tool, and an
+available tool may not authorize an action. Before saying BLOCKED, identify the
+exact failed operation and the acceptance item it prevents. Then:
+
+1. Check related instructions and current evidence, including prior permission.
+2. Discover the relevant supported API, CLI or browser capability. An authenticated
+   UI step is agent work when its action and target are already authorized. Inspect
+   the UI, perform the step and read back the result rather than asking the owner
+   to click merely because it is in a browser.
+3. If the preferred method is technically unavailable, try a relevant permitted
+   alternative within the same scope. Never evade an access denial, approval
+   rejection, sandbox or an explicit channel restriction through another method.
+4. A missing credential means inspect the documented credential location or normal
+   login flow without exposing secrets. Human MFA, unavailable entitlement and
+   an owner-only decision remain genuine blockers for dependent work.
+5. Continue independent acceptance items. One blocked integration cannot turn
+   an entire backlog into BLOCKED or justify unrelated speculative work.
+
+A failed test is a repair task. Missing evidence is a verification task when the
+agent can obtain it. A missing optional helper is a MAIN fallback. Poll timeouts
+are observations; preserve the same handle and use bounded waits. A terminal
+worker failure requires reconciling writes before MAIN takes over. Do not use a
+terminal failure to justify accepting unreviewed output.
+
+When no permitted path remains, report only: the blocked acceptance item, attempted
+method and observed error, why relevant alternatives cannot complete it, the exact
+missing human action/access, and what independent work was completed. Distinguish
+OWNER_ACTION, EXTERNAL_UNAVAILABLE, POLICY_DENIED and TECHNICAL_FAILURE. Apply
+native goal blocked-state rules separately; do not mark a whole goal blocked while
+useful authorized work remains. Never turn an unknown right/license into consent.
+
+## Keep review proportional to progress
+
+Review the next executable slice against concrete acceptance and failure paths.
+For a stable slice, default to one review and one focused correction verification.
+More review needs a newly evidenced material defect or changed risk, not a new
+amendment number, stylistic preference or desire for perfect prose. Preserve
+required independent/security gates; a review budget never makes a failed gate pass.
+
+After repeated review without accepted progress, stop the whole-plan loop. Deduplicate
+findings, retain blockers for the affected slice, defer non-blocking suggestions,
+and implement an already-authorized independent slice or resolve the concrete
+blocking defect in MAIN. Escalate only an actual unresolved owner choice. Do not
+reset the review budget by renaming a plan or opening a new reviewer task.
+
+Prefer maintainable code over line-count games. Honor real project limits by
+cohesive decomposition; do not invent arbitrary caps or spend worker cycles on
+blank-line shaving. Re-run only checks affected by the final change plus required
+repository checks. Finish after acceptance, not after an arbitrary quantity of
+reviews, tests or generated files.
+
+## Coordinated team execution
+
+MAIN owns the full outcome, coordination, critical path, dependencies, integration,
+owner decisions and acceptance. Before executing non-trivial work or entering a
+blocking wait, identify independent ready units and dispatch every useful eligible
+unit promptly to native workers within verified host capacity and authorized usage
+limits. Eligibility requires accepted dependencies, authority, a supported route
+and a free write scope. One visible MAIN coordinator is compatible with many native
+workers. Before a large or risky multi-writer fan-out that is not already
+executable, run the [builder-readiness check](idea-to-delivery.md#builder-readiness-check);
+skip it for already-executable plans and mechanical changes.
+
+When an eligible ready unit stays in MAIN while a useful slot is free, record the
+concrete reason in the current plan: shared mutable state, missing accepted
+dependency, unavailable capability/route, authority gate, usage limit, or a tiny or
+tightly coupled step. A missing measured speedup is not by itself a reason to keep
+eligible work in MAIN.
+
+A single bounded native delegate needs no Dispatcher queue; MAIN keeps coordination
+and acceptance. Use the [small native-worker packet](communication.md#small-native-worker-packet).
+Durable queues retain the [long-run state](long-run-state.md) and full
+Sessions/Dispatcher contract. Visible conversations follow the
+[canonical rule](../SKILL.md#choose-the-smallest-workflow); never substitute
+them for unavailable native workers.
+
+Target concurrency is the minimum of the effective host/model limit, authorized
+usage limits and useful independent ready units. A configured ceiling is not proof
+of available runtime slots. Count running reviewers, existing live workers and any
+permitted descendants too. If capacity is unknown, dispatch ready units
+incrementally within host policy and remaining quota until a capacity refusal;
+never spawn dummy probes. Reconcile uncertain spawn results by ID before retrying.
+If a send may have succeeded but returned no ID,
+reserve its possible capacity and write scope; do not retry or run that unit in
+MAIN until the host proves no worker is executing. Record delivery UNKNOWN in
+the existing tracker. This differs from proven pre-send unavailability, which
+permits MAIN fallback. A refusal reduces concurrency; it is not a goal
+blocker. Do not duplicate a unit after an uncertain send or timeout. Never bypass
+a host restriction.
+
+Use [communication](communication.md) for assignments and reports: plain
+technical English between agents by default, with the artifact language explicit
+when different. Preserve required formats and explicit language overrides.
+
+Each assignment names one bounded outcome, exact inputs/version, write scope,
+dependencies, owning method, authority, acceptance evidence, model/effort, budget
+and stop conditions. Schedule independent implementation, research and verification
+together only when mutable state does not overlap. Keep one owner for every shared
+mutable resource: files, browser/profile, test database, port, migration, generated
+artifact and integration surface. Use isolated worktrees where appropriate, then
+integrate explicitly. No duplicate investigations of the same question; read-only
+reviews may share frozen input when their questions are distinct.
+
+Use flat MAIN-owned delegation by default. Recursive delegation requires express
+assignment authority and a reserved capacity slot under the same verified host
+capacity. A host or owner prohibition remains controlling. Without reliable
+cross-tree accounting, keep delegation flat. Apply the [model policy](model-routing.md),
+including its Codex delegated preset; preserve explicit owner overrides.
+
+Prioritize work that unblocks downstream stages. MAIN advances useful integration
+or unresolved dependencies while workers execute. Queue excess ready units. On each
+worker completion, MAIN reconciles the exact returned ID, inspects the current
+artifact, assigned scope and required proof, and verifies that the worker has
+stopped writing. Then release only that unit's proven ownership, recompute readiness
+and dispatch newly ready work without waiting for unrelated slow workers. A
+worker's report, exit code or self-score does not accept its artifact.
+
+A waiting, suspended or uncertain worker has a stated reason and a bounded next
+observation in the current tracker. Reserve its scope and possible capacity until
+exact-ID readback reconciles its state. Prefer native completion notifications or
+bounded waits on the same IDs; wait only when no useful independent work remains
+for MAIN or available slots. Do not poll unchanged status as a substitute for work.
+
+Keep quota/cost ceilings, API/test-environment limits, runtime health warnings/hard
+limits, credential boundaries, owner gates and refusal handling. Shared sequential
+work remains serial. No filler units, speculative future work, fixed swarm or
+duplicated full-context prompts. Do not split a tiny task merely to reach a number.
+Measure progress by accepted outcomes and elapsed delivery, never by agent count
+or messages sent. Claims about speed, token use or quality require measured
+evidence; dispatch alone proves none of them.
+
+## GDD: goal-driven delivery through milestones
+
+The [approved-plan autopilot loop](autopilot.md) owns select, execute, check,
+review, correct and advance. This section owns the milestone map and its state
+transitions; use both without creating a second tracker.
+
+GDD is this workflow's execution pattern, not a new skill or a claim of inventing
+Goal-Driven Development. SDD owns requirements; the existing task tracker owns
+milestones and current state. For whole-SDD execution, derive milestones from its
+acceptance set. Each milestone records an ID, observable outcome, acceptance IDs,
+dependencies, owner, write scope, evidence and state. Every required acceptance ID
+must be assigned; cross-cutting criteria need a final integrated check.
+
+Use `PENDING -> READY -> RUNNING -> VERIFYING -> ACCEPTED`. `READY` requires
+accepted dependencies, necessary permission and a free write scope. A failed
+verification returns to repair; an external dependency marks only the affected
+milestone `BLOCKED` with its evidence and unblock action. Resume after fresh
+verification of that action. Superseded requirements invalidate only affected
+milestones and downstream evidence. Completed workers never self-accept.
+
+After each milestone, MAIN verifies evidence, updates the existing TODO and
+selects the next ready work without waiting for a new user prompt. Independent
+milestones may run together up to the target concurrency in
+[coordinated team execution](#coordinated-team-execution). Keep one overarching goal open
+until every required milestone and integrated DoD passes. Do not complete and
+replace the native goal for each milestone. Native goals are optional mirrors;
+Markdown remains the portable record. Host pauses or quotas can suspend execution,
+so preserve the next action without promising an automatic wakeup.

package/skills/nobrainer-tech-flow/references/idea-to-delivery.md

@@ -0,0 +1,82 @@
+# From an idea to a checked result
+
+Use when the owner supplies a goal or idea without an implementation plan.
+An idea is enough to begin discovery. It is not approval for every possible
+product choice or external effect.
+
+## Make the idea executable
+
+1. Read the existing project and relevant decisions. State the desired result,
+   audience and smallest useful scope. Separate supplied facts (`OBSERVED`),
+   reasonable assumptions (`INFERRED`), proposed choices (`RECOMMENDED`) and
+   unresolved facts (`UNKNOWN`). Do not present your defaults as owner decisions.
+2. Choose routine, reversible implementation details within the request.
+   Explain consequential assumptions. Ask one focused round only for missing
+   choices that change the product, acceptance, risk or authority; continue
+   independent work while that decision is pending.
+3. Use the [spec template](../../nobrainer-spec-driven-development/references/spec-template.md) when SDD is requested or its
+   maintenance is justified. Otherwise use Flow's compact scope and plan.
+   If a selected install lacks SDD, report that limit and use the documented
+   installation path within authorization; do not claim the skill ran.
+   Map each requirement to a sequential acceptance ID (`AC01`, `AC02`, …),
+   an observable check and the delivery layer that check establishes.
+4. Review the contract before implementation. Record the existing owner
+   instruction as approval when it already covers the defined scope; do not
+   manufacture approval for an unresolved product/risk choice. Freeze the
+   reviewed revision using the project's hash convention.
+5. For an end-to-end request, start the [autopilot loop](autopilot.md)
+   with those acceptance IDs. Planning and a generated spec are milestones.
+   Execute, verify, review where required, correct confirmed defects, and
+   continue to the requested delivery layer within existing authorization.
+
+## Builder-readiness check
+
+Before a large or risky multi-writer fan-out, assign one bounded read-only pass to
+a native builder. Use MAIN when native workers are unavailable and disclose that
+limit. Ask what would stop the first assigned unit from being implemented:
+
+- a missing interface or caller;
+- an unavailable tool;
+- a conflicting scope or shared resource;
+- an unresolved product decision;
+- impossible proof for an acceptance criterion.
+
+Return concrete blockers with source references and the affected unit or acceptance
+ID. MAIN resolves routine choices within the request. Only material owner decisions
+go to the existing single clarification round; do not start another requirements
+round or ask the owner to settle routine code choices.
+
+Skip this check for already-executable plans and mechanical changes. End after one
+bounded pass. It does not authorize new scope or consequential effects, replace
+required review, or demand elegance without a concrete implementation defect.
+Keep findings in the current plan; do not create another tracker.
+
+## Keep the contract and outcome connected
+
+Keep one acceptance ledger. Link it from the spec when the project uses a
+separate tracker. Record each ID's current evidence, remaining check or blocker;
+do not copy mutable status into several files. Use the SDD lifecycle for the
+overall spec state. Test completion does not silently accept a pending deploy.
+
+Routine file-list and execution-order changes stay within the existing scope.
+New behavior, risk, external effects or material acceptance changes require
+the SDD change-control path. Preserve blocked criteria while unrelated work
+advances. Never drop a requirement to make the ledger look complete.
+
+Follow [communication](communication.md). English technical specs, procedures
+and reports default to Writing's `TECHNICAL` mode unless another mode is
+requested. Preserve the requested language and exact constraints.
+A small diagram can explain dependencies; use an interactive artifact only
+when interaction helps a real decision and the host supports it. Do not add
+media, dependencies, paid calls or publication merely to make the output richer.
+
+## Stop at the requested boundary
+
+- **Spec only:** deliver the reviewed specification and actual approval state.
+  Do not implement it or mark product delivery `ACCEPTED`.
+- **End to end:** finish all required acceptance IDs with inspected evidence,
+  then report the result, checks and remaining uncertainty.
+- **Missing material decision:** name the exact choice and affected IDs; keep
+  useful independent work moving. Do not infer permission to publish or spend.
+- **Session interruption:** checkpoint the existing tracker. A saved file alone
+  does not restart a client or provide an unattended execution service.

package/skills/nobrainer-tech-flow/references/long-run-state.md

@@ -0,0 +1,209 @@
+# Long-run state and recovery
+
+Read this reference only after Flow's detailed-ledger gate passes. It preserves
+safe resume and delegated coordination without forcing machine ceremony into
+ordinary single-session work.
+
+## One canonical ledger
+
+Use the project's existing Markdown tracker when suitable. Otherwise create one
+small task-local Markdown artifact. It is the only mutable owner of execution state;
+specifications define required truth, reports provide evidence, and the wiki
+stores durable knowledge.
+
+Record the run boundary once:
+
+```text
+Run:
+Frozen request/spec and fingerprint:
+Base checkout and commit:
+State owner:
+Integration owner:
+Owner gates:
+Stop conditions:
+```
+
+Use one row per independently auditable outcome, not per command:
+
+```text
+ID | Outcome | Method | Owner/session | Dependencies | Write scope |
+Proof | Owner gate | Status
+```
+
+`Method` is one primary owner: a NoBrainer skill, maintained project capability,
+reviewed temporary capability or `DIRECT` for a truly mechanical step. Known
+implementation, verification, correction, integration and closeout work must
+appear before execution starts.
+
+Useful states are `PENDING`, `READY`, `RUNNING`, `BLOCKED`, `REPORTED`,
+`AUDITED`, `ACCEPTED`, `CORRECTION_REQUIRED`, `OWNER_DECISION_REQUIRED` and
+`STOPPED`. A report or green
+exit code cannot move a row to `ACCEPTED` without current proof.
+
+The owner-facing Progress checklist is only a view of this ledger. Update both
+from the same evidence at meaningful transitions.
+
+## Durable goal and resume
+
+When this reference is active, keep the portable goal in an existing Markdown
+tracker or one task-local Markdown `GOAL_FILE`. Do not create a second mutable
+status owner. The minimum readable block is:
+
+```text
+GOAL_ID: <stable identity>
+OUTCOME: <observable result>
+NON_GOALS: <bounded exclusions>
+DOD: <acceptance checks>
+STATUS: ACTIVE | OWNER_DECISION_REQUIRED | COMPLETE | BLOCKED
+CHECKPOINT: <last verified state and evidence pointer>
+NEXT_SAFE_ACTION: <one action or NONE>
+SESSION_POLICY: <policy reference or NONE>
+LAST_HEALTH_READBACK: <event, result, evidence pointer>
+```
+
+The Markdown goal works without any native goal API. A host-native goal is an
+optional mirror and control handle, used only when available and authorized by
+the host's tool rules; never create it merely because this reference was loaded.
+After session start, compaction or a verified clear, read `GOAL_FILE` from disk,
+verify `GOAL_ID`, repository, checkout, HEAD/dirty state, status and evidence,
+then reconcile any native goal actually used and continue from `NEXT_SAFE_ACTION`. A
+transcript summary, cached plan or native goal never overrides newer file state.
+The same file owns the outcome-level TODO rows; health gates may checkpoint them
+but cannot mark work complete. On every material transition, update the current
+row, evidence and next safe action before starting another unit.
+
+## Recovery card
+
+For unattended or resumable work, record:
+
+```text
+Trigger and frozen inputs:
+Expected outputs:
+Checkpoint and resume command/path:
+Idempotence key or duplicate-prevention rule:
+Retry budget and blocker fingerprint:
+Evidence location:
+Rollback:
+Attention budget and urgent owner events:
+```
+
+Do not invent a retry path. If a step cannot be safely resumed or repeated,
+state that before starting it and require the appropriate checkpoint or owner
+gate.
+
+At session start or after compaction, reconcile the exact checkout, base/HEAD,
+dirty state, ledger fingerprint, active sessions/writers, last accepted proof
+and next `READY` row. A stale summary never authorizes a successor.
+
+## Bounded turns and runtime release
+
+An outcome or goal may span bounded turns, but it never grants an unlimited
+turn/session lease. Run `SESSION_HEALTH_GATE` at `START`, `AFTER_COMPACTION`,
+`MATERIAL_TRANSITION` and `BEFORE_CLOSEOUT`. The policy is host/config supplied;
+these are policy fields, not universal limits:
+
+```text
+TURN_AGE_LIMIT: <configured value | NONE>
+HISTORY_SIZE_LIMIT: <configured value | NONE>
+COMPACTION_LIMIT: <configured value | NONE>
+COST_OR_TOKENS_LIMIT: <configured value | NONE>
+WARNING_THRESHOLD: <configured value | NONE>
+HARD_THRESHOLD: <configured value | NONE>
+SIGNALS: <turn age, history size, compactions, cost/tokens, owned workers>
+```
+
+Each signal is a readback value, `UNKNOWN`, `UNSUPPORTED`, or `NONE` when no
+limit is configured. Missing expected telemetry is not `HEALTHY`. Missing optional
+telemetry lowers that proof claim but does not block safe work: use bounded work
+units and the Markdown checkpoint. An explicitly required hard budget that cannot
+be measured or enforced blocks only the work depending on that guarantee; report
+the missing capability instead of claiming the cap holds. The gate
+result is `HEALTHY | WARNING | ROTATE_REQUIRED | UNKNOWN | UNSUPPORTED`. A
+warning checkpoints the goal/TODO and stops starting optional workers or large
+new units while continuing the safe current unit. A hard limit means persist `GOAL_FILE`,
+write a compact handoff, verify no write is in flight, and select:
+
+```text
+CLEAR_MODE: HOST_CLEAR | END_TURN | MANUAL_REQUIRED | UNSUPPORTED
+```
+
+Use `HOST_CLEAR` only when the host advertises the capability and readback
+proves the same goal file remains durable and no task-owned writer is active.
+Otherwise end the turn or require manual action. Never claim a clear from a
+command submission alone. Creating or rotating a session requires current or standing task authorization
+under the Sessions startup contract; do not infer it from a timeout, compaction
+or continued goal. Explicit Flow invocation activates assessment only; stricter host
+consent requirements still apply.
+
+`task_complete` closes an outcome only; it does not prove `RUNTIME_RELEASE`.
+Record `RUNTIME_RELEASE` as `VERIFIED | NOT_RELEASED | UNKNOWN | UNSUPPORTED`.
+Where the host can read back task-owned browser, tool or subprocess workers,
+`VERIFIED` requires no owned worker remains. Active workers are
+`NOT_RELEASED`; missing or unsupported readback lowers runtime proof and never
+supports a clean-runtime claim.
+
+An empty ready set is not itself a blocker. If work is `RUNNING`, wait for its
+bounded result; if `REPORTED`, audit it; if all acceptance is met, finish. If all
+unfinished work is blocked, record the blocker, owner and next unblock step;
+use `OWNER_DECISION_REQUIRED` only when an actual owner decision is needed.
+Do not invent work to keep a goal active.
+
+## Team, queue and transport
+
+Use one primary MAIN session. A native subagent with a returned ID, bounded task,
+disjoint write scope and observable completion needs no new visible task or
+persistent session registry. Audit its artifact and termination before integration.
+Create a durable visible session only under the
+[canonical rule](../SKILL.md#choose-the-smallest-workflow).
+Use native subagents for delegated units; if unavailable, continue in MAIN.
+For a persistent delegated queue:
+
+1. `nobrainer-team` maps every independent ready unit to a bounded native assignment.
+2. If several delegated units form a queue, `nobrainer-dispatcher` computes the
+   ready set and bounded batch.
+3. MAIN spawns each bounded unit as a native subagent; only for owner-authorized
+   visible sessions does `nobrainer-sessions` create/reuse exact sessions, check
+   identity and writer state, and send each unit.
+4. Dispatcher may record `READY -> SENT` only from the send receipt: the returned
+   native worker ID or Sessions' transport readback.
+
+The queued transitions are `Team -> Dispatcher SCHEDULE -> native subagent spawn
+-> Dispatcher DISPATCH` (default) and, for visible sessions:
+
+`Team -> Dispatcher SCHEDULE -> Sessions setup/delegate -> Dispatcher DISPATCH`
+
+On that path Sessions alone performs identity preflight and transport. On either
+path Dispatcher never duplicates the send or treats a planned assignment as delivered.
+
+A worker receives one outcome, inputs, exact write scope, proof, stop conditions
+and report destination. It never chooses a successor.
+
+When a worker reports, MAIN audits a native worker against its returned ID, and
+Sessions performs `RECEIVE_AUDIT` for a visible session, against the exact worker,
+host, checkout, commit, diff, tests, evidence and released writer state.
+If Dispatcher owns the queue, its reconcile step consumes that audited result
+before releasing dependencies.
+
+## Failure and correction
+
+- Unknown dependency, identity, write ownership or lease state is `BLOCKED`.
+- A changed owner decision supersedes the old requirement, stops affected
+  not-started rows and invalidates dependent proof.
+- A verified review finding becomes `CORRECTION_REQUIRED` and returns to Build.
+- A repeated blocker keeps one stable fingerprint; retry only after a changed
+  condition or new evidence.
+- Timeout, dead session, partial output and retry exhaustion preserve the row as
+  incomplete.
+
+Close the ledger only when every required row is `ACCEPTED` or explicitly
+`STOPPED` by a superseding owner decision, all writers are released, final proof
+is current and rollback is still intelligible.
+
+## Adaptive fresh-session continuation
+
+For owner-enabled `session-restart`, reuse this goal and its progress rows.
+Sessions owns the [restart protocol](../../nobrainer-sessions/references/session-restart.md):
+quiet milestone assessment, compact checkpoint, verified fresh target, conditional
+ownership transfer and source archive after takeover. A stale summary or timer
+does not authorize a successor. Keep model policy, pending operations and native
+goal/scheduler ownership in the handoff; do not create another status owner.

package/skills/nobrainer-tech-flow/references/model-routing.md

@@ -0,0 +1,83 @@
+# Model policy and routing
+
+`nobrainer-tech-flow` owns the model policy. This contract is portable:
+clients may execute it, expose a model choice, or report `UNSUPPORTED`;
+no provider is assumed. A model name, manifest or default setting is not
+runtime proof.
+
+MAIN keeps the model and effort selected by the user in every client. Use the
+[Codex adapter](codex-routing.md) only for Codex-specific capability discovery,
+not as a universal model preset. Client detection and model availability
+require readback. Use [Auto Fine Tune](../../nobrainer-auto-fine-tune/SKILL.md)
+when repeated work warrants measured route calibration.
+
+## Freeze one policy before work
+
+Record the policy in the canonical plan and copy it into each delegated work
+unit. Use the smallest policy that meets the acceptance bar:
+
+```text
+MODEL_POLICY: STANDARD | EXTENDED | ROUTED
+MODEL: HOST_SELECTED | <exact supported id> | UNKNOWN
+EFFORT: DEFAULT | <exact supported setting> | UNKNOWN
+BUDGET: tokens=<n>; time=<duration>; cost=<limit> | UNKNOWN
+ESCALATION: NONE | PROPOSE | OWNER_APPROVAL
+ROUTE_REASON: <risk, complexity, latency or evidence reason>
+```
+
+- If no policy is supplied, keep the owner- or host-selected MAIN model.
+  Use `STANDARD` for a clear one-unit task or a client without native
+  workers. Use `ROUTED` by default for substantial work with useful
+  independent units and verified native worker support.
+- `STANDARD` uses the owner- or host-selected model and effort. It is the fallback
+  for small work, unavailable native workers or one-model hosts. Unknown capacity
+  permits bounded incremental dispatch under the delivery contract.
+- `EXTENDED` keeps that identity while allowing a larger declared
+  effort, context, time or cost budget and bounded extra verification. A
+  stronger model is an explicit policy change with an exact model and gate; it
+  is never a hidden retry.
+- `ROUTED` is the bounded default for useful parallel work: it selects a
+  capable worker for each independent unit from models the host actually
+  exposes. Prefer a smaller, quicker route when the task's acceptance can
+  still be met. Record the exact model, effort and budget
+  before dispatch. If the target is unavailable, use an already verified
+  capable worker route within the same authority or continue in MAIN; report
+  the degraded mode. An uncertain send must be reconciled before retry.
+
+## Routing heuristics
+
+These heuristics choose a worker route; they do not gate eligible dispatch under
+[team execution](delivery.md#coordinated-team-execution).
+
+- For each independent ready unit, choose a smaller or faster worker only when
+  the current host advertises it, the assignment accepts it, and the expected
+  setup plus audit cost is lower than the critical-path benefit. Use measured
+  cost and latency when available; otherwise mark them unknown.
+- Default to useful native parallelism when the task splits cleanly. A second
+  perspective may catch defects, and a smaller worker may avoid repeating
+  MAIN's full context. These are mechanisms to evaluate, not universal
+  measured improvements in quality, speed or token use.
+- Use the host-selected/default capable model for ordinary implementation;
+  routine units get the lowest effort that still meets acceptance.
+- Give every worker the same shared assignment prefix with the unit-specific
+  part last; prompt-cache reuse from this is plausible but unmeasured.
+- Request a stronger tier only when ambiguity, security, architecture, failed
+  proof or a declared quality bar justifies its added budget.
+- Delegate disjoint research, implementation and review units proactively
+  when useful. Use the maximum verified *useful* concurrency up to the host
+  limit, with one exact write owner per file. MAIN integrates results while
+  workers run. Pass the frozen policy to each worker; it cannot choose a
+  successor, recursively delegate or escalate itself without assignment authority.
+- A unit that reaches its `BUDGET` stops and reports partial results.
+  Escalate only when new evidence changes the cost or acceptance decision.
+  State the blocker, target tier, expected benefit, added budget and approval
+  gate before starting the next attempt.
+
+## Proof and limits
+
+Record `MODEL_REQUESTED`, `MODEL_ACTUAL`,
+`EFFORT`, budget and provider/client version when the host exposes
+them. `UNKNOWN` or `UNSUPPORTED` keeps the runtime claim
+`UNVERIFIED`. This is a portable policy, not a cross-provider model
+gateway; a client may implement `ROUTED`, but the skills cannot claim
+automatic switching until a clean runtime readback proves it.