okstra 0.174.0 → 0.176.0

package/dist/lib/python-helper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-helper.mjs","sourceRoot":"","sources":["../../src/lib/python-helper.mts"],"names":[],"mappings":"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"}

package/dist/lib/runtime-manifest.d.mts

@@ -0,0 +1,7 @@
+export declare const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
+export declare const RUNTIME_MANIFEST_SCHEMA_VERSION = 2;
+import type { InstalledAssets, RuntimeManifest, RuntimeResolutionManifest } from "./types.mjs";
+export declare function runtimeListForSelection(runtime: string, resolution?: RuntimeResolutionManifest | null): string[];
+export declare function buildRuntimeManifest(runtime: string, installedAt?: string, resolution?: RuntimeResolutionManifest | null, installedAssets?: Partial<InstalledAssets> | null): RuntimeManifest;
+export declare function installedRuntimesFromManifest(data: Readonly<Record<string, unknown>>): string[];
+export declare function runtimeManifestIncludesClaudeAssets(data: Readonly<Record<string, unknown>>): boolean;

package/dist/lib/runtime-manifest.mjs

@@ -0,0 +1,73 @@
+export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
+export const RUNTIME_MANIFEST_SCHEMA_VERSION = 2;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function runtimeListForSelection(runtime, resolution = null) {
+    if (runtime === "all")
+        return [...(resolution?.catalogHostIds ?? [])];
+    if (runtime === "auto") {
+        const resolved = resolution?.resolvedRuntime;
+        return resolved && resolved !== "all" ? [resolved] : [];
+    }
+    return [runtime];
+}
+function includesClaudeAssets(resolution) {
+    return resolution?.installTargets?.includes("claude") === true;
+}
+function defaultResolution(runtime) {
+    if (runtime === "auto")
+        return null;
+    return {
+        requestedRuntime: runtime,
+        resolvedRuntime: runtime,
+        launchMode: null,
+        installTargets: [],
+        host: "explicit",
+        confidence: "high",
+        reason: `Explicit runtime '${runtime}' requested.`,
+        fallbackFrom: null,
+        warnings: [],
+    };
+}
+export function buildRuntimeManifest(runtime, installedAt = new Date().toISOString(), resolution = null, installedAssets = null) {
+    const runtimeResolution = resolution ?? defaultResolution(runtime);
+    const includesClaude = includesClaudeAssets(runtimeResolution);
+    const defaultAssets = {
+        sharedRuntime: true,
+        claudeSkills: includesClaude,
+        claudeAgents: includesClaude,
+        binWrappers: true,
+        templates: true,
+        schemas: true,
+        validators: true,
+    };
+    return {
+        schemaVersion: RUNTIME_MANIFEST_SCHEMA_VERSION,
+        installedAt,
+        installRequest: runtime,
+        runtimeResolution,
+        installedRuntimes: runtimeListForSelection(runtime, runtimeResolution),
+        installedAssets: { ...defaultAssets, ...(installedAssets ?? {}) },
+    };
+}
+export function installedRuntimesFromManifest(data) {
+    if (Array.isArray(data?.installedRuntimes))
+        return data.installedRuntimes;
+    if (Array.isArray(data?.runtimes))
+        return data.runtimes;
+    if (typeof data?.runtime === "string" && data.runtime)
+        return runtimeListForSelection(data.runtime);
+    return [];
+}
+export function runtimeManifestIncludesClaudeAssets(data) {
+    const installedAssets = isRecord(data.installedAssets)
+        ? data.installedAssets
+        : {};
+    if (data.schemaVersion === RUNTIME_MANIFEST_SCHEMA_VERSION) {
+        return installedAssets.claudeSkills === true || installedAssets.claudeAgents === true;
+    }
+    const legacyAssets = isRecord(data.assets) ? data.assets : {};
+    return legacyAssets.claudeSkills === true || legacyAssets.claudeAgents === true;
+}
+//# sourceMappingURL=runtime-manifest.mjs.map

package/dist/lib/runtime-manifest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-manifest.mjs","sourceRoot":"","sources":["../../src/lib/runtime-manifest.mts"],"names":[],"mappings":"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"}

package/dist/lib/skill-catalog.d.mts

@@ -0,0 +1,4 @@
+export declare const USER_SKILL_NAMES: readonly string[];
+export declare const OBSOLETE_SKILL_NAMES: readonly string[];
+export declare function userSkillNames(): string[];
+export declare function obsoleteSkillNames(): string[];

