okstra 0.201.2 → 0.202.0

package/bin/okstra

@@ -50,4 +50,4 @@ async function main(argv) {
   }
 }
 
-main(process.argv).then((code) => process.exit(code));
+process.exitCode = await main(process.argv);

package/dist/commands/lifecycle/setup.mjs

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
+import { ensureCitationGuidance } from "../../lib/citation-guidance.mjs";
 import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
 import { errorCode, errorMessage, fileExists, runProcess } from "../../lib/proc.mjs";
 const USAGE = `okstra setup — register the current project with okstra
@@ -20,6 +21,9 @@ Usage:
                                           on the command line
 
 Behavior:
+  - If <PROJECT_ROOT>/CLAUDE.md or AGENTS.md exists, an okstra-managed block is
+    appended (or refreshed) telling agents not to cite okstra-internal ids and
+    .okstra/ paths outside okstra reports. Neither file is created.
   - If project.json already exists, the projectId must match (okstra refuses
     to silently rename a project). Delete the file manually if you really
     want to change projectId.
@@ -229,11 +233,22 @@ export async function run(args) {
         process.stderr.write(`warning: failed to provision .claude/settings.local.json symlink — ` +
             `host Claude Code sessions in this project may need to add wrapper permissions manually. (${errorMessage(err)})\n`);
     }
+    // 프로젝트에 host 지침 문서(CLAUDE.md / AGENTS.md)가 이미 있으면, okstra 산출물
+    // 인용 규율 블록을 그 끝에 심는다. 없는 파일은 만들지 않는다.
+    let citationGuidance = [];
+    try {
+        citationGuidance = await ensureCitationGuidance(projectRoot);
+    }
+    catch (err) {
+        process.stderr.write(`warning: failed to update okstra citation guidance in CLAUDE.md / AGENTS.md — ` +
+            `agents in this project may quote okstra-internal ids in non-okstra writing. (${errorMessage(err)})\n`);
+    }
     process.stdout.write(JSON.stringify({
         ok: true,
         ...result,
         projectJsonPath,
         settingsLocalJson: settingsSymlink,
+        citationGuidance,
     }, null, 2) + "\n");
     return 0;
 }

package/dist/commands/lifecycle/setup.mjs.map

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

package/dist/lib/citation-guidance.d.mts

@@ -0,0 +1,21 @@
+export declare const GUIDANCE_BEGIN = "<!-- okstra:citation-guidance:begin -->";
+export declare const GUIDANCE_END = "<!-- okstra:citation-guidance:end -->";
+/** 관리 대상 host 지침 문서. 존재하는 것만 갱신한다. */
+export declare const GUIDANCE_TARGET_FILES: readonly ["CLAUDE.md", "AGENTS.md"];
+/** 마커로 감싼 블록 전문. 앞뒤 개행은 붙이는 쪽에서 관리한다. */
+export declare function renderGuidanceBlock(): string;
+/**
+ * 문서 본문에 블록을 반영한 결과를 돌려준다. 기존 블록이 있으면 그 자리에서
+ * 교체하고(문안이 바뀌어도 사용자가 쓴 앞부분은 그대로), 없으면 문서 끝에
+ * 붙인다. 내용이 이미 같으면 `changed: false` 로 파일을 건드리지 않는다.
+ */
+export declare function applyGuidance(content: string): {
+    content: string;
+    changed: boolean;
+};
+/**
+ * 프로젝트 루트의 host 지침 문서를 갱신하고, 실제로 쓴 파일 경로를 돌려준다.
+ * 없는 파일은 건너뛴다. `AGENTS.md` 가 `CLAUDE.md` 심링크인 흔한 배치에서는
+ * 같은 실파일을 두 번 쓰지 않도록 realpath 로 중복을 제거한다.
+ */
+export declare function ensureCitationGuidance(projectRoot: string): Promise<string[]>;

package/dist/lib/citation-guidance.mjs

@@ -0,0 +1,79 @@
+// okstra 산출물 인용 규율 블록을 대상 프로젝트의 host 지침 문서에 심는다.
+//
+// 배경: okstra 리포트는 `.okstra/` 안의 독자를 전제로 내부 식별자(리포트 절
+// 번호, `C-001` 같은 clarification id, run/stage id, `.okstra/...` 경로)를
+// 쓴다. 에이전트가 같은 식별자를 리포트 밖 글(대화 답변, 커밋/PR 본문,
+// 프로젝트 문서)에 그대로 옮기면 독자는 그 참조를 해석할 수 없다.
+//
+// 이 모듈은 `okstra setup` 이 프로젝트 루트에 **이미 있는** `CLAUDE.md` /
+// `AGENTS.md` 끝에 붙이는 관리 블록을 렌더하고 적용한다. 두 파일을 새로
+// 만들지는 않는다 — 없는 프로젝트는 host 지침 문서를 쓰지 않는다는 뜻이다.
+// 마커 규약은 `scripts/okstra_ctl/group_context.py` 의 task-memory 영역과 같다.
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+export const GUIDANCE_BEGIN = "<!-- okstra:citation-guidance:begin -->";
+export const GUIDANCE_END = "<!-- okstra:citation-guidance:end -->";
+/** 관리 대상 host 지침 문서. 존재하는 것만 갱신한다. */
+export const GUIDANCE_TARGET_FILES = ["CLAUDE.md", "AGENTS.md"];
+const GUIDANCE_BODY = [
+    "<!-- Managed by `okstra setup`. Edit above this block; this region is rewritten on each setup run. -->",
+    "",
+    "## Citing okstra artifacts",
+    "",
+    "okstra keeps its reports, decisions, and ledgers under `.okstra/`, written for readers of those reports.",
+    "Outside an okstra report — chat answers, commit messages, PR bodies, project docs, issue comments — do not",
+    "cite okstra-internal references (report section numbers, finding or clarification ids such as `C-001`,",
+    "run and stage ids, `.okstra/...` paths) as if the reader could resolve them. State the finding itself and",
+    "cite source code as `path:line`; name an okstra file only when the reader has been pointed to it.",
+].join("\n");
+/** 마커로 감싼 블록 전문. 앞뒤 개행은 붙이는 쪽에서 관리한다. */
+export function renderGuidanceBlock() {
+    return `${GUIDANCE_BEGIN}\n${GUIDANCE_BODY}\n${GUIDANCE_END}`;
+}
+/**
+ * 문서 본문에 블록을 반영한 결과를 돌려준다. 기존 블록이 있으면 그 자리에서
+ * 교체하고(문안이 바뀌어도 사용자가 쓴 앞부분은 그대로), 없으면 문서 끝에
+ * 붙인다. 내용이 이미 같으면 `changed: false` 로 파일을 건드리지 않는다.
+ */
+export function applyGuidance(content) {
+    const block = renderGuidanceBlock();
+    const begin = content.indexOf(GUIDANCE_BEGIN);
+    const end = content.indexOf(GUIDANCE_END);
+    if (begin !== -1 && end > begin) {
+        const next = content.slice(0, begin) + block + content.slice(end + GUIDANCE_END.length);
+        return { content: next, changed: next !== content };
+    }
+    const base = content.replace(/\s*$/, "");
+    const next = base.length === 0 ? `${block}\n` : `${base}\n\n${block}\n`;
+    return { content: next, changed: true };
+}
+/**
+ * 프로젝트 루트의 host 지침 문서를 갱신하고, 실제로 쓴 파일 경로를 돌려준다.
+ * 없는 파일은 건너뛴다. `AGENTS.md` 가 `CLAUDE.md` 심링크인 흔한 배치에서는
+ * 같은 실파일을 두 번 쓰지 않도록 realpath 로 중복을 제거한다.
+ */
+export async function ensureCitationGuidance(projectRoot) {
+    const written = [];
+    const seen = new Set();
+    for (const name of GUIDANCE_TARGET_FILES) {
+        const target = join(projectRoot, name);
+        let real;
+        try {
+            real = await fs.realpath(target);
+        }
+        catch {
+            continue; // 파일이 없거나 끊어진 심링크 — okstra 가 새로 만들지는 않는다.
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        const content = await fs.readFile(target, "utf8");
+        const applied = applyGuidance(content);
+        if (!applied.changed)
+            continue;
+        await fs.writeFile(target, applied.content, "utf8");
+        written.push(target);
+    }
+    return written;
+}
+//# sourceMappingURL=citation-guidance.mjs.map

package/dist/lib/citation-guidance.mjs.map

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

package/docs/architecture/storage-model.md

@@ -220,11 +220,13 @@ The following former files are no longer generated by okstra.
 ~/.okstra/managers/<manager-id>/
 ├── manager.json
 ├── projects.json
+├── view/index.html
 └── task-groups/<safe-task-group>/<safe-task-id>/
     ├── manifest.json
     ├── children.json
     ├── directives.jsonl
     ├── snapshots.json
+    ├── split-plan.json
     ├── events.jsonl
     └── child-context/<safe-project-id>-<safe-child-task-id>.md
 ```
