@hecer/yoke 1.9.0 → 1.11.0

package/dist/routing/router.js

@@ -1,8 +1,9 @@
 import { buildWatchdogInvocation, makeRunner, runCapturedAgent, runnerInvocation, contextBlockFor, } from '../loop/runner.js';
-import { isAcceptanceCriterion } from '../loop/prd.js';
+import { isAcceptanceCriterion, criterionCommandProblem } from '../loop/prd.js';
 import { historyForWorkers, projectHash, readRoutingObservations, recordRoutingObservation, storyHash } from './registry.js';
-import { assessmentInstructions, assessmentKey, parseAssessment } from './assessment.js';
-import { chooseCapability, readAssessment, saveAssessment } from './capability.js';
+import { assessmentInstructions, parseAssessment, tiers } from './assessment.js';
+import { chooseCapability, readAssessment, saveAssessment, routingAssessmentKey, knownInfrastructureFailure } from './capability.js';
+import { readPlanningFile } from './contracts.js';
 const costRank = { low: 0, medium: 1, high: 2 };
 export function rankWorkers(workers, strategy, maxCandidates) {
     const history = historyForWorkers(workers);
@@ -144,43 +145,73 @@ function routingSteps(options) {
         selection,
     }));
     return function* (ctx) {
+        const blocked = (summary) => ({ success: false, summary, routing: { blocked: true, recordOutcome: () => undefined } });
+        if (options.strategy === 'capability' && options.assessmentPolicy === 'prepared') {
+            try {
+                const criteria = ctx.story.acceptance;
+                if (criteria.length < 2 || criteria.length > 5 || criteria.some(c => !isAcceptanceCriterion(c) || criterionCommandProblem(c)))
+                    return blocked('Prepared routing requires 2-5 executable acceptance criteria');
+                if (!readAssessment(options.projectRoot ?? ctx.targetDir, ctx.story, true))
+                    return blocked('Task assessment is missing or stale. Run yoke prd assess before execution.');
+            }
+            catch (error) {
+                return blocked(`Cannot read prepared assessment: ${error.message}`);
+            }
+        }
         if (options.strategy === 'capability' && !options.rules?.some(rule => (!rule.area || rule.area === ctx.story.area) && (!rule.storyId || rule.storyId === ctx.story.id))) {
             const root = options.projectRoot ?? ctx.targetDir;
-            let assessment = readAssessment(root, ctx.story);
+            let assessment;
+            try {
+                assessment = readAssessment(root, ctx.story, options.assessmentPolicy === 'prepared');
+            }
+            catch (error) {
+                return blocked(`Cannot read assessment: ${error.message}`);
+            }
             let planning;
             const calls = [];
             if (!assessment) {
+                const inputKey = routingAssessmentKey(root, ctx.story);
                 const prompt = [assessmentInstructions, 'Use the supplied task contract and project context to produce a bounded plan. Do not implement or change files.',
+                    'Approved planning brief:', readPlanningFile(root, '.yoke/plan.md', 80_000) ?? '',
                     contextBlockFor(ctx.targetDir, ctx.story), JSON.stringify(ctx.story), 'Return exactly one line: YOKE_ASSESS {"taskClass":"implementation","difficulty":"medium","uncertainty":"low","risk":"low","scope":"low","testability":"high","reason":"evidence","approach":"steps and tests"}'].join('\n');
-                const selection = { ...options.parentSelection, nativeMultiAgent: false };
+                const planner = options.planner?.agent ?? options.parent;
+                if (!available(planner))
+                    return blocked('Configured planning provider is unavailable');
+                const selection = { ...(options.planner?.selection ?? options.parentSelection), nativeMultiAgent: false };
                 const started = now();
-                planning = yield () => options.captureRoute ? options.captureRoute(options.parent, ctx, prompt, selection)
-                    : runCapturedAgent(options.parent, buildWatchdogInvocation(runnerInvocation(options.parent, prompt, ctx.targetDir, true, 'read-only', selection), options.idleTimeoutMs ?? 0));
-                calls.push(callUsage('orchestrator', options.parent, selection, planning.tokens, now() - started));
+                planning = yield () => options.captureRoute ? options.captureRoute(planner, ctx, prompt, selection)
+                    : runCapturedAgent(planner, buildWatchdogInvocation(runnerInvocation(planner, prompt, ctx.targetDir, true, 'read-only', selection), options.idleTimeoutMs ?? 0));
+                calls.push(callUsage('orchestrator', planner, selection, planning.tokens, now() - started));
+                if (routingAssessmentKey(root, ctx.story) !== inputKey)
+                    return { ...blocked('Planning inputs changed during assessment; retry planning with the current contract'), tokens: aggregateCalls(calls) };
                 assessment = planning.success ? parseAssessment(planning.output) : undefined;
                 if (assessment)
-                    saveAssessment(root, ctx.story, assessment, { provider: options.parent, model: planning.tokens?.model ?? selection.model });
+                    saveAssessment(root, ctx.story, assessment, { provider: planner, model: planning.tokens?.model ?? selection.model });
             }
             if (!assessment)
                 return { success: false, summary: 'Routing assessment unavailable or invalid; implementation was not started', tokens: aggregateCalls(calls), routing: { recordOutcome: () => undefined, blocked: true } };
-            const choice = chooseCapability({ root, story: ctx.story, assessment, workers: eligibleWorkers, parent: options.parent, parentSelection: options.parentSelection, maxAttempts: options.maxAttempts });
+            const choice = chooseCapability({ root, story: ctx.story, assessment, workers: eligibleWorkers, parent: options.parent, parentSelection: options.parentSelection, maxAttempts: options.maxAttempts, fallback: options.fallback, maxTier: options.maxTier });
             options.onDecision?.(ctx.story.id, { profile: choice.worker?.id ?? 'SELF', provider: choice.provider, model: choice.selection.model, reasoningEffort: choice.selection.reasoningEffort, reason: choice.reason, next: choice.next, assessment });
+            if (choice.blocked)
+                return { ...blocked(choice.reason), tokens: aggregateCalls(calls) };
             if (choice.exhausted)
                 return { success: false, summary: 'Routing attempt budget exhausted; replan this task before retrying', tokens: aggregateCalls(calls), routing: { recordOutcome: () => undefined, blocked: true } };
             const started = now();
-            const result = yield () => makeWorker(choice.provider, choice.selection)({ ...ctx, story: { ...ctx.story, assessment } });
+            const result = yield () => makeWorker(choice.provider, choice.selection)({ ...ctx, attempt: choice.failures + 1, story: { ...ctx.story, assessment } });
             calls.push(callUsage(choice.worker ? 'worker' : 'parent', choice.provider, choice.selection, result.tokens, now() - started, choice.worker?.id ?? 'SELF'));
             let recorded = false;
+            const infrastructureFailure = result.infrastructureFailure || (!result.success && knownInfrastructureFailure(result.summary));
             return { ...result, summary: `route=${choice.worker?.id ?? 'SELF'} (${choice.reason}); ${result.summary}`,
+                ...(infrastructureFailure ? { success: false, infrastructureFailure: true } : {}),
                 tokens: { ...aggregateCalls(calls), storyId: ctx.story.id, escalated: choice.failures > 1 },
-                routing: { canRetry: !result.infrastructureFailure && choice.failures + 1 < (options.maxAttempts ?? 5), recordOutcome: (verified, failureKind) => {
+                routing: { blocked: infrastructureFailure || undefined, canRetry: !infrastructureFailure && choice.failures + 1 < (options.maxAttempts ?? 5), recordOutcome: (verified, failureKind) => {
                         if (recorded)
                             return;
                         recorded = true;
-                        recordRoutingObservation({ projectHash: projectHash(root), storyHash: storyHash(projectHash(root), ctx.story.id), assessmentKey: assessmentKey(ctx.story), taskClass: assessment.taskClass, requiredTier: choice.requiredTier,
+                        recordRoutingObservation({ projectHash: projectHash(root), storyHash: storyHash(projectHash(root), ctx.story.id), assessmentKey: routingAssessmentKey(root, ctx.story), taskClass: assessment.taskClass, requiredTier: choice.requiredTier,
                             role: 'implementation', strategy: 'capability', selected: choice.worker?.id ?? 'SELF', provider: choice.provider, requestedModel: choice.selection.model, requestedReasoningEffort: choice.selection.reasoningEffort,
-                            actualModel: result.tokens?.model, orchestratorProvider: options.parent, orchestratorModel: options.parentSelection?.model, orchestratorDurationMs: calls.filter(c => c.role === 'orchestrator').reduce((s, c) => s + c.durationMs, 0), workerDurationMs: calls[calls.length - 1].durationMs,
-                            processSuccess: result.success, verificationSuccess: verified, failureKind: failureKind ?? (result.infrastructureFailure ? 'infrastructure' : 'implementation'), usageAvailable: result.tokens !== undefined && result.tokens.measurementComplete !== false,
+                            actualModel: result.tokens?.model, orchestratorProvider: options.planner?.agent ?? options.parent, orchestratorModel: (options.planner?.selection ?? options.parentSelection)?.model, orchestratorDurationMs: calls.filter(c => c.role === 'orchestrator').reduce((s, c) => s + c.durationMs, 0), workerDurationMs: calls[calls.length - 1].durationMs,
+                            processSuccess: result.success, verificationSuccess: infrastructureFailure ? false : verified, failureKind: infrastructureFailure ? 'infrastructure' : failureKind ?? 'implementation', usageAvailable: result.tokens !== undefined && result.tokens.measurementComplete !== false,
                             inputTokens: result.tokens?.inputTokens ?? 0, outputTokens: result.tokens?.outputTokens ?? 0, totalCostUsd: result.tokens?.totalCostUsd });
                     } } };
         }
@@ -196,6 +227,8 @@ function routingSteps(options) {
         const ruleWorker = rule && failedStories.has(ctx.story.id) ? rule.escalateTo ?? 'SELF' : rule?.worker;
         const candidates = rule ? eligibleWorkers : rankWorkers(eligibleWorkers, options.strategy, options.maxCandidates);
         if (candidates.length === 0) {
+            if (options.fallback === 'block' || options.maxTier)
+                return blocked('No eligible routing profiles; parent fallback is disabled');
             return yield () => makeWorker(options.parent, options.parentSelection ?? {})(ctx);
         }
         const prompt = buildRoutingPrompt(ctx, candidates, options.strategy);
@@ -210,9 +243,11 @@ function routingSteps(options) {
             : routeRun.success ? parseRouteDecision(routeRun.output, candidates.map(worker => worker.id)) : null;
         const selected = decision?.worker ?? 'SELF';
         const worker = selected === 'SELF' ? undefined : candidates.find(candidate => candidate.id === selected);
+        if ((!worker && (options.fallback === 'block' || options.maxTier)) || (options.maxTier && (!worker?.tier || tiers.indexOf(worker.tier) > tiers.indexOf(options.maxTier))))
+            return blocked('Selected routing profile exceeds configured limits; execution blocked');
         const provider = worker?.agent ?? options.parent;
         const selection = worker
-            ? { model: worker.model, reasoningEffort: worker.reasoningEffort, nativeMultiAgent: false, ...(provider !== 'gemini' ? { bare: options.parentSelection?.bare } : {}) }
+            ? { model: worker.model, reasoningEffort: worker.reasoningEffort, nativeMultiAgent: false, ...(provider !== 'gemini' && provider !== 'qwen' ? { bare: options.parentSelection?.bare } : {}) }
             : { ...(options.parentSelection ?? {}), nativeMultiAgent: false };
         const workerStarted = now();
         const result = yield () => makeWorker(provider, selection)(ctx);

package/dist/setup/command.js

@@ -4,7 +4,7 @@ import { detectHostAgent } from '../agents/host.js';
 import { loadConfig, saveConfig } from '../retrofit/config.js';
 import { detectProject } from '../retrofit/detect.js';
 import { runRetrofit } from '../retrofit/command.js';
-const ALL_AGENTS = ['claude', 'codex', 'gemini'];
+const ALL_AGENTS = ['claude', 'codex', 'gemini', 'qwen'];
 export function defaultRoutingWorkers(agents) {
     const workers = {
         claude: [
@@ -25,6 +25,12 @@ export function defaultRoutingWorkers(agents) {
             { id: 'gemini-strong', agent: 'gemini', model: 'gemini-2.5-pro', tier: 'strong', costTier: 'medium', capabilities: ['debugging'] },
             { id: 'gemini-frontier', agent: 'gemini', model: 'gemini-2.5-pro', tier: 'frontier', costTier: 'high', capabilities: ['architecture'] },
         ],
+        qwen: [
+            { id: 'qwen-light', agent: 'qwen', model: 'qwen-turbo-latest', tier: 'light', costTier: 'low', capabilities: ['mechanical', 'tests'] },
+            { id: 'qwen-standard', agent: 'qwen', model: 'qwen3-coder-plus', tier: 'standard', costTier: 'medium', capabilities: ['implementation'] },
+            { id: 'qwen-strong', agent: 'qwen', model: 'qwen3-coder-plus', tier: 'strong', costTier: 'medium', capabilities: ['debugging'] },
+            { id: 'qwen-frontier', agent: 'qwen', model: 'qwen3-235b-a22b', tier: 'frontier', costTier: 'high', capabilities: ['architecture'] },
+        ],
     };
     return agents.flatMap(agent => workers[agent]);
 }
@@ -75,12 +81,12 @@ export async function runSetup(targetDir, opts = {}) {
         let decisionPolicy = defaultPolicy;
         let routing = defaultRouting;
         if (interactive && ask) {
-            agents = parseAgents(await ask(`Agents [${defaultAgents.join(',')}] (claude,codex,gemini|all): `), defaultAgents);
+            agents = parseAgents(await ask(`Agents [${defaultAgents.join(',')}] (claude,codex,gemini,qwen|all): `), defaultAgents);
             const graphAnswer = (await ask(`Code graph [${defaultGraph}] (graphify|serena): `)).trim().toLowerCase();
             if (graphAnswer === 'graphify' || graphAnswer === 'serena')
                 codeGraph = graphAnswer;
             loop = yes(await ask(`Enable autonomous loop? [${defaultLoop ? 'yes' : 'no'}]: `), defaultLoop);
-            const runnerAnswer = (await ask(`Default runner [${runner}] (claude|codex|gemini): `)).trim().toLowerCase();
+            const runnerAnswer = (await ask(`Default runner [${runner}] (claude|codex|gemini|qwen): `)).trim().toLowerCase();
             if (ALL_AGENTS.includes(runnerAnswer))
                 runner = runnerAnswer;
             const policyAnswer = (await ask(`Decision mode [${decisionPolicy}] (auto|critical): `)).trim().toLowerCase();
@@ -104,6 +110,8 @@ export async function runSetup(targetDir, opts = {}) {
             enabled: routing,
             strategy: opts.routingStrategy ?? config.routing?.strategy ?? 'capability',
             maxCandidates: config.routing?.maxCandidates ?? 3,
+            assessmentPolicy: existing?.routing?.assessmentPolicy ?? (existing ? 'on-demand' : 'prepared'),
+            fallback: existing?.routing?.fallback ?? (existing ? 'parent' : 'block'),
             ...(config.routing?.orchestrator ? { orchestrator: config.routing.orchestrator } : {}),
             workers: existingWorkers.length > 0 && !opts.routingPreset ? existingWorkers : defaultRoutingWorkers(agents),
         };

package/docs/BATCH-PLANNING-VALIDATION.md

@@ -0,0 +1,67 @@
+# Batch planning validation — 2026-09-06
+
+AI-assisted implementation record for the local development build after 1.9.0.
+No new version has been published by this task.
+
+## Implemented
+
+- One bounded assessment call for a selected package, with exact output IDs,
+  executable-criteria checks, project locking and atomic PRD replacement.
+- Separate planning provider/model/effort, complete draft/inbox assessments,
+  stale-contract detection including upstream requirements and the approved brief.
+- Prepared routing and blocked fallback in new setups; existing settings remain
+  compatible. Automatic tier ceilings block insufficient configurations.
+- Capability routing recognizes reported Windows process-creation/authentication
+  failures and failed gate evidence as infrastructure, stopping repair without
+  adding model-quality failures.
+
+## Actual Yoke run
+
+The current compiled development CLI ran in a separate `Yoke-batch` checkout with
+capability routing, prepared assessment, blocked fallback, a strong tier ceiling
+and one serial worker. The assigned task was limited to batch-command tests.
+Yoke chose `codex-standard`, requested `gpt-5.6-terra` at medium effort, verified
+the criterion tests and committed the result. The main checkout received only
+the reviewed test file; one assertion was strengthened during review.
+
+Recorded start: 2026-09-06T17:45:54.729Z. Terminal state: complete at
+17:50:41.108Z, one backlog task accepted. One measured worker call and no
+orchestrator/assessment call were recorded. Input: 546,591 tokens, including
+496,384 cached input tokens; output: 6,294 tokens. Reported monetary cost and
+actual model identity are unknown. This is no cost benchmark or measured saving.
+
+This run explicitly used unsafe permissions. It does not validate the Windows
+safe-mode execution reported in issue #5.
+
+## Issue #5 boundary
+
+**Follow-up:** the user subsequently requested completion of the runner correction.
+The reproduction, safe-mode end-to-end result and supervision changes are recorded
+in [WINDOWS-RUNNER-VALIDATION.md](WINDOWS-RUNNER-VALIDATION.md). The following paragraph
+describes the earlier batch-planning checkpoint.
+
+The user-provided runner handoff and [issue #5](https://github.com/HECer/yoke/issues/5)
+were read. The infrastructure-classification correction is partial. The original
+safe-mode shell failure has not been reproduced or diagnosed here. In particular,
+a preflight under the actual sandbox identity, streamed tool-error handling when
+a provider exits zero, separate heartbeat/useful-progress reporting, total process
+budgets and argument-safe Windows launch regressions remain open. Optional MCP
+startup warnings alone are not treated as proof of a task failure. No affected
+DeviceLane worktree was restarted or cleaned, and the issue was not closed.
+
+## Evidence scope
+
+Automated tests cover batch call suppression, invalid/partial/duplicate output,
+concurrent PRD edits, contract invalidation, planner/worker separation, prepared
+dispatch, tier limits and infrastructure repair suppression. Injected planner
+responses establish command behavior; they are not authenticated provider parity
+benchmarks. The full suite executed 1,166 tests in 127 files: 1,163 passed, two
+were skipped and one new test fixture lacked a required configuration field.
+After correcting that fixture, all 11 tests in its file passed. Subsequent
+focused routing checks cover the final input-freshness guard. Planning hashes
+establish input freshness, not provenance or correctness.
+
+Read-only provenance scan: no C2PA located, supported scan complete, verification,
+signer trust and Markdown metadata privacy unknown. The audit's limits are:
+"No conforming verifier was supplied." and "Keyed model-level watermarks cannot
+be checked without the provider's key." No authorship inference or mark removal.

package/docs/CAPABILITY-ROUTING.md

@@ -1,54 +1,82 @@
-# Routing by task requirements
-
-Available in Yoke 1.9.0.
-
-New setups use `routing.strategy: capability`. Existing explicit strategies and profiles remain unchanged. To opt an existing project into capability routing with its current profiles:
-
-```sh
-yoke setup . --yes --routing --routing-strategy=capability
-```
-
-Give each existing worker a `tier: light|standard|strong|frontier`. Profiles without a tier remain usable with legacy strategies but are not candidates for capability selection. To explicitly replace worker profiles with the supplied provider presets, add `--routing-preset`. This replaces customized worker profiles; omit it to retain them.
-
-## Planning and selection
-
-The configured start provider/model plans new change requests. The planner supplies an `assessment` with the task class, difficulty, uncertainty, risk, scope, testability, rationale and implementation approach. Existing tasks without an assessment receive one read-only assessment call using the start model. This call does not use a cheaper orchestration override. Its result is cached under `.yoke/routing/`, keyed by the task contract. Changing the contract invalidates the cached assessment; toggling `passes` does not.
-
-An assessment is a planning judgment, not a measured success probability. High testability means executable checks can detect an incorrect implementation. High uncertainty, architecture work or high risk require the frontier tier; difficult or broadly coupled work requires strong; routine implementation requires standard. Light is reserved for clear, low-risk mechanical work with strong checks. Weak testability raises the minimum tier. Reviews and critics have a standard minimum even for light tasks.
+# Routing by task requirements
+
+Capability routing is available in Yoke 1.9.0. Batch preparation, separate planning settings and routing limits described below are local, unreleased additions.
+
+New setups use `routing.strategy: capability`. Existing explicit strategies and profiles remain unchanged. To opt an existing project into capability routing with its current profiles:
+
+```sh
+yoke setup . --yes --routing --routing-strategy=capability
+```
+
+Give each existing worker a `tier: light|standard|strong|frontier`. Profiles without a tier remain usable with legacy strategies but are not candidates for capability selection. To explicitly replace worker profiles with the supplied provider presets, add `--routing-preset`. This replaces customized worker profiles; omit it to retain them.
+
+## Planning and selection
+
+The start provider/model remains the planning default. Optional `planning.agent`, `planning.model` and `planning.reasoningEffort` select a separate planner without changing the execution model. Draft and change-inbox planning request complete assessments in the same pass that creates the tasks. The inbox still performs its separate coverage review.
+
+New setups use `routing.assessmentPolicy: prepared` and `routing.fallback: block`. Before dispatch, each unfinished task must have 2–5 executable criteria and a current assessment. No per-task planning call runs in this mode. Existing configurations retain `on-demand` and `parent` unless explicitly changed; on-demand routing makes a read-only planning call for an unassessed task and caches its result.
+
+Run `yoke prd assess .` to assess all missing or stale unfinished tasks together. One invocation makes at most one read-only planner call, with exact task IDs and validated output, then atomically replaces the PRD. Invalid, incomplete or duplicate output leaves the PRD unchanged; concurrent input edits are preserved and the result is rejected. A current package uses zero model calls. `--story=ID` selects one unfinished task; `--reassess` also includes already-current assessments. The default package limit is 20 tasks (`planning.maxTasks`, range 1–50) and the prompt limit is 60,000 characters; oversized input is rejected before calling the provider.
+
+Yoke writes `assessmentFor` bindings over requirements, declared write scope/provider, transitive dependency contracts and `.yoke/plan.md`. Changes invalidate affected unfinished tasks; progress or priority changes do not. A changed brief invalidates all unfinished tasks. These hashes detect stale input, not authorship or semantic correctness. Source-code changes outside these contracts require explicit reassessment when relevant.
+
+Example settings alongside the project's existing worker profiles:
 
 ```yaml
-assessment:
-  taskClass: implementation
-  difficulty: medium
-  uncertainty: low
-  risk: low
-  scope: low
-  testability: high
-  reason: Existing handler pattern and executable contract tests
-  approach: Extend the handler, cover the boundary cases, run contract tests
+runner:
+  agent: codex
+  model: gpt-5.6-terra
+planning:
+  agent: codex
+  model: gpt-6-astra
+  reasoningEffort: high
+  maxTasks: 20
+routing:
+  enabled: true
+  strategy: capability
+  assessmentPolicy: prepared
+  fallback: block
+  maxTier: strong
+  # Keep the existing workers list here.
 ```
 
-Yoke chooses an eligible profile at or above the required tier, then compares declared cost tiers. Optional `roles: [implementation, reviewer, critic, repair]` limits a profile's uses. Task `agent` affinity restricts implementation to that provider. Explicit routing rules and explicit quality role models retain precedence. A missing suitable profile falls back to the start model (or the explicitly bound provider's default) and labels the fallback; it does not prove that the fallback has sufficient capability. An invalid assessment blocks implementation.
-
-## Initial profiles
-
-| Tier | Codex | Claude | Gemini |
-| --- | --- | --- | --- |
-| light | gpt-5.6-luna, low | haiku | gemini-2.5-flash |
-| standard | gpt-5.6-terra, medium | sonnet | gemini-2.5-pro |
-| strong | gpt-5.6-sol, high | sonnet, high effort | gemini-2.5-pro |
-| frontier | gpt-6-astra, high | opus | gemini-2.5-pro |
-
-These are editable starting hypotheses, not measured equivalences or price claims. The Codex names follow the requested profile family. Account access is not established by finding an installed CLI. Gemini uses documented explicit model IDs and receives no unsupported reasoning-effort parameter. Several Gemini tiers deliberately share Pro; moving between those tiers alone is not a stronger-model transition. Adjust the presets to the models available to your account. Claude aliases can resolve to different concrete models over time. Provider-reported model identity remains separate from requested identity.
-
-Provider references: [Claude model configuration](https://code.claude.com/docs/en/model-config), [Gemini model selection](https://geminicli.com/docs/cli/model/).
-
-## Repair, escalation and evidence
-
-After an independent mechanical failure, capability routing permits one targeted repair at the initial tier, then raises the required tier on further failures. Attempts retain the current worktree and receive the previous gate findings. Every returned candidate still passes the normal acceptance, protection, quality, review and integration gates. Critical decisions, pause/cancellation and protected-acceptance violations stop retries. Provider process failures are classified conservatively as infrastructure; they do not count as evidence that a stronger model is needed.
-
-`routing.maxAttempts` limits implementation calls per unchanged task contract (default 5, configurable 1–8). The initial tier imposes an additional bound: light at most 5, standard 4, strong 3, frontier 2. An exhausted task blocks and requires a revised plan. These are inner implementation attempts; the outer loop's iteration count still counts task dispatches. Existing quality repair rounds and time limits remain separate bounds, and quality repairs can raise their profile tier by round. Goal execution keeps its existing global attempt, time and token budgets.
-
-Routing observations record task class, required tier, requested and reported models, effort, independent result, duration and available consumption. Selection considers matching project/task-class/tier history from the last 30 days within the bounded registry read. At least ten matching observations are required before an observed success rate below 80% excludes a profile. History is scoped to the concrete reported model to avoid mixing changed aliases. This is a conservative exclusion rule; it does not lower the planner's safety floor or claim calibrated probabilities. Missing usage remains unknown. Financial optimization and cross-provider performance require authenticated benchmarks.
-
-The dashboard's Now view shows the last recorded implementation profile, requested model/effort, rationale and next escalation tier. Usage & time retains reported model and role consumption, including assessment calls. Cached planning has no new model-call charge. Routing state is local runtime data and excluded from Yoke story commits.
+`maxTier` limits automatic execution and escalation, including routing-rule selections. If a task needs frontier while the ceiling is strong, it blocks; Yoke does not lower the required capability. Planning itself may still use Astra. Explicit quality-role model overrides retain precedence. Goal execution retains its own protected manifest and budgets, uses the configured planner on demand, and honors routing fallback/tier limits; PRD preparation policy does not apply to synthetic goal tasks.
+
+An assessment is a planning judgment, not a measured success probability. High testability means executable checks can detect an incorrect implementation. High uncertainty, architecture work or high risk require the frontier tier; difficult or broadly coupled work requires strong; routine implementation requires standard. Light is reserved for clear, low-risk mechanical work with strong checks. Weak testability raises the minimum tier. Reviews and critics have a standard minimum even for light tasks.
+
+```yaml
+assessment:
+  taskClass: implementation
+  difficulty: medium
+  uncertainty: low
+  risk: low
+  scope: low
+  testability: high
+  reason: Existing handler pattern and executable contract tests
+  approach: Extend the handler, cover the boundary cases, run contract tests
+```
+
+Yoke chooses an eligible profile at or above the required tier, then compares declared cost tiers. Optional `roles: [implementation, reviewer, critic, repair]` limits a profile's uses. Task `agent` affinity restricts implementation to that provider. Explicit routing rules and explicit quality role models retain precedence. With legacy `fallback: parent` and no tier ceiling, a missing suitable profile falls back to the start model (or the explicitly bound provider's default) and labels the fallback; it does not prove sufficient capability. `fallback: block` or a configured tier ceiling prevents that fallback. An invalid assessment blocks implementation.
+
+## Initial profiles
+
+| Tier | Codex | Claude | Gemini |
+| --- | --- | --- | --- |
+| light | gpt-5.6-luna, low | haiku | gemini-2.5-flash |
+| standard | gpt-5.6-terra, medium | sonnet | gemini-2.5-pro |
+| strong | gpt-5.6-sol, high | sonnet, high effort | gemini-2.5-pro |
+| frontier | gpt-6-astra, high | opus | gemini-2.5-pro |
+
+These are editable starting hypotheses, not measured equivalences or price claims. The Codex names follow the requested profile family. Account access is not established by finding an installed CLI. Gemini uses documented explicit model IDs and receives no unsupported reasoning-effort parameter. Several Gemini tiers deliberately share Pro; moving between those tiers alone is not a stronger-model transition. Adjust the presets to the models available to your account. Claude aliases can resolve to different concrete models over time. Provider-reported model identity remains separate from requested identity.
+
+Provider references: [Claude model configuration](https://code.claude.com/docs/en/model-config), [Gemini model selection](https://geminicli.com/docs/cli/model/).
+
+## Repair, escalation and evidence
+
+After an independent mechanical failure, capability routing permits one targeted repair at the initial tier, then raises the required tier on further failures. Attempts retain the current worktree and receive the previous gate findings. Every returned candidate still passes the normal acceptance, protection, quality, review and integration gates. Critical decisions, pause/cancellation and protected-acceptance violations stop retries. Provider process failures are classified conservatively as infrastructure; they do not count as evidence that a stronger model is needed.
+
+`routing.maxAttempts` limits implementation calls per unchanged task contract (default 5, configurable 1–8). The initial tier imposes an additional bound: light at most 5, standard 4, strong 3, frontier 2. An exhausted task blocks and requires a revised plan. These are inner implementation attempts; the outer loop's iteration count still counts task dispatches. Existing quality repair rounds and time limits remain separate bounds, and quality repairs can raise their profile tier by round. Goal execution keeps its existing global attempt, time and token budgets.
+
+Routing observations record task class, required tier, requested and reported models, effort, independent result, duration and available consumption. Selection considers matching project/task-class/tier history from the last 30 days within the bounded registry read. At least ten matching observations are required before an observed success rate below 80% excludes a profile. History is scoped to the concrete reported model to avoid mixing changed aliases. This is a conservative exclusion rule; it does not lower the planner's safety floor or claim calibrated probabilities. Missing usage remains unknown. Financial optimization and cross-provider performance require authenticated benchmarks.
+
+The dashboard's Now view shows the last recorded implementation profile, requested model/effort, rationale and next escalation tier. Usage & time retains reported model and role consumption, including assessment calls. Cached planning has no new model-call charge. Routing state is local runtime data and excluded from Yoke story commits.

package/docs/DASHBOARD-EVOLUTION.md

@@ -0,0 +1,33 @@
+# Dashboard evolution
+
+The local dashboard is an actionable workspace for registered Yoke projects. It reads the same saved project, loop, goal, acceptance, and measurement data as the CLI. Project-controlled text is rendered through `textContent`, and the server remains bound to the loopback interface with same-origin authorization for pause requests.
+
+## Overview
+
+Project status is derived from both the saved goal and the latest loop report. A blocked or running loop is not hidden by a completed goal. When goal and loop states differ, the card displays both. Blocked, failed, paused, unavailable, and stale active reports need attention; those projects are ordered before active projects, followed by the remaining projects.
+
+Cards also show the reported current task and saved blocker reason when available, so the overview explains why a project needs attention before opening it.
+
+An active loop report more than 20 minutes old is labeled **unconfirmed**. This means Yoke has an old active report, not evidence that the process is still live. The overview can be searched by project name, canonical path, or goal objective and filtered to All, Active, or Needs attention. A no-match state explains the result and provides a clear action that resets both search and filter.
+
+## Durable navigation
+
+The URL hash stores the current screen, project, project tab, period, UTC grouping, and complete custom date range. Supported screens are the overview, workspace comparison, and project detail. Supported project tabs are Now, Usage & time, and Results; periods are 1, 7, 30, 90, or 365 days; groupings are day, week, or month. Custom dates must be real ISO calendar dates in chronological order and cover at most 366 inclusive days.
+
+Invalid hash state returns to the overview with the 30-day/day defaults. Browser back and forward, a page reload, and Refresh restore the validated state. Refresh reloads data without resetting the selected view or controls. Starting any navigation aborts earlier fetches and changes a request generation, so an older response cannot replace the current screen.
+
+The workspace comparison schedules at most three project analytics requests at once. If navigation changes, in-flight fetches are aborted and no additional obsolete project requests are scheduled. All projects and individual project links remain available in the navigation while viewing the comparison.
+
+## Usage comparisons
+
+Usage & time compares the selected period with the immediately preceding period of exactly the same duration. A single time boundary is captured before either analytics request is made. The comparison covers recorded input plus output tokens, recorded acceptance events, and reported cost.
+
+When the preceding value is zero, the dashboard describes no change or new recorded activity instead of calculating an infinite percentage. A cost percentage is shown only when both periods have fully measured cost. Otherwise the dashboard says the percentage is unavailable. Current and previous missing-usage coverage is displayed from calls with unknown usage and unmeasured attempts. Recorded portions remain recorded portions; missing tokens or charges are not estimated as zero.
+
+Charts and their tables include periods that contain recorded events. Empty UTC calendar buckets are omitted and the chart explains that a gap means no recorded activity, not a measured zero. Detailed provider/model/role, model timeline, task, and phase tables remain below the comparison.
+
+## Design findings and limitations
+
+Goal state and loop state describe different durable facts and need independent presentation. Freshness is also separate from state: a saved `running` value can become unconfirmed without being rewritten. Navigation state belongs in the URL because the dashboard has several independently useful views and time controls. Analytics fan-out needs cancellation as well as a concurrency bound because registered workspaces may contain many projects.
+
+The dashboard combines local saved evidence with process-identity checks for supervised providers (see [Windows runner validation](WINDOWS-RUNNER-VALIDATION.md)). Unverified process identity remains unknown. It does not reconstruct activity that predates retained measurements, estimate missing provider usage or prices, or turn requested model names into proof of models used. Parallel call durations can overlap, so summed call time is consumption intensity rather than generation speed. The 20-minute freshness threshold is a presentation rule, not a process-health guarantee. No provider performance benchmark is implied by these views.

package/docs/MIGRATING-TO-1.0.md

@@ -1,33 +1,33 @@
-# Migrating to Yoke 1.0
-
-Yoke 1.0 changes unsafe implicit behavior into explicit policy.
-
-## Runner permissions
-
-The default is `runner.permissions: safe`. Automation that intentionally requires a full
-sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
-`read-only` for planning and probing.
-
-## Reviews
-
-Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
-differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
-
-## Commit ownership
-
-Yoke resolves identity before implementation. Configure it when Git has no identity:
-
-```yaml
-commit:
-  authorName: HECer
-  authorEmail: hec_er@web.de
-  allowCoAuthors: false
-```
-
-## PRDs, audit, and cleanup
-
-Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
-collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
-version suppressions with `suppressionsVersion: 1`.
-
-`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.
+# Migrating to Yoke 1.0
+
+Yoke 1.0 changes unsafe implicit behavior into explicit policy.
+
+## Runner permissions
+
+The default is `runner.permissions: safe`. Automation that intentionally requires a full
+sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
+`read-only` for planning and probing.
+
+## Reviews
+
+Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
+differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
+
+## Commit ownership
+
+Yoke resolves identity before implementation. Configure it when Git has no identity:
+
+```yaml
+commit:
+  authorName: HECer
+  authorEmail: hec_er@web.de
+  allowCoAuthors: false
+```
+
+## PRDs, audit, and cleanup
+
+Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
+collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
+version suppressions with `suppressionsVersion: 1`.
+
+`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.

package/docs/MIGRATING-TO-1.1.md

@@ -1,27 +1,27 @@
-# Migrating to Yoke 1.1
-
-Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
-
-Run the setup wizard once in an existing project:
-
-```bash
-npx @hecer/yoke@1.1.0 setup .
-```
-
-It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
-
-The new config fields are optional and backward-compatible:
-
-```yaml
-runner:
-  agent: codex
-  permissions: safe
-loop:
-  enabled: true
-  timeoutMinutes: 30
-  decisionPolicy: critical  # auto | critical
-```
-
-`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
-
-Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.
+# Migrating to Yoke 1.1
+
+Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
+
+Run the setup wizard once in an existing project:
+
+```bash
+npx @hecer/yoke@1.1.0 setup .
+```
+
+It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
+
+The new config fields are optional and backward-compatible:
+
+```yaml
+runner:
+  agent: codex
+  permissions: safe
+loop:
+  enabled: true
+  timeoutMinutes: 30
+  decisionPolicy: critical  # auto | critical
+```
+
+`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
+
+Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.