package/dist/lib/skill-catalog.mjs

@@ -0,0 +1,50 @@
+// Single source of truth for which okstra skills are user-facing and which
+// former or renamed skill directories must be pruned from agent skill homes on
+// (re)install. The Claude plugin manifest (.claude-plugin/plugin.json) and the
+// installer both derive their skill list from here, so the public surface
+// cannot drift between discovery and install.
+export const USER_SKILL_NAMES = Object.freeze([
+    "okstra-setup",
+    "okstra-brief-gen",
+    "okstra-run",
+    "okstra-manager",
+    "okstra-memory",
+    "okstra-inspect",
+    "okstra-rollup",
+    "okstra-usage",
+    "okstra-schedule-gen",
+    "okstra-container-build",
+    "okstra-pr-gen",
+    "okstra-user-response",
+    "okstra-code-review",
+]);
+// Names okstra used to install as skills before they were renamed or moved
+// into the runtime resource tree. Install prunes these exact directories from
+// each target skill home so upgrades do not leave stale slash commands behind.
+// Exact-name only — never wildcard.
+export const OBSOLETE_SKILL_NAMES = Object.freeze([
+    "okstra",
+    "okstra-context-loader",
+    "okstra-team-contract",
+    "okstra-convergence",
+    "okstra-report-writer",
+    "okstra-coding-preflight",
+    "okstra-container",
+    "okstra-brief",
+    "okstra-schedule",
+    // Pre-merge status/history/logs/report/time skills, since folded into
+    // okstra-inspect. Absent here, upgrades left them stranded in agent skill
+    // homes and their pre-.okstra-migration bodies kept triggering.
+    "okstra-status",
+    "okstra-history",
+    "okstra-logs",
+    "okstra-report-finder",
+    "okstra-time-summary",
+]);
+export function userSkillNames() {
+    return [...USER_SKILL_NAMES];
+}
+export function obsoleteSkillNames() {
+    return [...OBSOLETE_SKILL_NAMES];
+}
+//# sourceMappingURL=skill-catalog.mjs.map

package/dist/lib/skill-catalog.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-catalog.mjs","sourceRoot":"","sources":["../../src/lib/skill-catalog.mts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,+EAA+E;AAC/E,0EAA0E;AAC1E,8CAA8C;AAE9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,cAAc;IACd,kBAAkB;IAClB,YAAY;IACZ,gBAAgB;IAChB,eAAe;IACf,gBAAgB;IAChB,eAAe;IACf,cAAc;IACd,qBAAqB;IACrB,wBAAwB;IACxB,eAAe;IACf,sBAAsB;IACtB,oBAAoB;CACrB,CAAC,CAAC;AAEH,2EAA2E;AAC3E,8EAA8E;AAC9E,+EAA+E;AAC/E,oCAAoC;AACpC,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,QAAQ;IACR,uBAAuB;IACvB,sBAAsB;IACtB,oBAAoB;IACpB,sBAAsB;IACtB,yBAAyB;IACzB,kBAAkB;IAClB,cAAc;IACd,iBAAiB;IACjB,sEAAsE;IACtE,0EAA0E;IAC1E,gEAAgE;IAChE,eAAe;IACf,gBAAgB;IAChB,aAAa;IACb,sBAAsB;IACtB,qBAAqB;CACtB,CAAC,CAAC;AAEH,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,GAAG,gBAAgB,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,GAAG,oBAAoB,CAAC,CAAC;AACnC,CAAC"}

package/dist/lib/types.d.mts