@@ -234,9 +236,11 @@ Storage authority:
 - `manager.json`: manager identity and schema version.
 - `projects.json`: the projectId / projectRoot / role / tags registered with the manager. `projectRoot` must be an existing directory, and setup-equivalent registration is performed only when project-local `.okstra/project.json` is absent.
 - `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, and shared/project directives.
+- `split-plan.json`: the last tracker split plan `task split` applied. The briefs it produced live in each child project's `.okstra/briefs/`, and the children it registered carry `ticketId`, `briefPath`, `scope` and `recommendedPhase` in `children.json`.
 - `snapshots.json`: a read-side snapshot that `task sync` imports from the child project's `.okstra`. It is not the source of truth for project state.
 - `events.jsonl`: manager events such as `task-created` and `child-launch-prepared`.
 - `child-context/*.md`: child lead context prepared by `task run`. Sibling project reports/snapshots are passed only as read-side source material.
+- `view/index.html`: the page `okstra manager view` writes from the files above. It is a derived view, rewritten on every run; it does not read child projects, so it shows each task as of its last `task sync`.
 
 Path segments are normalized into slugs. If a slug would be empty, as can happen with non-ASCII values, a `u-<sha1-prefix>` fallback segment is used. However, `manifest.json` and the child `taskKey` preserve the original input values (`project-id:task-group:task-id`).
 

package/docs/architecture.md

@@ -128,7 +128,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - [`okstra_ctl.session`](../scripts/okstra_ctl/session.py) · [`okstra_ctl.seeding`](../scripts/okstra_ctl/seeding.py) — Claude session ID / resume command / installation validation / runtime settings.
 - [`okstra_ctl.{ids,index,invocation,jsonl,project_meta,reconcile,sequence,backfill,listing,locks}`](../scripts/okstra_ctl/) — existing central-index (`~/.okstra`) modules.
 - [`okstra_project.{resolver,state}`](../scripts/okstra_project/) — PROJECT_ROOT resolution + project.json upsert + task-catalog/manifest reader.
-- [`okstra_ctl.manager_cli`](../scripts/okstra_ctl/manager_cli.py), [`manager_store`](../scripts/okstra_ctl/manager_store.py), [`manager_sync`](../scripts/okstra_ctl/manager_sync.py), [`manager_launch`](../scripts/okstra_ctl/manager_launch.py), [`manager_paths`](../scripts/okstra_ctl/manager_paths.py) — cross-project manager state, one-way project snapshot sync, and child launch packet/context creation for `okstra manager`.
+- [`okstra_ctl.manager_cli`](../scripts/okstra_ctl/manager_cli.py), [`manager_store`](../scripts/okstra_ctl/manager_store.py), [`manager_sync`](../scripts/okstra_ctl/manager_sync.py), [`manager_launch`](../scripts/okstra_ctl/manager_launch.py), [`manager_paths`](../scripts/okstra_ctl/manager_paths.py), [`manager_view`](../scripts/okstra_ctl/manager_view.py), [`manager_split`](../scripts/okstra_ctl/manager_split.py) — cross-project manager state, one-way project snapshot sync, child launch packet/context creation, the HTML overview page, and tracker split into per-project scoped briefs for `okstra manager`.
 
 ### Bash entry points (thin)
 

package/docs/cli.md

@@ -823,7 +823,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, skill/agent installation, and model-pool state. The JSON `modelPool` object reports pool errors, default errors, binding precision, observed model, max write boundary, and invocation downgrade reason. It never sends an inference call. The `codex`, `antigravity`, and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
 | `okstra model list [--role <role>] [--host <host>] [--json]` | List catalog models for a host and optional role. Unselectable exact bindings report `exact binding unavailable`. No inference call |
 | `okstra model default set\|unset <role> ... --scope project\|global [--cwd <dir>]` | Atomically write or remove `modelDefaults` for one canonical role |
-| `okstra setup --project-id <id>` | Create or update `.okstra/project.json` in the current project |
+| `okstra setup --project-id <id>` | Create or update `.okstra/project.json` in the current project. When `<PROJECT_ROOT>/CLAUDE.md` or `AGENTS.md` already exists, it also appends — or refreshes in place — an okstra-managed block between `<!-- okstra:citation-guidance:begin -->` / `end` telling agents not to cite okstra-internal references (report section numbers, `C-NNN` ids, run/stage ids, `.okstra/...` paths) outside an okstra report. Neither file is created, and a failure is a warning, not an error |
 | `okstra check-project [--json]` | Verify that the current project is registered |
 | `okstra preflight [--runtime <name>] [--cwd <dir>] [--machine]` | Single skill-preflight call combining `ensure-installed`, with silent reinstall when stale, `check-project`, and host-specific `runtimeReadiness`. It defaults to a fixed text projection. `--machine` returns the automation JSON contract, and `--json` is a deprecated one-release alias. A `claude-code` host checks project workspace trust. A `codex` current-session host verifies write access to `~/.okstra/worktrees/registry.lock`; a sandbox denial blocks before the wizard with the `switch-codex-to-full-access-and-rerun` action. `antigravity` and `external` hosts return ready without reading Claude Code state. Step 0 of every project-scoped skill converges on this command |
 | `okstra convergence seed --groups <path> --work-state <path> --final-state <path> --migration-dir <dir> [--restart-from-round0]` | Create, resume, reuse, or explicitly recover deterministic convergence state |
@@ -856,7 +856,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Resolve the prior implementation-planning active context only through the current project and run authority, then emit fixed fields such as the executor base ref. Caller-supplied active-context paths are not accepted. |
 | `okstra report-translate <source\|write\|check-data> --run-manifest <path> …` | Resolve the report data and translation sidecar from the run manifest. `source` emits a source digest with the fixed translation queue; `write` requires that digest and rejects a stale report; `check-data` verifies the derived sidecar. Models never choose the data or sidecar path. |
 | `okstra convergence prepare-groups --run-manifest <path> --input <grouping.md>` | Parse fixed grouping Markdown, validate distinct per-worker evidence and group semantics against the run authority, then publish the schema-valid groups artifact at the run-owned path. |
-| `okstra manager <init\|discover-projects\|new\|task> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. |
+| `okstra manager <init\|discover-projects\|new\|task\|list\|view> [--json]` | Public CLI for grouping cross-project okstra tasks into manager-owned context. The default is purpose-specific fixed text for model use; `--json` preserves the machine contract and exit codes. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. `list managers`, `list projects --manager-id <id>` and `list tasks --manager-id <id>` enumerate manager state; `view --manager-id <id>` writes `~/.okstra/managers/<id>/view/index.html` and prints its path and `file://` URL. `task split --plan <json>` writes one validated brief with a `## Project Scope` section into each project an issue is assigned to and registers those children; `task run` then passes `--task-brief`. |
 | `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-rollup skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Omitting `--task-group` targets the whole project catalog. |
 | `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--text\|--json]` | Read-only backend for the okstra-usage skill. `--text` emits ordered fixed labels for model use. The default and `--json` preserve the full machine JSON contract and exit codes. Defaults to the current project's last 30 days. |
 | `okstra worker-state transition --team-state <path> --worker <id> --status <in-progress\|completed\|timeout\|error\|not-run> [--reason <text>] [--model <execution-value>]` | Atomically update one persisted worker row. `in-progress` records the authoritative `startedAt` and clears `endedAt`; terminal states record `endedAt`; `timeout`, `error`, and `not-run` require a reason. Dispatch adapters use this same transition path, so CLI-backed and in-process orchestration share the status timestamp contract |

package/docs/for-ai/skills/okstra-manager.md

@@ -33,8 +33,19 @@ okstra manager task note --manager-id <manager-id> --task-group <task-group> --t
 okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
 okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
 okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>]
+okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
+okstra manager list managers
+okstra manager list projects --manager-id <manager-id>
+okstra manager list tasks --manager-id <manager-id>
+okstra manager view --manager-id <manager-id>
 ```
 
+- `list managers`: every manager in this home with its project count and manager-task count.
+- `list projects`: the manager's registered projects with root, role, tags and link time.
+- `list tasks`: the manager's tasks by task-group and task-id with objective, progress mode and child count.
+- `task split`: reads a tracker split plan (one Linear project or parent issue, each issue assigned to one or more projects with a scope), writes one brief per (issue, project) pair to `<projectRoot>/.okstra/briefs/<task-group>/<ticketId>-<file-title>.md` with a `## Project Scope` section, and registers each pair as child `<project-id>:<task-group>:<slug(ticketId)>`. Every brief passes the brief validator before any file is written; an existing brief with different content stops the run unless `--overwrite` is given. The skill's Tracker Split section defines the plan JSON and the fetch/confirm procedure.
+- `view`: writes `view/index.html` (summary tiles, project table, one panel per task with child rows, directives and events) and returns `View path` and `View URL`. It does not sync; each panel shows its last sync time and the sync command.
+
 ## Storage Model
 
 Manager state is stored under `~/.okstra/managers/<manager-id>/`, split into two layers: the manager root and the task directory.
@@ -47,11 +58,13 @@ Directly under the manager root:
 Under the task directory `task-groups/<safe-group>/<safe-task>/`:
 
 - `manifest.json`: manager task objective, common brief, progress mode
-- `children.json`: child task plan, assignment, launch metadata
+- `children.json`: child task plan, assignment, launch metadata; children made by `task split` also carry `ticketId`, `briefPath`, `scope` and `recommendedPhase`
+- `split-plan.json`: the last plan `task split` applied
 - `directives.jsonl`: shared/project directive rows
 - `snapshots.json`: the read-side snapshot `task sync` read from the project-local `.okstra`
-- `events.jsonl`: manager events such as `task-created` and `child-launch-prepared`
+- `events.jsonl`: manager events such as `task-created`, `task-split` and `child-launch-prepared`
 - `child-context/<safe-project>-<safe-task>.md`: the child lead context `task run` produced
+- `view/index.html` (under the manager root): the overview page `view` writes; rewritten on every run
 
 A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<sha1-prefix>` path segment, but the manifest and the child `taskKey` preserve the original input value.
 
@@ -60,10 +73,14 @@ A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<s
 `task run` does not run the child work directly; it prepares a launch packet. The key fixed fields of the returned packet:
 
 - `Task key`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
-- `Backend`: always `subagent-child-lead`
+- `Backend`: always `spawn-process` — the child lead runs as a separate host process started by the installed launcher
 - `Worker dispatch backend`: always `subagent` in v1
 - `Project root`: the child project root
 - `Context path`: the manager child context markdown
-- every numbered `Run arg N`: the ordered `okstra run ... --directive "Read manager child context: ..."` arguments for the host launcher to use
+- `Run command`: the installed launcher, `~/.okstra/bin/okstra.sh`
+- every numbered `Run arg N`: the ordered launcher arguments `--project-root … --project-id … --task-group … --task-id … --directive "Read manager child context: …"`. A child made by `task split` also gets `--task-brief <briefPath>`, and `--task-type <recommendedPhase>` while the child task does not exist yet in its project
+- `Shell command`: `Run command` plus every `Run arg N`, shell-quoted; the skill hands this line to the user to run in a new terminal
+
+The launcher fills the task type and brief from the child task manifest when it exists and asks for the rest, then prepares the run and starts the lead with the directive in its prompt. `okstra run` is not a substitute: for a lead host it adds `--launch-only`, which drops the task inputs and the directive.
 
 When packet creation succeeds, that child launch's status in `children.json` is updated to `prepared`, and a `child-launch-prepared` is appended to `events.jsonl`. On failure it does not modify the project-local task state.

package/docs/for-ai/skills/okstra-setup.md

@@ -91,6 +91,15 @@ Create command:
 okstra setup --yes --project-root /abs/project --project-id my-project
 ```
 
+`okstra setup` also refreshes the okstra-managed citation-guidance block in
+`<PROJECT_ROOT>/CLAUDE.md` and `AGENTS.md` when those files already exist (it never
+creates them). The block tells agents not to carry okstra-internal references — report
+section numbers, `C-NNN` clarification ids, run/stage ids, `.okstra/...` paths — into
+writing that is not an okstra report, where the reader cannot resolve them. The command
+reports the files it touched in its JSON `citationGuidance` array; a failure there is a
+`warning:` line, not a non-zero exit. Tell the user which guidance files were updated so
+they can review the appended block.
+
 ## Optional configuration
 
 Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.

package/docs/project-structure-overview.md

@@ -29,7 +29,7 @@ Current baseline:
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-option-selection → implementation-planning → implementation → final-verification → release-handoff`
 - installed skills: 13
-- provider workers: `claude`, `codex`, `antigravity`, `grok`, `kimi`; functional report writer: `report-writer`
+- provider workers: `claude`, `codex`, `antigravity`, `grok`, `kimi`, `zai` (GLM via Claude Code); functional report writer: `report-writer`
 - final report SSOT: `schemas/final-report-v2.0.schema.json` + `*.data.json`
 
 Design principles:
@@ -224,7 +224,7 @@ Top-level scripts:
 | File | Role |
 |---|---|
 | `okstra.sh` | Bash CLI wrapper around `prepare_task_bundle`, optionally launches `claude` |
-| `okstra-{claude,codex,antigravity,grok,kimi}-exec.sh` | Worker CLI entrypoints — four lines each, `exec`ing `okstra-provider-exec.py` with the provider id. They hold no provider logic; adding a flag to one of these instead of to the provider adapter is exactly the drift this shape exists to prevent |
+| `okstra-{claude,codex,antigravity,grok,kimi,zai}-exec.sh` | Worker CLI entrypoints — four lines each, `exec`ing `okstra-provider-exec.py` with the provider id (`zai` selects the Z.ai GLM provider, which reuses the installed `claude` executable with process-local connection settings). They hold no provider logic; adding a flag to one of these instead of to the provider adapter is exactly the drift this shape exists to prevent |
 | `okstra-provider-exec.py` | The one worker entrypoint: parses the shared positional contract plus `--presentation`, resolves the provider's `ExecutionStrategy` from the registry, refuses a missing CLI before any artifact is written, then hands the run to `okstra_ctl.worker_runner` |
 | `okstra-wrapper-status.py` | Standalone writer for one worker status sidecar. No longer on the dispatch path — `worker_runner.py` writes the same document in-process |
 | `okstra-token-usage.py` | Token usage CLI entrypoint |
@@ -245,6 +245,8 @@ Important modules:
 | `exact_coverage.py` | Shared pure calculator for requirement coverage and scope precision in option selection and selected-direction planning |
 | `implementation_options.py` | Option-selection criteria, weighting, candidate fingerprint convergence, ranking, and semantic validation |
 | `implementation_direction.py` | Selected report/response validation, direction snapshot materialization, and selected-direction reference validation |
+| `technical_verification.py` | Optional `technical-verification` phase backend — resolves and freezes the explicitly classified unresolved facts from the same task's implementation-option-selection report into `state/technical-verification-input-<seq>.json` (`write_technical_verification_input` / `resolve_technical_verification_input`, driven from `run.py`). No selected direction is required and unresolved user decisions still block entry; it links test inputs to observed results and never produces adoption approval or changes candidate feasibility |
+| `verification_target.py` | Shared reader for the prepared final-verification target snapshot (`verification-target.md`) written by `run.write_verification_target_snapshot`. One implementation of the digest/scope rule serves both consumers — report assembly (records `verificationScope`) and `validators/validate-run.py` (re-checks the published report against the target) — so the two cannot drift |
 | `implementation_stage.py` | `implementation` single-stage run orchestration — read the Stage Lifecycle Snapshot → pick an available Stage Map entry → provision an isolated stage worktree → publish the selected stage as run context (extracted from `run.py`) |
 | `stage_targets.py` | Stage readiness/verification policy SSOT — from the Stage Lifecycle Snapshot (`consumers.jsonl` ledger + carry sidecar backfill + active registry reservation) it decides which stage is runnable, which commit it branches from, and what final-verification checks. `acquire_final_verification_target()` acquires the ledger, registry, worktree, Git, and optional whole-task integration facts behind one task-key mutex and returns a typed target without render-context coupling. `order_stage_closure` topologically sorts (Kahn) the dependency closure of the wizard's multi-selected stage set to produce the unattended `chain-stages` chaining order |
 | `stage_fix_carry.py` | fix-run carry derivation for a re-run on an `implementation` stage whose latest final-report data.json carries verifier `FAIL` verdicts — collects the previous report path, previous run HEAD, failed verifiers, carried blocking findings, and a routing recommendation, which `run.py` renders into the analysis profile through the `{{FIX_RUN_CONTEXT}}` token. A first run, or a re-run after `PASS`, yields no carry and renders the token empty |
@@ -300,7 +302,8 @@ Important modules:
 | `wizard/confirmation.py` | `confirmation_block` and the confirm step |
 | `wizard/registry.py` | the ordered `STEPS` literal (order is question order), `STEP_BY_ID`, `_reset_from`, and the steps that rewind the registry (edit target, brief carry) |
 | `wizard/engine.py` | public API — `init_state`, `next_prompt`, `submit`, progress / simulation, host interaction payloads |
-| `wizard/render.py` | `render_args`, `render_role_args`, `wizard_outcome` |
+| `wizard/render.py` | `render_args`, `render_role_args`, and the stage-intent helpers |
+| `wizard/outcome.py` | `wizard_outcome` — assembles the run argv, confirmation screen, and persistence actions from an approved `WizardState` (extracted from `render.py`) |
 | `wizard/cli.py`, `wizard/__main__.py` | `okstra wizard` argparse entrypoint (`main`); `python3 -m okstra_ctl.wizard` |
 | `wizard_stage_intent.py` | stage-related intent projection of the `okstra-run` wizard output — normalizes whole-task (`__whole_task__`) vs single/multi stage selection into render-args (`resolve_wizard_stage_intent`) |
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `backfill.py` | `~/.okstra` run index and history operations — `record_start` (index.py) writes a run's start; the end is closed either by `settle_run_row` (reconcile.py, records a verdict the caller already knows — used by `validate-run.py`) or by `reconcile_home` (infers one from disk — used by `run._reconcile_prior_runs` as the backstop for runs that died before validation) |
@@ -324,10 +327,13 @@ Important modules:
 | `plan_run_root.py` | shared helper deriving `approved_plan_path` → `plan_run_root` and back-tracing the task-key |
 | `manager_cli.py` | `okstra manager` Python entrypoint — purpose-specific fixed text by default, machine JSON with `--json` |
 | `manager_paths.py` | Manager state path SSOT under `~/.okstra/managers/<manager-id>/`; slug fallback uses `u-<sha1-prefix>` when a safe segment would be empty |
-| `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append |
+| `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append — plus the `list managers/projects/tasks` readers |
 | `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
 | `manager_launch.py` | Child launch packet and manager child context renderer; records `prepared` launch metadata/events without changing project-local task state |
+| `manager_view.py` | `okstra manager view` — renders one manager's projects, tasks, child summaries, directives and events into `view/index.html` from `templates/manager/view.template.html`; reads manager-owned files only |
+| `manager_split.py` | `okstra manager task split` — validates a tracker split plan, renders one brief per (issue, project) with a `## Project Scope` section, checks each with `validators/validate-brief.py` before writing, and registers the children |
 | `agent/invocation.py` | Deep invocation-contract module — composes model assignment, common/functional duty, and task instructions; publishes immutable prompt/metadata pairs; verifies five digests; owns standalone result/completion envelopes |
+| `agent/evidence_recovery.py` | Issues a same-model, same-role evidence-recovery invocation over a terminal-state attempt — verifies the source invocation metadata and existing result, then republishes a suffixed prompt/metadata/result triple (`-evidence-recovery-<attempt>`) that preserves the original model assignment while confining the child to preserving the earlier result's evidence rather than re-running the completed work (`prepare_evidence_recovery`, driven from `dispatch_core`) |
 | `agent/prompt_cli/` | CLI boundary for run-backed and standalone materialization/verification plus host-native dispatch and result-link records. `inputs` resolves the path arguments this model-facing surface cannot trust and `emit` writes the result; above them `run_identity` refuses a role the run never issued and `dynamic_verifier` reserves a re-verification slot only after that role qualifies; `materialize` authors the specification (every report-writer prompt gets the okstra-rendered `## Output`; with `--corrections` it runs the ledger check in `corrections` and prepends `## Corrections`; without one it refuses a corrective dispatch over a parsing narrative), `results` links what came back, and `cli` is the argparse surface with the command's canonical USAGE epilog (`check-corrections` runs the ledger check without materializing; `apply-corrections` writes a mechanical ledger to the narrative and records the `lead-correction-applied` activity row via `corrections.run_corrections_apply`) |
 | `dispatch_state.py` | Provider-neutral `WorkerJob`, invocation metadata validation, immutable host-native dispatch/result-link recording, and shared team-state mutation helpers |
 | `dispatch_core.py` | Backend-neutral worker dispatch core — verifies invocation metadata immediately before worker execution, then records and collects code-owned process/pane attempts shared by every lead runtime |
@@ -392,7 +398,7 @@ Project resolver and read-only state helpers:
 
 Token/cost accounting:
 
-- provider adapters: `claude.py`, `codex.py`, `antigravity.py`, `grok.py` (`grok.py` reads the Grok Build session docs under `~/.grok/sessions/<percent-encoded-cwd>/`, taking cumulative tokens from the last `params.update.usage.modelUsage` snapshot in `updates.jsonl`)
+- provider adapters: `claude.py`, `codex.py`, `antigravity.py`, `grok.py`, `kimi.py`, `zai/adapter.py` (`grok.py` reads the Grok Build session docs under `~/.grok/sessions/<percent-encoded-cwd>/`, taking cumulative tokens from the last `params.update.usage.modelUsage` snapshot in `updates.jsonl`; `zai/adapter.py` wraps the Claude Code executor for GLM workers — reads `ZAI_API_KEY` from the process env or the current user's `~/.env`, runs each child against `https://api.z.ai/api/anthropic` with `--setting-sources ""`, attests the served model only from response `message.model`, and prices usage at Z.ai's public API rates for `glm-5.3` / `glm-5.3-flash`)
 - aggregation: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`
 - incremental scan cache: `cursor.py` (`$OKSTRA_HOME/cache/token-usage/` byte cursor + usage event extracts; bypass with `--no-cache`)
 - pricing: `pricing.py`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.201.2",
+  "version": "0.202.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.201.2",
-  "builtAt": "2026-09-13T23:51:12.747Z",
+  "package": "0.202.0",
+  "builtAt": "2026-09-19T06:41:23.090Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/launch.template.md

@@ -76,7 +76,7 @@ For every other task type:
 - Pointer `status: pending` with a `rationale` → the user's own input is what comes next. Quote the `rationale` and issue the command it names. Do not re-run the phase that just completed, and do not send the user to `/okstra-inspect`: a finished phase has nothing to inspect, and re-running it discards the result the user is being asked to act on.
 - Otherwise → `/okstra-inspect status` for this task.
 
-For file links in progress updates and closeout, use a short descriptive label in the Report Language, such as `[<선택 언어> 보고서 열기](<actual-report-path>)`, replacing `<선택 언어>` with the run's selected report language name. Put each link on its own line. Keep the complete destination on one source line without inserted newlines or spaces; never abbreviate the destination or repeat the long path beside the label. Use the verified destination from `reportPaths.markdown` or the launch prompt's run paths, changing only the display label. Commands stay in backticks.
+For file links in progress updates and closeout, use a short descriptive label in the Report Language, such as `[<선택 언어> 보고서 열기](<absolute-report-path>)`, replacing `<선택 언어>` with the run's selected report language name. The destination is always an absolute path: a project-relative destination does not open when the host's working directory differs or the user opens the file in an external program. `reportPaths.markdown` destinations are already absolute; for a project-relative path from this prompt, prefix `{{PROJECT_ROOT}}/`. Wrap a destination that contains spaces in `<...>`. Put each link on its own line. Keep the complete destination on one source line without inserted newlines; never abbreviate the destination or repeat the long path beside the label. Change only the display label. Commands stay in backticks.
 
 Some terminal hosts expand Markdown links into visible paths. If that happens, provide a copyable file-opening command for the verified host OS in a code block, on one source line with the actual path safely shell-quoted (for example, `open` on macOS). Do not execute it unless asked. Do not promise that Markdown prevents visual wrapping, or create a shortened copy or symlink merely for display. This is presentation guidance, not runtime validation of the emitted message.
 

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -106,7 +106,7 @@ User-utterance interpretation rule:
 
 At each phase or implementation-stage boundary, at task completion, and before a controlled session pause or handoff, follow the launch prompt's "Progress, remaining work, and recommendation" guidance. Include the result and evidence, unfinished work and blockers, and the next action with its reason. During an authorized continuous run, deliver this update beside the checkpoint and continue; do not turn the update into an approval gate. The same guidance applies to the final reply after persistence below.
 
-Apply the launch prompt's file-link presentation guidance to these updates as well: short localized labels, one link per line, an intact verified destination, and a copyable file-opening command when the terminal expands links. Keep file links separate from the raw progress checkpoint line.
+Apply the launch prompt's file-link presentation guidance to these updates as well: short localized labels, one link per line, an intact absolute destination, and a copyable file-opening command when the terminal expands links. Keep file links separate from the raw progress checkpoint line.
 
 Follow the launch prompt's operation-level progress guidance: name the actual prepared artifact or executed check, distinguish preparation from execution and results, and cite the observed error when blocked. Apply its existing-authorization guidance before asking about provider data transfer again; reuse approval for the same recipients and material while respecting separate host execution permission.
 
@@ -343,6 +343,8 @@ For `improvement-discovery`, Lead records `## Primary Pass Assignments` in the P
 
 ### Phase 4 / Phase 5 — Dispatch, await, and error-log recording
 
+Before redispatch, inspect the invocation's last attempt in the run manifest. A running attempt is awaited; only `failed-no-mutation` can append another attempt within its retry budget. Other terminal states retain their original result and audit. For a legacy implementer rejected solely by `declared out-of-plan path did not change`, `okstra team dispatch` prepares a separate evidence-recovery invocation with the same assignment and model and distinct prompt/result paths. Collect that recovery result, then continue the selected independent verifier. Do not replay completed implementation or ask the user to reauthorize unchanged scope. For other terminal failures, use `okstra agent-prompt materialize` with a new `--invocation-id` and distinct `--prompt`/`--result` paths for the bounded verified defect or missing evidence. These retry restrictions are enforced by `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt`.
+
 For each selected worker assignment, persist the exact prompt history, emit the per-worker Phase 4 checkpoint, and call `dispatch_worker(assignment, promptPath)` through the selected adapter — the dispatch hands the worker the persisted prompt's path, never a re-inlined copy of its body. Then call `await_workers(handles)`. A dispatch acknowledgement or process/pane creation is never completion: verify the terminal status, Result Path, and worker-results audit path required by `team-contract` before emitting the Phase 5 collection checkpoint.
 
 Retries and convergence re-verification always call `redispatch_worker` to create a fresh one-shot session. Never reuse a worker conversation or switch adapters/providers to hide a failed assignment.
@@ -357,7 +359,7 @@ The launch prompt's `## Run Logs (error-log wiring)` section gives Lead the reso
 
 Workers are contractually required to extract this line and abort with `<WORKER>_ERRORS_PATH_MISSING` if it is absent (see each worker definition's "Path extraction (BLOCKING)" block). A worker records its tool failure through the typed `okstra error-log append-observed` form in that contract; it does not write an intermediate JSON file.
 
-After each worker terminates, BEFORE classifying its terminal status, verify the canonical result file exists at the absolute path resolved from the `**Result Path:**` header. If it is absent — or the deterministic provider process returned `CODEX_RESULT_MISSING` / `ANTIGRAVITY_RESULT_MISSING` — re-dispatch the SAME worker once with the byte-identical prompt. Only after the second attempt also misses may the role be classified `error` with `--message "result-missing after 1 retry"`. Full rules: [team-contract](./team-contract.md) "Lead Redispatch Policy on Result-Missing".
+After each worker terminates, verify the canonical result file at `**Result Path:**` and inspect the recorded mutation status. A missing result permits the same worker/prompt retry only for `failed-no-mutation` within its retry budget. A terminal state with changes or unresolved attribution requires a separate bounded corrective invocation, preserving existing work and evidence. Full rules: [team-contract](./team-contract.md) "Lead Redispatch Policy on Result-Missing".
 
 `--agent`, `--agent-role`, and `--error-type` are **closed enums**, not free-form labels — the role names used elsewhere in these contracts (`Codex worker`, `Claude worker`) are rejected. Use exactly:
 
@@ -527,7 +529,7 @@ When the host native picker is available and two of those rows could apply, ask
 
 **Cite run-artifact paths, do not assemble them.** The `report-finalize` result's `reportPaths` carries this run's `humanReport`, `reportRecord`, `teamState`, and `renderFullCopy` command, each already rooted at the project (`.okstra/tasks/<task-group>/<task-id>/runs/...`). Every other run-artifact path the reply cites — the resume command among them — comes from the launch prompt's `## Manifests` / `## Run Paths` lists, which are rooted the same way. A path you compose from a `runs/<task-type>/...` pattern instead is identical across every task of that task-type, so it names no task and does not resolve from the project root either.
 
-Write file references as Markdown links with short labels in the Report Language, following the launch prompt's file-link presentation guidance. `reportPaths.markdown` supplies verified destinations for the report, report record, and team state; preserve those destinations and shorten only their display labels. Put each link on its own line without repeating the path in prose or inserting a line break inside the destination. Apply the same format to worker results, error logs, and briefs, using the project-rooted paths from `## Manifests` / `## Run Paths`. If the terminal expands links into long paths, offer the host-appropriate copyable file-opening command described in the launch prompt. Markdown alone does not guarantee clickable links in every terminal.
+Write file references as Markdown links with short labels in the Report Language, following the launch prompt's file-link presentation guidance. `reportPaths.markdown` supplies absolute destinations for the report, report record, and team state; preserve those destinations and shorten only their display labels. Put each link on its own line without repeating the path in prose or inserting a line break inside the destination. Apply the same format to worker results, error logs, and briefs: take the project-rooted path from `## Manifests` / `## Run Paths` and prefix the absolute project root, so every link destination is absolute. Relative paths stay in commands, not in link destinations. If the terminal expands links into long paths, offer the host-appropriate copyable file-opening command described in the launch prompt. Markdown alone does not guarantee clickable links in every terminal.
 
 **Enforced:** `scripts/okstra_ctl/report_finalize.py` `_closeout_report_paths` builds the task-qualified paths and `closeout_command` builds the close, so neither is re-derived; `validators/validate_session_conformance.py` `_check_progress_checkpoints` requires the `phase-7-persist` checkpoint this phase opens with.
 
@@ -568,3 +570,13 @@ The run-level error log lives at `<runDir>/logs/errors-<task-type>-<seq>.jsonl`.
 | Re-sending a finding absent from the persisted round plan | Dispatch exactly the engine-returned `findingIds`; see [convergence](./convergence.md) "Re-verification Dispatch" |
 | Aggregating a `timeout`/`error` reverify dispatch as `DISAGREE` | Put the terminal outcome in round results; `apply-round` records `verification-error`. See [convergence](./convergence.md) "Worker failure handling in reverify" |
 | Bypassing `report-finalize` and running its Phase 7 steps manually | Run `okstra report-finalize ...`; it owns token substitution and the remaining persistence order. |
+
+## Recoverable completion discrepancies
+
+Treat `plannedPaths` as an expected change inventory, not an exhaustive authorization list. `ExecutionMutationAudit.compare` enforces write authority and emits plan discrepancies as warnings; `dispatch_state.missing_completion_paths` checks required result availability and usability. Collect usable results with warnings and pass the observed changes and unresolved evidence to independent verification before declaring task completion.
+
+Preserve original results and attempt identities when correcting declaration formatting, missing rationale, or required artifacts. Continue the smallest affected repair within the approved objectives. Do not restart implementation or request renewed permission solely for a plan-path mismatch. If a required artifact is unusable, repair that artifact and keep only its dependent steps waiting. If the same repair produces no new evidence, report the unresolved requirement and resume point instead of repeating the whole implementation.
+
+Ask for user judgment only when the proposed work changes approved objectives or acceptance conditions, crosses an explicit authority boundary, or adds an unapproved external action. A warning does not waive read-only roles, protected paths, independent verification, or final acceptance checks. Never convert an old closed failed attempt into success by overwriting its audit; use a recorded recovery with independent evidence.
+
+For a closed attempt whose only failure was a declaration discrepancy, preserve that attempt and its original result. Use the existing `agent-prompt materialize` and dispatch workflow to create a bounded evidence-recovery invocation in the same run, with a distinct result path and explicit references to the original invocation, result, and audit. Ask it to reconcile the declaration and required artifacts against current evidence, not repeat completed implementation. Then dispatch the selected independent verifiers against the current source and artifacts. Adopt the new verified result through normal result collection; retain the original failure as history. Do not use this route to bypass a real authority violation or unresolved code defect.

package/runtime/prompts/lead/team-contract.md

@@ -167,6 +167,8 @@ Branch on the exit code, not the JSON: without `--wait`, `0` = every probe healt
 
 ## Lead Redispatch Policy on Result-Missing
 
+For V2 calls, check the recorded attempt before applying any retry below. Only `failed-no-mutation` may append an attempt within its budget. Await an unfinished attempt. Preserve other terminal attempts and use a separate bounded corrective invocation with the same assignment/model and distinct prompt/result paths; do not replay implementation that already changed source or artifacts. `dispatch_core._next_attempt` and `execution_manifest._validate_next_attempt` enforce this restriction. A legacy declaration-only implementer rejection is routed by `okstra team dispatch` to evidence recovery before independent verification.
+
 After each worker attempt returns (regardless of role), Lead MUST verify the canonical result file exists at the absolute path resolved from the `**Result Path:**` anchor header (against `**Project Root:**`). The check is identical for host-native workers and deterministic CLI processes.
 
 **Triggers (any of):**

package/runtime/prompts/profiles/_implementation-executor.md

@@ -92,8 +92,8 @@ template's check; that template is gone.
 
 ## Allowed actions during the run
 
-- **Edit / Write on approved project source files**: scope is bounded first by the shared Resource boundary, then by the approved plan's file list. Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in your worker result's `Out-of-plan edits` block with rationale.
-  - **The block's shape is fixed, because a machine reads it (BLOCKING).** Write a `## Out-of-plan edits` heading, then one `- ` line per file whose first backticked token is the repository-relative path, followed by the rationale: ``- `src/http/router.ts` — the plan's step 3 needs a route the plan did not list``. Nothing else on that line is read. With no such edits, write the heading and the single line `- (none)`. The write audit compares the stage's changed files against the plan's paths union this block: a file edited outside the plan and absent here settles the run as a contract violation, and a path this parser cannot find is the same as one you never declared.
+- **Edit / Write on approved project source files**: scope is bounded by the shared Resource boundary and the approved objectives and acceptance conditions; the plan's file list predicts expected changes. Editing files outside the plan's list is permitted only when strictly needed to satisfy a step, and MUST be recorded in your worker result's `Out-of-plan edits` block with rationale.
+  - Use `## Out-of-plan edits` with a backticked path and rationale per item when convenient. The dispatcher reads this shape as supporting evidence, not write authorization. `ExecutionMutationAudit.compare` records observed changes independently and treats missing declarations or declaration/diff mismatches as warnings. Do not rerun implementation merely to repair this block; reconcile the explanation while preserving the original result. Required result usability is checked by `dispatch_state.missing_completion_paths`; source-readonly, protected paths, assigned roots and Git authority remain enforced by the write audit.
 - read-only inspection commands: `git status`, `git diff`, `git log`, `grep`, `rg`, `find`, `cat`, `ls`, file Read tools
 - build, lint, type-check, and test commands (`npm test`, `pytest`, `go build`, `cargo test`, `bash -n`, etc.)
 - **local git operations only**: `git add`, `git commit`. Prefer small commits keyed to plan steps.

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -23,7 +23,7 @@ Every verifier acts as a QA gate, not just a diff reviewer. Trusting the executo
   
 ### Record the verification target
 
-Before each declared check, run `okstra verification-target --project-root <project-root> --run-manifest <run-manifest> --expected-head <executor-head> --command <exact-declared-command>` and preserve its JSON output under this run's artifact directory. This tool reads the active run's recorded worktree and checks its HEAD and source fingerprint; it never executes the command. Execute the declared command through the host's authorized tool with that worktree as its separate working-directory argument. Repeat the target check with `--baseline <saved-json>` after execution. Include both target-check results and the actual command outcome in `readOnlyCommandLog`.
+Before each declared check, run `okstra verification-target --project-root <project-root> --run-manifest <run-manifest> --expected-head <executor-head> --command <exact-declared-command>` and preserve its JSON output under this run's artifact directory. This tool reads the active run's recorded worktree and checks its HEAD and source fingerprint; it never executes the command. Execute exactly the returned `target.command` through the host's authorized tool with `target.cwd` as its separate working-directory argument. The tool separates a legacy trailing `; existing helper: <file>:<lines>` annotation and removes a leading `cd` only when it names that exact worktree. Preserve `declaredCommand` and `commandAnnotation` when returned; never independently trim prose or rewrite shell syntax. Repeat the target check with the same original declaration and `--baseline <saved-json>` after execution. Include both target-check results and the actual command outcome in `readOnlyCommandLog`. Enforcement: `capture_verification_target` and `test_verification_target_returns_one_command_without_executing_it`.
 
 A target mismatch or changed fingerprint invalidates this check's evidence. Record it as an execution-target problem, preserve the source, and rerun only the affected verification after the lead resolves it. An unavailable environment or a check that never ran is not a code rejection. A matching target fingerprint proves source stability at the two observations; it does not prove the command ran or that the test covers the requirement. Keep the independent command outcome and coverage assessment.
 
@@ -256,3 +256,9 @@ If every verifier present in the resolved roster ends with a non-result terminal
 ## Executor completion self-check (not this role's gate)
 
 - The executor's `Implementation self-check` gate (`prompts/profiles/_implementation-self-check.md`) belongs to the worker that owns the diff, and its body is deliberately not delivered here: it asks for in-place fixes and break-then-restore mutation checks, every one of which this verifier is forbidden to perform. Do not re-derive its items or claim to have run it. What grades the same defects from this side is the blocking taxonomy above, applied to the diff you re-read yourself. When the executor's `Coverage:` / `Self-check coverage:` lines are among the inputs this prompt enumerates, a missing line or one whose file list does not reconcile with the diff is a blocking finding — the gate was skipped or partially run.
+
+## Plan differences and completion recovery
+
+Review the observed source and artifact changes, including paths absent from the planned file list or the executor's declaration. Link necessary changes to the approved objectives and acceptance conditions. A file-list discrepancy, declaration spelling, or a restored file is not an implementation failure by itself. Record missing rationale as evidence to reconcile. Reject unrelated scope expansion or weakened acceptance checks on their substantive impact, with the affected requirement and evidence.
+
+When the audit reports unavailable historical artifact coverage, verify the current artifact content and its acceptance checks independently. Do not reconstruct missing before-state from the current file or claim that a source-only diff proves an artifact did not change. Preserve the original result and qualify any unverified attribution. Required independent validation remains enforced by `validate-run.py::_validate_verifier_reran_independently` and the existing conformance gates.

package/runtime/prompts/profiles/implementation-planning.md

@@ -1,5 +1,7 @@
 # Implementation Planning Profile
 
+Keep `commandOrObservation` executable when the checklist calls for a command. Put explanations and existing-helper citations in the checklist's `check` text, outside the command. Do not append prose after a semicolon. The plan-item renderer separates legacy `existing helper: <file>:<lines>` suffixes, and `verification-target` supplies the same executable command to every verifier.
+
 Validation commands are executable inputs: preserve their newlines, quotes, and code bodies. Use frozen dependency installation (`npm ci`, `pnpm install --frozen-lockfile`, or the package manager's equivalent). Name QA scripts with absolute task-artifact paths when a command runs from a stage worktree; `.okstra/tasks/...` relative to that worktree does not point to the project task. `stage_validation_executability_errors` enforces command restrictions at planning validation, implementation entry, and report preflight, including advisory plan-body runs.
 
 Plan for the actual worktree layout before approval. Shared documentation directories can be links to the main checkout. Choose a build command compatible with those links (for example, an installed Next.js version may provide `next build --webpack`); verify the available option rather than assuming it. Do not plan for a verifier to move links or repair its environment. Compare negative-case assertions with the brief and the script body: a requirement to cache existing assets does not establish that missing assets should be cached. Record any changed expectation in a new plan revision; preserve the earlier approved plan.