@lovehlmmm/primekit 1.0.0

package/skills/orchestrate/references/job-spec.md

@@ -0,0 +1,251 @@
+# Job Spec
+
+`/pk:orchestrate` accepts YAML or turns a free-form request into YAML under the
+run report directory. This file owns the durable data shape and execution
+semantics. It does not own a runtime roster, model catalog, or provider route.
+
+Resolve every runtime, model, agent, flag, and safety control from live evidence
+before dispatch:
+
+- [runtime-matrix.md](runtime-matrix.md): live candidate evidence;
+- [model-routing.md](model-routing.md): the sole selection policy;
+- [harness-profiles.md](harness-profiles.md): control evidence;
+- [internal-routing.md](internal-routing.md): in-session agent mechanics.
+
+## Schema
+
+```yaml
+version: 1
+concurrency: 2
+defaults:
+  timeout: 10m
+  effect: observe
+  approval: inherit
+  capture: true
+jobs:
+  - id: string
+    runtime: string
+    agent: string
+    fallback_runtime: [string]
+    task: scout | architecture | implement | review | audit | security | test | docs | mechanical
+    importance: normal | high
+    model: string
+    cwd: string
+    prompt: string
+    skill: string
+    allowed_tools: [string]
+    disallowed_tools: [string]
+    effect: observe | scoped-write | high-impact-write | external-destructive
+    approval: inherit | require
+    isolation: none | worktree
+    timeout: 10m
+    expected_output: string
+    depends_on: [job-id]
+    destructive: false
+    checks: [string]
+```
+
+Candidate identifiers are opaque strings until the current run verifies them.
+`agent` is meaningful only for in-session dispatch. `skill` is meaningful only
+for the PrimeKit skill-run branch. Do not copy a candidate list into this file.
+
+`effect` and `approval` are normalized coordinator intent, not runtime flags.
+The live harness profile maps them to verified native sandbox, permission, and
+approval controls. Block a route when no verified mapping meets its risk tier.
+
+## Required Fields
+
+Every job includes:
+
+- `id`, `runtime`, and `cwd`;
+- exactly one executable intent through `prompt` or `skill`;
+- `timeout` or `defaults.timeout`;
+- `expected_output`;
+- `model` or a routable `task`.
+
+When `model` is present it is an explicit constraint, not proof of availability.
+The live inventory gate still applies. An internal agent owns its configured
+model, so internal jobs do not set `model`.
+
+`isolation: worktree` is required for parallel writers in one repository and
+for any write whose verified harness controls do not otherwise satisfy the
+assigned risk tier. Worktree isolation prevents edit collisions; it does not
+claim to be an operating-system sandbox.
+
+`importance: high` raises capability and risk floors according to
+[model-routing.md](model-routing.md). This schema never names the resulting
+model or reasoning setting.
+
+## Validation
+
+Before stage construction:
+
+1. Reject duplicate or unsafe job IDs and unknown dependency IDs.
+2. Reject dependency cycles.
+3. Resolve `cwd` and ensure it stays within the authorized workspace.
+4. Require bounded timeout and capture for every job.
+5. Verify each primary and fallback runtime in the live matrix.
+6. Map effect, approval, and tool constraints to verified native controls.
+7. Verify explicit model and agent constraints.
+8. Reject parallel write overlap unless file ownership is disjoint and each
+   writer has the required isolation.
+9. Stop for explicit approval before destructive or external side effects.
+
+Unknown flags, models, or controls fail validation. Re-read live help or current
+official documentation; never guess a replacement.
+
+## Execution Semantics
+
+- Jobs with no dependencies form the first stage.
+- A job starts only after every dependency succeeds.
+- A stage may run up to `concurrency` jobs when ownership and isolation allow.
+- Failed or timed-out dependencies block their dependents.
+- A failed job is not retried unless the user explicitly requests it.
+- Fallback selection reruns the full capability and risk gate for that runtime.
+- Every state transition is atomically persisted before the next dispatch.
+
+## Run State And Resume
+
+`<run-dir>/state.json` is the tracker:
+
+```json
+{
+  "runId": "<run-id>",
+  "specPath": "jobs.yaml",
+  "jobs": {
+    "<job-id>": {
+      "status": "queued|running|success|failed|blocked|interrupted",
+      "runtime": "<verified-runtime>",
+      "model": "<resolved-model-or-null>",
+      "agent": "<resolved-agent-or-null>",
+      "attempts": 1,
+      "startedAt": "<timestamp-or-null>",
+      "endedAt": null,
+      "worktree": "<path-or-null>"
+    }
+  }
+}
+```
+
+On resume:
+
+- reuse successful outputs;
+- convert interrupted `running` work to `interrupted` and preserve its partial
+  capture under an attempt directory;
+- require fresh approval before redispatching destructive work;
+- recompute blocked jobs from current dependencies and live runtime evidence;
+- rerun the arbiter whenever any reviewed job reruns.
+
+## Delegating CLI Job Execution To `primekit orchestrate`
+
+`primekit orchestrate` (`apps/cli/internal/runtime/orchestrate`) is a separate local
+process-group supervisor, not part of this schema or this skill's own state
+machine. It owns process spawn, PID/PGID identity, and signal escalation for a
+run so that a job's process is never left ownerless if this coordinating
+session is interrupted. Use it for the process-lifecycle portion of a CLI job
+whenever the current platform supports it (`primekit orchestrate start` reports
+unsupported, exit code 6, on every non-Darwin `GOOS` in the current version);
+this schema, dispatch policy, capture redaction, and the arbiter contract stay
+entirely owned by this skill either way.
+
+Translation, once a stage's CLI jobs have a fully resolved runtime, model, and
+final command line:
+
+1. For each CLI job in the stage, build one `orchestrate.JobSpec`:
+   `id` = the job's `id`; `command`/`args` = the resolved, verified argv (never
+   a shell string, never the unresolved `prompt`/`skill` fields); `work_dir` =
+   the job's resolved `cwd` (the job's worktree when `isolation: worktree`);
+   `env` = only the explicit KEY=VALUE pairs this job's resolved invocation
+   requires, never a raw environment dump; `depends_on` = the job's own
+   `depends_on` list, unchanged.
+2. Write the resulting `{"jobs": [...]}` graph to
+   `<run-dir>/<orchestrate-run-id-once-known>/jobs.json` (or a stage-scoped
+   path of the coordinator's choosing) — this is the exact file `primekit orchestrate
+   start`/`resume` read, distinct from `jobs.yaml`.
+3. Dispatch with `primekit orchestrate start <path-to-jobs.json>`, record the printed
+   run ID in `<run-dir>/state.json` alongside the job's own tracked fields, and
+   poll with `primekit orchestrate status <run-id>` instead of watching a raw
+   subprocess handle.
+4. Cancel with `primekit orchestrate stop <run-id>` instead of signalling a PID this
+   skill read from its own state — a client must never derive a kill target
+   from persisted process fields itself.
+5. `runtime: internal` jobs never go through this translation: they have no
+   separate process to hand off, so they keep using
+   [internal-routing.md](internal-routing.md) unchanged.
+
+Only the resolved argv, working directory, and minimal required env cross this
+boundary. Routing metadata (capability tier, risk tier, resolved model/agent,
+`expected_output`, `checks`) stays in this skill's own `jobs.yaml`/`state.json`
+and is never passed to or read back from the runtime supervisor, which has no
+concept of any of it.
+
+## Capture Contract
+
+CLI jobs write bounded, redacted capture:
+
+```text
+<run-dir>/<job-id>/
+  command.txt
+  stdout.txt
+  stderr.txt
+  status.json
+  artifacts/
+```
+
+In-session jobs have no process surface. They write `result.md` plus
+`status.json` with the resolved agent and a null process exit code. Never put
+tokens, cookies, credentials, raw environment values, or private keys in any
+capture. Mark truncation and preserve the first and last useful sections.
+
+## Arbiter Contract
+
+The coordinator reports `Arbiter: pass` only when:
+
+- every required job succeeded;
+- expected outputs and listed checks exist and pass;
+- outputs do not contain unresolved contradictions;
+- claims are supported by available evidence;
+- unresolved questions are absent or explicitly accepted.
+
+The arbiter route must satisfy the judgment floor in
+[model-routing.md](model-routing.md). Independence is verified from the live
+inventory, not asserted from a copied provider name.
+
+## Illustrative Spec
+
+Placeholders below must be resolved and verified before dispatch.
+
+```yaml
+version: 1
+concurrency: 2
+jobs:
+  - id: scout-contract
+    runtime: "<verified-read-runtime>"
+    task: scout
+    cwd: "<workspace-root>"
+    prompt: "Map the contract owners and cite source evidence."
+    timeout: 8m
+    expected_output: "Source-backed contract map."
+
+  - id: inspect-tests
+    runtime: "<verified-read-runtime>"
+    fallback_runtime: ["<verified-fallback-runtime>"]
+    task: test
+    cwd: "<workspace-root>"
+    prompt: "Identify copied inventories and propose source-derived gates."
+    timeout: 8m
+    expected_output: "Test-coupling report with file evidence."
+
+  - id: arbiter
+    runtime: "<verified-judgment-runtime>"
+    task: review
+    cwd: "<workspace-root>"
+    prompt: "Reconcile both reports and reject unsupported claims."
+    depends_on: [scout-contract, inspect-tests]
+    timeout: 8m
+    expected_output: "Verified arbiter verdict."
+```
+
+The schema stays stable while live routing changes. Update the owning routing or
+runtime reference when selection policy or evidence changes; do not refresh
+examples with a new catalog.

package/skills/orchestrate/references/model-routing.md

@@ -0,0 +1,199 @@
+# Model Routing
+
+This file is the sole selection-policy authority for `/pk:orchestrate`. It
+decides which live runtime, model capability tier, and safety posture a job
+needs. Other orchestrate references describe evidence collection or dispatch
+mechanics and must link here instead of copying routes.
+
+Routing is resolved at execution time. Runtime availability, model catalogs,
+aliases, permission controls, and CLI flags are volatile. Never treat a model
+name, provider catalog, or previous run as current evidence.
+
+Scope: CLI runtimes and the `runtime: internal` branch. Internal agents keep
+the model declared by their live agent definition; the coordinator selects an
+agent rather than setting its model.
+
+## Inputs
+
+Classify every job before selecting a route:
+
+- `task`: scout, architecture, implement, review, audit, security, test, docs,
+  or mechanical;
+- `importance`: normal or high;
+- effect: read-only, scoped write, high-impact write, or destructive/external;
+- evidence needs: structured capture, citations, test output, or artifacts;
+- controls: sandbox, approval gate, tool restrictions, isolation, and timeout;
+- constraints: explicit runtime/model/agent pin, budget, OS, and dependencies.
+
+An explicit pin is a constraint, not proof that the route exists or is safe.
+
+## Live Inventory Gate
+
+Before routing any job, build the per-run inventory described in
+[runtime-matrix.md](runtime-matrix.md) and profile each candidate with
+[harness-profiles.md](harness-profiles.md). Record the result in
+`<run-dir>/runtimes.json`.
+
+For each candidate, verify in the actual run environment:
+
+1. executable or internal-agent availability;
+2. non-interactive authentication readiness without exposing credentials;
+3. current headless command and required flags from live help or current
+   official documentation;
+4. models or agents currently selectable by that runtime;
+5. sandbox, approval, tool-gating, cwd, timeout, capture, and resume behavior;
+6. host-OS limitations that weaken any claimed control.
+
+Unavailable, unverified, or insufficiently controlled candidates cannot
+satisfy a route merely because an older report used them.
+
+## Capability Tiers
+
+Select the minimum capability tier that can reliably produce and verify the
+expected output.
+
+| Tier | Required behavior | Typical work |
+| --- | --- | --- |
+| **C1 throughput** | Accurate search, extraction, summarization, and bounded repetitive changes | scout, docs, mechanical fan-out |
+| **C2 delivery** | Multi-file implementation judgment, test design, and failure-path handling | normal implementation and tests |
+| **C3 judgment** | Deep trade-off analysis, conflict resolution, security reasoning, and independent arbitration | architecture, review, audit, security, arbiter |
+
+Capability is established from the live runtime catalog, operator policy, and
+recent observed evidence when available. Marketing labels alone do not prove a
+tier. If a candidate cannot be classified confidently, do not assign it a
+load-bearing job.
+
+## Risk Tiers
+
+Risk determines the minimum harness controls independently of model
+capability.
+
+| Tier | Effect | Minimum controls |
+| --- | --- | --- |
+| **R0 observe** | Read/report only | Explicit cwd, bounded timeout, captured result, no unnecessary write or shell grant |
+| **R1 scoped write** | Reversible edits in owned files | Scoped write boundary, tool restrictions, diff capture, no permission bypass |
+| **R2 isolated write** | Parallel, high-impact, untrusted, or hard-to-revert changes | Separate worktree or stronger isolation, enforced sandbox where available, explicit checks and arbiter review |
+| **R3 external/destructive** | Deploy, release, delete, credentialed, or other external side effect | Explicit user approval, preview/rollback plan, strongest verified controls; block when those controls are unavailable |
+
+Secrets never belong in prompts, logs, inventory, or reports at any tier.
+
+## Routing Rules
+
+1. **Honor verified pins.** A pinned runtime, model, or agent must pass the live
+   inventory and risk-control gate. If it does not, block or ask before
+   changing the user's explicit constraint.
+2. **Fan out cheaply, decide strongly.** Use C1 for independent volume work,
+   then C3 for the job that synthesizes, judges, or arbitrates the outputs.
+3. **Require independent judgment.** Review, audit, security, and arbiter jobs
+   require C3. Prefer a different model family or independently configured
+   agent from the primary producer when live inventory proves that diversity;
+   otherwise disclose the same-family fallback.
+4. **Match controls before cost.** Filter candidates by the job's risk tier
+   before comparing latency, price, or convenience. An auto-approved or weakly
+   isolated harness does not qualify for shared-tree writes.
+5. **Use live aliases carefully.** Prefer a current stable alias or automatic
+   selection mode when the runtime documents it. Pin an exact identifier only
+   for a real reproducibility need, verify it immediately before dispatch, and
+   record the resolved identifier in capture.
+6. **Keep experimental routes non-load-bearing.** A candidate with unverified
+   flags, authentication, controls, or output capture may contribute advisory
+   evidence only and must be paired with a verified route.
+7. **Escalate expensive failure.** `importance: high` implementation requires
+   C3 and at least R2 controls. Use the strongest verified reasoning setting
+   when the live runtime exposes one; never guess a setting or value.
+
+## Task Defaults
+
+These are capability and risk floors, not runtime or provider routes.
+
+| Task class | Capability floor | Default risk floor |
+| --- | --- | --- |
+| `scout` | C1 | R0 |
+| `architecture` | C3 | R0 |
+| `implement` | C2; C3 when `importance: high` | R1; R2 when parallel or high-impact |
+| `review`, `audit`, `security` | C3 | R0 for review-only; match the effect if fixes are included |
+| `test` | C2 | R0 for design, R1 for writing or execution artifacts |
+| `docs` | C1 | R1 when files change |
+| `mechanical` | C1 | R1; R2 for broad or parallel edits |
+| arbiter | C3 | R0 |
+
+Raise either floor when the prompt, files, trust boundary, or expected output
+demands it. Never lower a floor solely to meet a budget.
+
+## Selection Procedure
+
+For each job:
+
+1. Determine its capability and risk floors.
+2. Apply explicit user constraints.
+3. Remove candidates that failed live availability, authentication, command,
+   or control verification.
+4. Remove candidates below either floor.
+5. Rank the remainder by task fit, control strength, evidence quality,
+   reliability, then cost and latency.
+6. Prefer independent model-family evidence for C3 review when available.
+7. Record the selected runtime, resolved model or agent, capability tier, risk
+   tier, controls, evidence source, and fallback reason.
+
+If no candidate qualifies, mark the job `blocked`. Do not silently weaken the
+risk posture or substitute a lower capability tier.
+
+## Internal Branch
+
+For `runtime: internal`:
+
+- validate an explicit `agent:` against the live agent list;
+- otherwise match the job's task and expected output to live agent
+  descriptions and declared tools, choosing the most specific qualified
+  agent;
+- use a general-purpose agent only when it is present and meets the risk tier;
+- do not set `model:`; the resolved agent definition owns it;
+- when model-family diversity or stronger isolation is required but cannot be
+  proven internally, choose a verified CLI candidate or disclose a blocked
+  fallback.
+
+Dispatch and capture mechanics live in
+[internal-routing.md](internal-routing.md).
+
+## Fallbacks
+
+Evaluate `fallback_runtime` entries through the same live gate and in declared
+order. Recompute the resolved model, capability tier, controls, and command for
+the new runtime. Never carry an identifier or flags from the failed runtime to
+its fallback.
+
+A fallback is acceptable only when it meets the same capability and risk
+floors. Record every substitution in `status.json` and the coordinator report.
+
+## Reasoning Controls
+
+For C3 jobs, inspect the selected runtime's live help or current official docs
+for a supported reasoning-depth control. Use the strongest setting justified
+by the task and operator budget. If no verified control exists, select based on
+the verified model capability tier and omit the setting. Never copy an old
+configuration key or assume values are portable between runtimes.
+
+## Worked Example
+
+"Audit a settings surface, implement the accepted fix, then review it":
+
+| Job | Task | Required route |
+| --- | --- | --- |
+| map-settings | `scout` | C1/R0, live verified read-only candidate |
+| design-fix | `architecture` | C3/R0, depends on map-settings |
+| implement-fix | `implement` | C2/R1, or C3/R2 when marked high importance |
+| review-fix | `review` | C3/R0, independent model family when live and qualified |
+
+Exact runtime, model, agent, and flags are resolved and recorded during that
+run; this document does not preselect them.
+
+## Operator Checklist
+
+- `runtimes.json` reflects this host and this run.
+- Every selected runtime and model or agent was found live.
+- Capability and risk floors are recorded.
+- No candidate relies on a copied provider catalog or stale command example.
+- Permission bypasses are off unless the user explicitly approved the exact
+  R3 action and external isolation makes the residual risk acceptable.
+- Fallbacks meet the same floors as their primary route.
+- The arbiter is C3 and its independence or same-family limitation is stated.

package/skills/orchestrate/references/runtime-matrix.md

@@ -0,0 +1,199 @@
+# Runtime Matrix
+
+`/pk:orchestrate` builds a runtime matrix for each run. This reference defines
+that live evidence contract; it is intentionally not a durable provider roster
+or command catalog. Runtime installation, authentication, flags, models, and
+safety behavior must be revalidated in the actual execution environment.
+
+[model-routing.md](model-routing.md) is the sole authority for selecting among
+verified candidates. [harness-profiles.md](harness-profiles.md) defines the
+evidence fields used by that decision.
+
+## Candidate Set
+
+Start with only candidates relevant to the requested run:
+
+- explicit `runtime:` values in the job spec;
+- entries in each job's `fallback_runtime` chain;
+- `runtime: internal` when the current harness exposes an agent-dispatch
+  interface;
+- a runtime the user explicitly asks the coordinator to consider.
+
+Treat each value as a candidate identifier, not proof of support. Do not add a
+runtime because it appeared in an old report or this repository's history. Do
+not install, update, authenticate, or alter configuration during discovery.
+
+The current [job-spec.md](job-spec.md) and active dispatch implementation own
+accepted identifiers. If they disagree, stop and report the contract mismatch
+instead of inventing a mapping.
+
+## Live Matrix Record
+
+Write the inventory to `<run-dir>/runtimes.json`. Each candidate record should
+contain at least:
+
+```json
+{
+  "id": "<candidate-id>",
+  "kind": "cli|internal|skill-run",
+  "state": "available|constrained|unverified|unavailable",
+  "binary": "<resolved-path-or-null>",
+  "version": "<live-value-or-null>",
+  "authenticated": true,
+  "hostOS": "<live-os>",
+  "models": ["<live-resolved-choice>"],
+  "agents": [],
+  "headless": true,
+  "cwdControl": "enforced|argument-only|prompt-only|none|unverified",
+  "approval": "per-operation|scoped|auto|none|unverified",
+  "toolGating": "granular|coarse|none|unverified",
+  "isolation": "os-sandbox|container|worktree|prompt-only|none|unverified",
+  "nativeBudget": "<verified-control-or-null>",
+  "externalTimeout": true,
+  "capture": ["final-result", "exit-status"],
+  "resume": "supported|unsupported|unverified",
+  "evidence": ["<probe-or-current-official-doc>"],
+  "notes": []
+}
+```
+
+Never include tokens, cookies, credential values, raw environment variables,
+or sensitive command arguments. Empty arrays and `null` are preferable to
+guessed capability.
+
+## CLI Probe Sequence
+
+For each CLI candidate:
+
+1. Resolve the executable using the active dispatcher or explicit user
+   configuration. Record the absolute executable path without following a
+   surprising shadow binary silently.
+2. Run the runtime's non-mutating version command and live help.
+3. From live help, verify the exact features needed by the job: headless
+   invocation, cwd handling, output capture, model selection, permissions,
+   native budgets, and resume.
+4. If live help advertises a model or capability listing command, run it and
+   record only the choices relevant to this run.
+5. Use a non-mutating authentication/status probe when available. A runtime
+   that would open an interactive login is `unavailable` for headless
+   dispatch until the operator completes setup outside the run.
+6. When help is ambiguous, consult current official documentation and record
+   the exact source checked. Do not rely on copied command snippets.
+7. Build a dry command template with redacted placeholders and validate its
+   arguments before dispatch. Do not execute a write merely to test syntax.
+
+An unknown flag or model is a failed probe. Re-check live help and current
+official docs, then rebuild the command. Never guess a replacement or carry
+flags between runtimes.
+
+## Internal Probe Sequence
+
+For `runtime: internal`, do not probe a binary:
+
+1. list the agent types the current harness exposes;
+2. read live agent descriptions, tools, permission boundaries, and model
+   metadata when exposed;
+3. record only agents available in this session;
+4. mark unenforced prompt constraints and accounting-only timeouts plainly;
+5. apply dispatch and capture behavior from
+   [internal-routing.md](internal-routing.md).
+
+An on-disk agent definition is supporting evidence, not proof that the current
+session can dispatch it. Prefer the live harness list.
+
+## Command Construction
+
+Construct each CLI command from the verified live surface. A dispatch command
+must establish or record:
+
+- non-interactive/headless invocation;
+- exact working directory;
+- prompt transport that preserves content without shell interpolation;
+- resolved model only when the route requires or supports model selection;
+- least-privilege approval, tool, and write controls;
+- structured or bounded output capture;
+- coordinator-owned external timeout;
+- redacted command capture in `<job-id>/command.txt`.
+
+Use prompt files or stdin for multiline, quote-heavy, or untrusted text when
+the live runtime supports them. Otherwise use the host shell's safe argument
+passing; never concatenate untrusted prompt text into a shell command.
+
+Do not add a permission bypass merely because the process is unattended. If
+headless mode is inherently auto-approved, record the constraint and limit it
+to work allowed by the risk policy.
+
+## OS Revalidation
+
+Record the host OS and shell before command construction. Verify rather than
+assume:
+
+- executable naming and installation path;
+- quoting, stdin, and prompt-file behavior;
+- path separators, path length, and worktree support;
+- whether sandbox claims apply on this OS;
+- how external process timeouts and cancellation work;
+- whether extra writable roots weaken isolation.
+
+When OS enforcement is weaker than the requested risk tier, use a stronger
+external boundary or block the route. A worktree prevents edit collisions but
+is not an OS sandbox.
+
+## Support States
+
+The live matrix uses evidence states rather than a permanent support tier:
+
+| State | Required evidence | Allowed use |
+| --- | --- | --- |
+| `available` | Command, auth, required controls, and capture verified live | Eligible for routing |
+| `constrained` | Dispatch verified, but controls or capture have known limits | Eligible only when policy accepts those limits |
+| `unverified` | Candidate exists, but required behavior was not proven | Advisory/non-load-bearing work only |
+| `unavailable` | Missing, unauthenticated, incompatible, or failed probe | Do not dispatch |
+
+Runtime selection, capability floors, risk floors, and fallback acceptance are
+defined only in [model-routing.md](model-routing.md).
+
+## Timeout Contract
+
+- Bound every CLI job with a coordinator-owned process timeout.
+- Treat native wall-time, turn, or tool-call limits as defense in depth.
+- On timeout, stop the process using the host's verified mechanism, preserve
+  bounded partial output, mark the job failed, and block dependents.
+- Internal timeouts are accounting-only unless the current harness proves a
+  cancellation mechanism; scope those prompts tightly.
+
+## Safety Gate
+
+Before dispatch, confirm:
+
+- runtime and model or agent were observed live;
+- cwd and writable roots match the job;
+- approval and tool controls meet the assigned risk tier;
+- parallel writers are isolated in separate worktrees and own disjoint files;
+- destructive or external actions have explicit user approval and rollback;
+- prompt and capture paths cannot expose secrets;
+- command flags were verified for this installed runtime and OS;
+- a fallback will be re-profiled rather than inheriting the failed command.
+
+If any required field is unknown, downgrade the candidate to `unverified` or
+block it. Do not infer safety from a runtime brand or prior successful run.
+
+## Drift and Failure Handling
+
+- Version, help, authentication, or model-list changes invalidate the affected
+  cached profile for this run.
+- A command-line parse failure returns to the probe step once; it is not a
+  reason to try guessed flags repeatedly.
+- A runtime crash, timeout, or permission prompt is a job failure. Preserve
+  evidence and apply the declared fallback through
+  [model-routing.md](model-routing.md).
+- Update evergreen docs only when the evidence procedure or safety invariant
+  changes. Do not paste the newly observed provider catalog back into these
+  references.
+
+## Verification Rule
+
+Before every dispatch, verify the selected runtime's current command and
+controls from the live binary, supplementing with current official
+documentation when necessary. Record the evidence in `runtimes.json` and the
+resolved command in capture. Stale examples are never an execution contract.