@@ -0,0 +1,129 @@
+export type CliArgs = readonly string[];
+export type CommandRunner = (args: CliArgs) => Promise<number>;
+export type CommandCategory = "admin" | "introspection";
+export interface HostCapabilities {
+    readonly claudeSkillHandoff?: boolean;
+    readonly tmuxAvailable?: boolean;
+}
+export interface RuntimeEnvironment {
+    readonly OKSTRA_RUNTIME_HOST?: string;
+}
+export interface HostRuntimeResolution {
+    readonly ok: boolean;
+    readonly requestedRuntime: string;
+    readonly resolvedRuntime: string | null;
+    readonly launchMode: string | null;
+    readonly installTargets: readonly string[];
+    readonly catalogHostIds?: readonly string[];
+    readonly host: string;
+    readonly confidence: string;
+    readonly reason: string;
+    readonly fallbackFrom: string | null;
+    readonly warnings: readonly string[];
+}
+export interface HostDescriptor {
+    readonly id: string;
+    readonly install_targets?: readonly string[];
+    readonly installTargets?: readonly string[];
+}
+export interface HostRegistryCatalog {
+    readonly hosts?: readonly HostDescriptor[];
+}
+export interface HostProbeOptions {
+    readonly hostRuntime: string;
+    readonly entryMode: string;
+    readonly projectRoot: string;
+    readonly homeDir: string;
+    readonly availableFunctions?: readonly string[];
+}
+export type HostReadinessStatus = "ready" | "blocked" | "unknown";
+export interface HostReadiness {
+    readonly runtime: string;
+    readonly status: HostReadinessStatus;
+    readonly checks: readonly unknown[];
+    readonly [key: string]: unknown;
+}
+export interface HostResolveOptions {
+    readonly requestedRuntime: string;
+    readonly command: string;
+    readonly env?: RuntimeEnvironment;
+    readonly capabilities?: HostCapabilities;
+}
+export interface CommandDefinition {
+    readonly name: string;
+    readonly module: string;
+    readonly export: string;
+    readonly category: CommandCategory;
+    readonly summary: readonly string[];
+}
+export interface RuntimePaths {
+    readonly agents: string;
+    readonly workspace: string;
+    readonly pythonpath: string;
+    readonly bin: string;
+    readonly home: string;
+    readonly package: string;
+    readonly version: string;
+    readonly "dev-link": string;
+}
+export interface ProcessResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type PythonRunner = (options: PythonModuleOptions) => Promise<ProcessResult>;
+export interface PythonModuleOptions {
+    readonly module: string;
+    readonly args?: CliArgs;
+    readonly extraEnv?: Readonly<Record<string, string | undefined>>;
+    readonly stdio?: "capture" | "inherit-stdout";
+}
+export interface PythonSnippetOptions {
+    readonly script: string;
+    readonly args?: CliArgs;
+    readonly extraEnv?: Readonly<Record<string, string | undefined>>;
+}
+export interface InstalledScriptOptions {
+    readonly scriptName: string;
+    readonly args: CliArgs;
+    readonly usage: string;
+    readonly emptyArgsCode?: number;
+}
+export interface InstalledValidatorOptions {
+    readonly validatorName: string;
+    readonly args: CliArgs;
+}
+export interface JsonErrorOptions {
+    readonly stage: string;
+    readonly reason: string;
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+export interface RuntimeResolutionManifest {
+    readonly requestedRuntime: string;
+    readonly resolvedRuntime: string;
+    readonly launchMode: string | null;
+    readonly installTargets: readonly string[];
+    readonly host: string;
+    readonly confidence: string;
+    readonly reason: string;
+    readonly fallbackFrom: string | null;
+    readonly warnings: readonly string[];
+    readonly catalogHostIds?: readonly string[];
+}
+export interface InstalledAssets {
+    readonly sharedRuntime: boolean;
+    readonly claudeSkills: boolean;
+    readonly claudeAgents: boolean;
+    readonly binWrappers: boolean;
+    readonly templates: boolean;
+    readonly schemas: boolean;
+    readonly validators: boolean;
+}
+export interface RuntimeManifest {
+    readonly schemaVersion: number;
+    readonly installedAt: string;
+    readonly installRequest: string;
+    readonly runtimeResolution: RuntimeResolutionManifest | null;
+    readonly installedRuntimes: readonly string[];
+    readonly installedAssets: InstalledAssets;
+}

package/dist/lib/types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.mjs.map

package/dist/lib/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../../src/lib/types.mts"],"names":[],"mappings":""}

package/dist/lib/version.d.mts

@@ -0,0 +1,2 @@
+export declare function getPackageVersion(): Promise<string>;
+export declare function getPackageRoot(): string;

package/dist/lib/version.mjs

@@ -0,0 +1,27 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const here = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(here, "..", "..", "package.json");
+let cachedVersion;
+function isVersionRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "version" in value &&
+        typeof value.version === "string");
+}
+export async function getPackageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    const raw = await readFile(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isVersionRecord(parsed)) {
+        throw new Error(`package.json has no string version: ${packageJsonPath}`);
+    }
+    cachedVersion = parsed.version;
+    return parsed.version;
+}
+export function getPackageRoot() {
+    return join(here, "..", "..");
+}
+//# sourceMappingURL=version.mjs.map

package/dist/lib/version.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.mjs","sourceRoot":"","sources":["../../src/lib/version.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;AAE/D,IAAI,aAAiC,CAAC;AAEtC,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAClC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,uCAAuC,eAAe,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAChC,CAAC"}

package/docs/architecture/storage-model.md

@@ -38,6 +38,10 @@ The task manifest, task index, instruction set, runs, and history are collected
   - optional inert agent notes under `notes/<slug>-<YYYY-MM-DD>.md`; a run reads them only when explicitly carried through `--clarification-response`
 
 Actual directory segments may be normalized into slugs to create safe paths.
+
+v2 run artifacts persist `participantRef`, `roleExecutionRef`, `invocationRef`, `attempt`, and `executionLabel` as stored fields. Readers must not reparse those strings from `workerId`, provider, or model labels. v1 bytes stay unread-write. A mixed or partial v2 payload is rejected.
+
+Shared Git common directories and other-stage refs are outside the mutation-audit enforcement surface. Dispatch records observed projection only; it does not claim to police every ref that a shared object store can see.
 However, the logical task key always retains the original input values in the form `project-id:task-group:task-id`.
 
 ### 2. Per-run execution artifacts
@@ -249,9 +253,9 @@ Examples of key fields:
 - `workflow.currentPhaseState`
 - `workflow.phaseStates`
 - `workflow.lastCompletedPhase`
-- `workflow.nextRecommendedPhase`
+- `workflow.nextRecommendedPhase` *(object `{phase, status, rationale}`; `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready` — an authoring rule, not a constraint the struct enforces: `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a stored non-`ready` pointer that still names a phase is a normal manifest state. Read `status` to decide whether anything can be launched.)*
+- `workflow.nextRecommendedPhaseCorrection` *(present only when Phase 7 validation replaced the authored pointer — `{authored, applied}`)*
 - `workflow.awaitingApproval`
-- `workflow.routingStatus`
 - `workflow.lastSafeCheckpoint`
 - `phaseOutcome` *(artifact-derived semantic phase outcome; for example, when the implementation carry proves that all stages passed, the implementation phase outcome may be recorded as completed even if run contract validation failures remain)*
 - `inputs`

package/docs/architecture.md

@@ -96,6 +96,10 @@ The two callers of `prepare_task_bundle` are:
 
 The host-native Okstra lead owns judgment policy and worker orchestration. okstra's prepare stage only creates structured assets so that the lead starts with the correct input bundle and output skeleton.
 
+Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `lead` is a compatibility alias for `leader`. `executor` is a compatibility alias for `implementer`. New artifacts write only the canonical names.
+
+Selection is role-first: `--role-count <role>=<N>` creates `RoleInstance` ordinals, `--role-model <role>=<modelRef>` and `modelDefaults` feed `ModelPool`, and a pinned model is kept only when the host can bind it exactly. The resulting `RoleExecution` owns `Invocation` and `Attempt` rows plus the stored `executionLabel`. Pane titles use that label. Shared Git object stores and other-stage refs are observed-projection only; they are not an audit enforcement surface.
+
 ## Runtime assets vs support assets
 
 Runtime entry points are consolidated in Python packages. Bash and skills only call into them.
@@ -307,7 +311,7 @@ The standard `okstra` workflow applies the following team contract consistently
 - The current host-native provider owns the synthesis-only lead session: Claude on Claude Code, Codex on Codex.
 - Every selected worker comes from the profile roster and provider capability registry. The default analysis policy remains Claude + Codex + a report writer; Antigravity, Grok, and Kimi are attempted only when the profile and resolved roster include them.
 - `Report writer worker` focuses on report structure and evidence organization, while the host-native lead remains the final synthesis owner. Claude is the default report-writer provider; Codex may be selected explicitly.
-- Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-build-0.1`, and Kimi analyser=`kimi-k2.7-code`.
+- Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-4.6`, and Kimi analyser=`kimi-k2.7-code`. Selectable catalog models may be assigned to every role.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
 - Worker timing begins at the atomic transition to `in-progress`, which records `workers[].startedAt` in `team-state.json`; prompt creation time is not a dispatch proxy. `okstra worker-state transition` and both dispatch adapters share `dispatch_state.transition_worker_status`, while `okstra worker-liveness --team-state ... --worker ...` reads that timestamp as the launch-grace authority for both probe kinds — the in-process audit sidecar is reused on re-dispatch, so only `startedAt` separates the previous attempt's last heartbeat from this dispatch's silence.
@@ -425,25 +429,27 @@ Selection rules:
 
 - With `--task-type <name>`, `prompts/profiles/<name>.md` is rendered as the task bundle's `instruction-set/analysis-profile.md`.
 - The single selector in the external interface is `task-type`.
-- The selected task type is reflected unchanged in `taskType`, `workflow.currentPhase`, and `workflow.nextRecommendedPhase` in task-manifest.json.
+- The selected task type is reflected unchanged in `taskType` and `workflow.currentPhase` in task-manifest.json. It is not written into `workflow.nextRecommendedPhase`: prepare only lowers an inherited `ready` pointer to `pending`, and the pointer's next value comes from the report this run produces.
 - It is also used as the run-directory path segment (`runs/<task-type>/...`).
 
 ### Standard task types
 
 Each task type enforces phase-specific allowed and forbidden actions. A run creates only the artifacts for its own task type and does not advance to the next phase. The next phase always begins with a new `okstra.sh` execution.
 
-| task type | Purpose | Core artifacts | Next recommended phase | Code changes allowed? |
+The fourth column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves behind. The pointer is an object `{phase, status, rationale}`; `status` is `ready`, `pending`, `blocked`, or `terminal`, and `phase` names a phase only under `ready`. Phase 7 does not decide the route — it projects the pointer from the report's own routing field (`scripts/okstra_ctl/next_phase.py::project`), named per row below. The authoring rule for the field is stated once, in the Phase 6 checklist of [`prompts/lead/report-writer.md`](../prompts/lead/report-writer.md); this table describes the outcome, not the rule.
+
+| task type | Purpose | Core artifacts | Next-phase pointer after Phase 7 | Code changes allowed? |
 |---|---|---|---|---|
-| `requirements-discovery` | Classify the request as bugfix, feature, refactor, ops, or improvement, then route it to a safe next phase | work category, routing decision, missing-input list, clarification requests | `error-analysis`, `implementation-option-selection`, or `pending-routing-decision` | No |
-| `error-analysis` | Analyze the symptoms, causes, and reproduction gaps of a reported error/incident based on evidence | symptom/trigger summary, root-cause hypotheses, reproduction gap, validation path | `implementation-option-selection` after a credible cause, or `error-analysis` for continued investigation | No |
-| `implementation-option-selection` | Compare or validate implementation directions before detailed planning | up to three ranked directions, per-direction `coveragePercent` and `scopePrecisionPercent`, rejected-candidate audit, separate `DIRECTION SELECTION` response | `implementation-planning` after a valid direction is confirmed; otherwise `blocked` | No (strictly read-only; source edits, builds, tests, migrations, and deploys are prohibited) |
-| `implementation-planning` | Expand one selected direction into an executable plan without changing its mechanism or architecture boundary | selected-direction snapshot/reference, direction realization, affected-file list, Stage Map, validation/rollback, exact plan coverage, YAML frontmatter `approved: false`, **§5.5.9 Plan Body Verification**. Existing plans without `planningContract: selected-direction` retain the legacy option-candidate and `implementation-option:` contract | `implementation` after separate plan approval, or `implementation-option-selection` when the direction is invalidated | No |
-| `implementation` | Modify source code according to the approved `implementation-planning` final report. **One run executes exactly one stage** (selected with `--stage <auto\|N>`) | commit list, diff summary, out-of-plan edits block, validation/TDD evidence, rollback verification, verifier results (Antigravity/Codex/Claude), `carry/stage-<N>.json` evidence sidecar | `final-verification` | Yes (limited to the approved plan's file list; `git push`/publish/deploy/real migration prohibited) |
-| `final-verification` | Check completed work for residual defects and regression risk, then make a release judgment | acceptance verdict, residual risk, follow-up routing (`error-analysis`/`implementation-option-selection`/`implementation-planning`/`release-handoff`) | `pending-release-handoff` when accepted; otherwise route by whether the defect is in the cause, selected direction, or detailed plan | No (read-only tests only) |
-| `release-handoff` | Deliver `accepted` changes as a commit, push, or PR according to the user's chosen method | user menu responses (H1 action / H2 PR base / H3 message handling), executed git/gh command log, commit SHA list, PR URL | `done-or-follow-up` | Yes—but execute **only the mutating commands selected by the user in the menu**. `git push --force*`, direct push to the base branch, `--no-verify`, `gh release`, and publish/deploy are prohibited. The source code itself must not be changed; package the existing `implementation` diff unchanged. |
-| `project-analysis` | Map the current project structure and feature index | components, dependencies, entry points, data stores, external systems, feature index | `pending-routing-decision` | No (strictly read-only; tests are also prohibited) |
-| `feature-analysis` | Trace one confirmed existing feature | flows, domain rules, state changes, external interactions, test coverage | `pending-routing-decision` | No (strictly read-only; tests are also prohibited) |
-| `change-impact-analysis` | Map the impact of one proposed change | preserved behavior, impact items, dependency blast radius, test and operational impact | `pending-routing-decision` | No (strictly read-only; tests are also prohibited) |
+| `requirements-discovery` | Classify the request as bugfix, feature, refactor, ops, or improvement, then route it to a safe next phase | work category, routing decision, missing-input list, clarification requests | from `requirementsDiscovery.routing.nextTaskType`: `ready` at `error-analysis` or `implementation-option-selection`; `pending` when the run settles on neither | No |
+| `error-analysis` | Analyze the symptoms, causes, and reproduction gaps of a reported error/incident based on evidence | symptom/trigger summary, root-cause hypotheses, reproduction gap, validation path | from `errorAnalysis.routing.nextTaskType`: `ready` at `implementation-option-selection` after a credible cause, or at `error-analysis` for continued investigation | No |
+| `implementation-option-selection` | Compare or validate implementation directions before detailed planning | up to three ranked directions, per-direction `coveragePercent` and `scopePrecisionPercent`, rejected-candidate audit, separate `DIRECTION SELECTION` response | from the `implementationOptionSelection.routing` string enum: `ready` at `implementation-planning` once a direction is confirmed, `pending` on `pending-direction-selection`, `blocked` on `blocked` | No (strictly read-only; source edits, builds, tests, migrations, and deploys are prohibited) |
+| `implementation-planning` | Expand one selected direction into an executable plan without changing its mechanism or architecture boundary | selected-direction snapshot/reference, direction realization, affected-file list, Stage Map, validation/rollback, exact plan coverage, YAML frontmatter `approved: false`, **§5.5.9 Plan Body Verification**. Existing plans without `planningContract: selected-direction` retain the legacy option-candidate and `implementation-option:` contract | from `implementationPlanning.outcome`: `ready` at `implementation` on `plan-ready` (the plan still needs its separate approval before that run starts), `ready` at `implementation-option-selection` on `direction-invalidated` | No |
+| `implementation` | Modify source code according to the approved `implementation-planning` final report. **One run executes exactly one stage** (selected with `--stage <auto\|N>`) | commit list, diff summary, out-of-plan edits block, validation/TDD evidence, rollback verification, verifier results (Antigravity/Codex/Claude), `carry/stage-<N>.json` evidence sidecar | from `implementation.routingRecommendation.target`: `ready` at that phase — `final-verification` on a clean stage, otherwise `error-analysis`, `implementation-planning`, or `implementation` | Yes (limited to the approved plan's file list; `git push`/publish/deploy/real migration prohibited) |
+| `final-verification` | Check completed work for residual defects and regression risk, then make a release judgment | acceptance verdict, residual risk, follow-up routing (`error-analysis`/`implementation-option-selection`/`implementation-planning`/`release-handoff`) | from `finalVerification.routingRecommendation.target`: `ready` at that value — `release-handoff` only on an `accepted` verdict, otherwise the phase owning the defect (cause, selected direction, or detailed plan). `release-handoff(stage-group)` is a scope qualifier on the same phase, so it projects to `release-handoff`. `done` becomes `terminal` | No (read-only tests only) |
+| `release-handoff` | Deliver `accepted` changes as a commit, push, or PR according to the user's chosen method | user menu responses (H1 action / H2 PR base / H3 message handling), executed git/gh command log, commit SHA list, PR URL | always `terminal` — the lifecycle ends here and this report has no routing field Phase 7 projects from | Yes—but execute **only the mutating commands selected by the user in the menu**. `git push --force*`, direct push to the base branch, `--no-verify`, `gh release`, and publish/deploy are prohibited. The source code itself must not be changed; package the existing `implementation` diff unchanged. |
+| `project-analysis` | Map the current project structure and feature index | components, dependencies, entry points, data stores, external systems, feature index | always `pending` with no phase — a sidetrack settles no route | No (strictly read-only; tests are also prohibited) |
+| `feature-analysis` | Trace one confirmed existing feature | flows, domain rules, state changes, external interactions, test coverage | always `pending` with no phase — a sidetrack settles no route | No (strictly read-only; tests are also prohibited) |
+| `change-impact-analysis` | Map the impact of one proposed change | preserved behavior, impact items, dependency blast radius, test and operational impact | always `pending` with no phase — a sidetrack settles no route | No (strictly read-only; tests are also prohibited) |
 
 Common constraints:
 
@@ -748,7 +754,7 @@ The report writer records the decision unchanged in `implementationPlanning.incr
 scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path>
 ```
 
-Abbreviated form for a later phase (if the manifest's `workflow.nextRecommendedPhase` is `implementation-planning`, `--task-type` may also be omitted):
+Abbreviated form for a later phase (if the manifest's `workflow.nextRecommendedPhase` is `{"phase": "implementation-planning", "status": "ready", ...}`, `--task-type` may also be omitted):
 
 ```bash
 scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --workers claude,codex
@@ -802,9 +808,9 @@ Checking the following fields first makes it easy to determine the current posit
 - `workflow.currentPhaseState`
 - `workflow.phaseStates`
 - `workflow.lastCompletedPhase`
-- `workflow.nextRecommendedPhase`
+- `workflow.nextRecommendedPhase` *(object `{phase, status, rationale}`; `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready` — an authoring rule, not a constraint the struct enforces: `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal manifest state. Read `status` to decide whether anything can be launched.)*
+- `workflow.nextRecommendedPhaseCorrection` *(present only when Phase 7 validation replaced the authored pointer — `{authored, applied}`, where `authored` is the pointer the lead wrote)*
 - `workflow.awaitingApproval`
-- `workflow.routingStatus`
 - `workflow.lastSafeCheckpoint`
 - `phaseOutcome`
 
@@ -822,8 +828,9 @@ Resume decision rules:
 
 - Resume the current run: if `latestResumeCommandPath` exists, use that path first.
 - Restart the current phase: run again with the same `task-key` and current `task-type`.
-- Start the next phase: if `workflow.nextRecommendedPhase` is a concrete phase, prepare the next `okstra.sh` run with that value.
-- Additional material required: if `routingStatus=pending` or `nextRecommendedPhase=pending-routing-decision`, augment the brief first.
+- Start the next phase: if `workflow.nextRecommendedPhase.status` is `ready`, prepare the next `okstra.sh` run with its `phase`.
+- Additional material required: if that `status` is `pending` or `blocked`, the pointer carries no phase. Read its `rationale`, augment the brief, and rerun the phase that left the pointer unsettled.
+- Nothing left to run: `status` `terminal` means the lifecycle ended at this phase.
 
 ## Final report structure
 
@@ -921,7 +928,7 @@ Tokens used in each run are collected from lead/worker session transcripts and w
 - CLI execution evidence and token attribution are independent. A wrapper `.status.json` proves `not-started`, `started`, `exited`, `timeout`, or `failed` and supplies the worker's collection window; only a matching transcript with a final token snapshot proves attributable usage. If a wrapper exited successfully but no attributable transcript exists, the worker remains `source: "unavailable"` with `cliExecutionStatus: "exited"` and a reason instead of becoming zero usage or being described as never invoked.
 - Records billable-equivalent token math and USD cost estimates. It applies Anthropic billing ratios (`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`). When the transcript provides separate `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` values, they are counted separately.
 - Pricing is centrally managed in `scripts/okstra_token_usage/pricing.py`. Update it when model prices change. Model IDs that fail price matching are exposed to the user in `usageSummary.unmatchedModels`, preventing silent-zero incidents.
-- Project-wide historical usage is exposed through the read-only `okstra usage-report` command (`src/commands/inspect/usage-report.mjs` → `scripts/okstra_ctl/usage_report.py`) and the `okstra-usage` skill. It defaults to the whole current project's last 30 days and returns run coverage, raw and billable-equivalent tokens, known USD cost, CPU-sum milliseconds, and wall-clock milliseconds grouped by task type. Runs without usable Phase 7 usage are excluded from resource totals and reported through unavailable reason counts rather than treated as zero usage; unmatched model names remain visible when their tokens and time are included but their cost is not. Use `okstra-inspect` for one task's elapsed/context detail and `okstra-rollup` for task-group or project status/report digests.
+- Project-wide historical usage is exposed through the read-only `okstra usage-report` command (`src/commands/inspect/usage-report.mts` → `scripts/okstra_ctl/usage_report.py`) and the `okstra-usage` skill. It defaults to the whole current project's last 30 days and returns run coverage, raw and billable-equivalent tokens, known USD cost, CPU-sum milliseconds, and wall-clock milliseconds grouped by task type. Runs without usable Phase 7 usage are excluded from resource totals and reported through unavailable reason counts rather than treated as zero usage; unmatched model names remain visible when their tokens and time are included but their cost is not. Use `okstra-inspect` for one task's elapsed/context detail and `okstra-rollup` for task-group or project status/report digests.
 - **Incremental scan cache (P6)**: To avoid rescanning session jsonl files, a per-file byte cursor and the extracted usage events before windowing are stored in `$OKSTRA_HOME/cache/token-usage/<transcript-dir>/<sessionId>.json` (`scripts/okstra_token_usage/cursor.py`). The run window (since/until) is reevaluated over events on every invocation, so even if a rerun narrows the window, the total matches a full scan. The cache is derived data; identifier mismatch, truncation, or corruption automatically falls back to a full rescan, and `okstra-token-usage.py --no-cache` forces a bypass.
 - **Phase timeline (P0 instrumentation)**: The collector extracts `PROGRESS: phase-*` checkpoint lines (see "Progress reporting" in prompts/lead/okstra-lead-contract.md) from the lead session jsonl scoped to the run window, and records them in team-state as a `phaseTimeline` block (`{source, phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`) (`scripts/okstra_token_usage/collect.py :: phase_timeline`). This provides measurement points for per-phase wall-clock time within the run and is consumed by the "Per-run phase breakdown" in the `okstra-inspect` time facet. Runs without markers explicitly report that measurement is unavailable with `phases: []`.
 
@@ -936,7 +943,9 @@ Entry points that enforce whether phase artifacts may be published:
 
 Each validator blocks the phase with a `contract-violated` exit code when a contract is breached. Violations are applied when the next phase executes, leaving prior artifacts unchanged.
 
-`contractValidation.status=failed` means the run artifact contract failed; it does not necessarily mean the implementation itself is incomplete. An implementation run derives `phaseOutcome.implementation` from `runs/implementation/carry/stage-<N>.json`, `runs/implementation-planning/consumers.jsonl`, and the approved Stage Map together. If every Stage Map stage has pass-grade carry evidence, it can retain the contract failure as audit information while correcting `workflow.nextRecommendedPhase` to `final-verification`.
+**Blocking failures vs advisories.** `validate-run.py` splits its findings into `validation.failures` and `validation.advisories` (both written to the run manifest and team state, and printed on stdout; advisories also go to stderr one per line). Only `failures` decide `validation.status`, so a run can pass while carrying advisories. The dividing line is whether a remedy still exists at Phase 7: a defect in the report is fixable by re-authoring and re-rendering, while a defect in what an *already-ended session* wrote down is not — the worker that would restate its citation and the lead pane that would emit its PROGRESS line are both gone, so the only remaining move is to void the phase, which blocks the next one without establishing that any conclusion in the report is wrong. Two surfaces are advisory today: the worker citation ledger (`okstra_ctl.worker_audit_ledger.worker_results_audit_findings` — a `path:line` citation with no matching Evidence read row; a missing or unreadable sidecar stays blocking) and the PROGRESS narration lines (`validators/validate_session_conformance.py` `SessionConformanceResult.advisories`; the user-confirmation cross-check stays blocking because it verifies a claim the report makes). **Enforced:** `tests/contract/test_worker_audit_check.py::test_an_unmatched_citation_is_advisory_and_a_missing_sidecar_is_not` and `tests/contract/test_validate_session_conformance.py::test_missing_checkpoints_are_advisory_not_blocking`.
+
+`contractValidation.status=failed` means the run artifact contract failed; it does not necessarily mean the implementation itself is incomplete. An implementation run derives `phaseOutcome.implementation` from `runs/implementation/carry/stage-<N>.json`, `runs/implementation-planning/consumers.jsonl`, and the approved Stage Map together. If every Stage Map stage has pass-grade carry evidence, it can retain the contract failure as audit information while raising `workflow.nextRecommendedPhase.status` to `ready`. It does not choose the phase: the reconciler's fact is that every stage finished, and the destination was already settled by the last stage's report routing, so it leaves `phase` untouched and raises the status only when `phase` is non-empty.
 
 ## Practical notes