okstra 0.124.0 → 0.125.1

package/runtime/skills/okstra-inspect/facets/cost.md

@@ -0,0 +1,84 @@
+# okstra-inspect facet — cost
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## cost
+
+Trigger phrases: "okstra context-cost", "context cost", "context-cost", "read cost", "artifact cost", "task bundle cost", "agent read cost".
+
+Read-only estimate of how much file/context surface a prepared task bundle asks the lead, analysis workers, and report-writer to absorb. This sub-command does **not** mutate task artifacts.
+
+### cost.1 — Resolve target
+
+Accepted target forms:
+
+1. Full task-key: `<project-id>:<task-group>:<task-id>`.
+2. Bare token — a task-id (e.g. `DEV-9184`) **or** a task-group (e.g. `PROD`).
+3. Task root path, e.g. `<projectRoot>/.okstra/tasks/<group>/<task-id>`.
+
+If the user gives a task root path, run `okstra context-cost <absolute-or-user-provided-path>` directly.
+
+If the user gives a full task-key, run:
+
+```bash
+okstra context-cost <task-key> --project-root <projectRoot>
+```
+
+If the user gives a bare token, resolve it via the standard task-key resolution rule in `SKILL.md` (core).
+
+If the user asks generally ("show me the context cost") and does not name a task, apply the core no-task fallback to pick the task to measure.
+
+### cost.2 — Run estimator
+
+Use the CLI output as the source of truth:
+
+```bash
+okstra context-cost <resolved-target> --project-root <projectRoot>
+```
+
+Do not re-count files manually unless the CLI fails and the user explicitly asks for manual fallback.
+
+### cost.3 — Render
+
+Render the CLI JSON into the cost.4 template. Each row's Files / Size / ~Tokens come from the matching output block — `totals` (Task bundle, Current run, Legacy timestamp), `instructionSet`, `leadPhase1`, `analysisWorker`, `reportWriter`, `skillAssets`; their exact field names are in the CLI output (do not re-list them here). Format bytes as raw + rounded KB/MB.
+
+Field-specific notes (these affect interpretation, not just display):
+- Analysis worker uses per-worker fields (`bytesPerWorker`, `estimatedTokensPerWorker`). Use `analysisWorker.estimatedReductionPercent` directly for the worker-input reduction — do **not** recompute it from `bytesPerWorker` when `mode == "analysis-packet-primary"` (that value is already the packet-primary cost).
+- `estimatedTokens*` are a static ranking heuristic (~4 ASCII chars/token, non-ASCII ≈ 1 token/char), never billing numbers — actual cost is the token-usage collector's domain.
+- `skillAssets` = the per-run hot-path instruction assets loaded OUTSIDE the task bundle (skill bodies + agent specs), sorted by size — the prompt-diet target.
+
+### cost.4 — Output template
+
+```markdown
+## okstra Context Cost — <task-key>
+
+| Surface | Files | Size | ~Tokens |
+|---|---:|---:|---:|
+| Task bundle | <N> | <bytes> (<human>) | - |
+| Current run | <N> | <bytes> (<human>) | - |
+| Instruction set | <N> | <bytes> (<human>) | <estimatedTokens> |
+| Lead Phase 1 (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokens> |
+| Analysis worker / worker (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokensPerWorker> |
+| Report writer synthesis | <N> | <bytes> (<human>) | <estimatedTokens> |
+| Skill assets (hot path) | <N> | <bytes> (<human>) | <estimatedTokens> |
+
+- Current run: `<currentRunPath-or-->`
+- Legacy timestamp artifacts: `<N>`
+- Legacy full worker contract: `<legacyFullContractBytesPerWorker>` bytes (`<human>`) per analysis worker
+- Packet estimate: `<estimatedPacketModeBytesPerWorker>` bytes (`<human>`) per analysis worker
+- Estimated worker-input reduction: `<percent>%`
+
+### Reading
+
+<One or two Korean sentences explaining the main bottleneck and the next likely optimization target.>
+```
+
+Interpretation rules:
+
+- `leadPhase1.mode == "active-run-context"` means the compact lead intake file is present and should be treated as the primary lead read surface.
+- `leadPhase1.mode == "legacy-five-file"` means this task was prepared before active-run-context, or the manifest does not reference it.
+- `analysisWorker.mode == "analysis-packet-primary"` means new workers should read `analysis-packet.md` first and open full source inputs only for evidence checks or missing detail.
+- If `analysisWorker.mode == "full-input-contract"` and `estimatedReductionPercent` is low, the next target is worker prompt/input contract slimming.
+- If `reportWriter.bytes` dominates, the next target is a compact `synthesis-input` artifact.
+- If `skillAssets.estimatedTokens` dominates the per-run fixed cost, the next target is slimming the largest `skillAssets.files[]` entries (prompt diet — perf plan v2 P2), e.g. thin-core + lazy-sidecar split.
+- If `legacyTimestampFileCount` is high, recommend current-view/cold-artifact separation or retention cleanup, not destructive deletion by default.

package/runtime/skills/okstra-inspect/facets/error-zip.md

@@ -0,0 +1,41 @@
+# okstra-inspect facet — error-zip
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## error-zip
+
+Trigger phrases: "okstra error-zip", "error zip", "error feedback", "error bundle", "cross-project errors".
+
+Collect and anonymize the okstra run errors (`runs/*/logs/errors-*.jsonl`) of every target project on the machine into the global run-index, then bundle them as a `.zip` (aggregate report + anonymized JSONL). Read-only over every target's `.okstra/`.
+
+### error-zip.1 — Decide the output path (picker)
+
+Read the previous output path from `lastOutputPath` in `~/.okstra/error-zip.json`. If that value exists, present it in a 3-option picker:
+
+1. (previous path exists) reuse `<lastOutputPath>` — recommended, first option.
+   (no previous path) propose the default path `~/okstra-error-feedback-<YYYY-MM-DD>.zip` — recommended.
+2. Enter directly (always the last option).
+
+Read `~/.okstra/error-zip.json` directly with Read (if absent, treat it as no previous path).
+
+### error-zip.2 — Run the renderer
+
+```bash
+okstra error-zip --out <resolved-path>
+```
+
+### error-zip.3 — Report the summary
+
+Parse the stdout JSON and report:
+
+| Field | Source |
+|---|---|
+| Output zip | `outPath` |
+| Total errors | `errorCount` |
+| Logs (runs) | `runCount` |
+| Unreachable runs | `unreachableRuns` |
+| Cluster count | `clusterCount` |
+| Project count | `projectCount` |
+
+- If `unreachableRuns > 0`, surface it (no silent omission).
+- End with the next step: "To fix okstra itself with this zip, build a brief with the error-feedback variant of `/okstra-brief-gen`, then run `okstra-run --task-type error-analysis` in the okstra repo."

package/runtime/skills/okstra-inspect/facets/errors.md

@@ -0,0 +1,69 @@
+# okstra-inspect facet — errors
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## errors
+
+Trigger phrases: "okstra errors", "error report", "error summary", "gather the errors", "clean up failure logs".
+
+Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-observed + worker-reported) into a timestamped markdown report and summarize it. This sub-command renders a **read-derived artifact** (a `.md` file) but never mutates task state (`task-manifest.json`, catalog, timeline).
+
+### errors.1 — Resolve target
+
+Accepted target forms (same as `cost`):
+
+1. Full task-key: `<project-id>:<task-group>:<task-id>`.
+2. Bare token (task-id or task-group) — resolve via the standard task-key resolution rule in `SKILL.md` (core).
+3. Task root path.
+
+If the user asks for an error report without naming a task, apply the core no-task fallback — never list only placeholder forms and ask back.
+
+### errors.2 — Run the renderer
+
+Use the CLI output as the source of truth:
+
+```bash
+okstra error-report <resolved-target> --project-root <projectRoot>
+```
+
+For a task-root path, run `okstra error-report <path>` directly. Do not parse the jsonl files by hand unless the CLI fails and the user explicitly asks for a manual fallback.
+
+### errors.3 — Summarize output
+
+Parse the stdout JSON and report:
+
+| Field | Source |
+|---|---|
+| Report file | `reportPath` (project-root-relative `.md`) |
+| Total errors | `totals.errorCount` |
+| Logs (runs) | `totals.runCount` |
+| By errorType | `totals.byErrorType` (tool-failure / cli-failure / contract-violation) |
+| By source | `totals.bySource` (lead-observed / worker-reported) |
+| By phase | `byPhase[]` |
+| By agent | `byAgent[]` |
+| Parse-skipped lines | `parseSkipped` |
+
+- If `reportPath` is empty AND `totals.errorCount == 0`: report `This task has no recorded error logs.` and do not claim a file was written.
+- Otherwise show the `.md` path and offer to read it.
+- If `parseSkipped > 0`, surface it (do not silently hide malformed lines).
+
+### errors — Output template
+
+```markdown
+## okstra Error Report — <task-key>
+
+- Report: `<reportPath-or-->`
+- Total errors: <N> across <runCount> log(s)
+- By type: <tool-failure: a, cli-failure: b, ...>
+- By source: <lead-observed: x, worker-reported: y>
+
+| Phase | Count |
+|---|---:|
+| implementation | 3 |
+
+| Agent | Count |
+|---|---:|
+| codex-worker | 2 |
+
+<If parseSkipped > 0: "⚠ Parse-skipped lines: <N>">
+```

package/runtime/skills/okstra-inspect/facets/history.md

@@ -0,0 +1,90 @@
+# okstra-inspect facet — history
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## history
+
+Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list tasks", "run again", "resume", "continue".
+
+**Re-run vs Resume — decide upfront.** Re-run = start a fresh run (new run-seq, new manifest, new report) reusing an old run's parameters → `history.3`. Resume = continue an interrupted Claude session for an existing run, no new run-seq → `history.4`. If the user is ambiguous, ask — defaulting to the wrong one either wastes a fresh run-seq or silently abandons a recoverable session.
+
+### history.1 — Read the task catalog
+
+1. Read `.okstra/discovery/task-catalog.json`.
+2. Apply filters from user input (all optional, AND-combined):
+   - `--task-type <type>` → keep entries whose `taskType` matches.
+   - `--latest-run-status <status>` → keep entries whose `latestRunStatus` matches (`completed`, `contract-violated`, `error`).
+   - `--task-group <group>` → keep entries whose `taskGroup` matches.
+3. Sort by `updatedAt` desc.
+4. Page: default `--limit 20`. If truncated, add `... <N> more (pass --limit <N> to see all)`.
+5. Extract: `taskKey`, `taskType`, `currentStatus`, `latestRunStatus`, `latestRunManifestPath`, `updatedAt`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+
+```markdown
+## okstra Task History — <project-id>
+
+| # | Task Key | Type | currentStatus | latestRunStatus | Last Run | Report |
+|---|----------|------|---------------|------------------|----------|--------|
+| 1 | proj:group:id | error-analysis | completed | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.md |
+| 2 | proj:group:id2 | final-verification | todo | error | 2026-04-04 15:30 | -- |
+```
+
+**Catalog absent — fallback.** Do NOT bail out. Manifests on disk are the source of truth.
+
+1. Glob `<projectRoot>/.okstra/tasks/*/*/task-manifest.json`.
+2. For each manifest, read the same fields as above.
+3. Apply the same filters/sort/limit and print the same table, prefixed with: `note: task-catalog.json missing; reconstructed from task manifests on disk.`
+4. Only if the glob yields zero manifests: `There is no okstra execution history yet.`
+
+### history.2 — Run history by task
+
+When a user selects a specific task:
+
+1. Retrieve `historyTimelinePath`, read `runs` array.
+2. Extract: `runTimestamp`, `runDateTimeSegment`, `taskType`, `status`, `runManifestPath`, `reportPath`, `resumeCommandPath`, `relatedTasks`.
+
+```markdown
+## Runs for <task-key>
+
+| # | Timestamp | Type | Status | Report |
+|---|-----------|------|--------|--------|
+| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.md |
+| 2 | 2026-04-04 15:30 | error-analysis | error | -- |
+```
+
+### history.3 — Re-run (NEW run from old parameters)
+
+Builds a fresh run — new run-seq, new manifest, new report — using parameters from a previous `run-manifest-*.json`. Does NOT touch old artifacts; use `history.4` to continue an interrupted session.
+
+1. Pick the source run-manifest: `runManifestPath` from `history.2`, or task's `latestRunManifestPath` from `history.1`. Note: `latestRunManifestPath` is projected from the timeline's latest run, so it is empty when the task has no recorded run yet (timeline absent) — in that case fall back to a `history.2` per-run `runManifestPath`, or ask the user.
+2. Read the manifest and extract required arguments:
+   - `projectId` → `--project-id`
+   - `taskGroup` → `--task-group`
+   - `taskId` → `--task-id`
+   - `taskType` → `--task-type`
+   - `taskBriefPath` → `--task-brief`
+3. Optional arguments (include only when present in source):
+   - `recommendedWorkers` → `--workers` (comma-separated)
+   - `relatedTasks` → `--related-tasks`
+   - model overrides → `--claude-model`, `--codex-model`, `--antigravity-model`
+   - for `taskType: implementation`: `teamContract.executor.provider` → `--executor <claude|codex|antigravity>` when different from `claude`.
+4. **`taskType: implementation` only — resolve `--base-ref`:** base ref is NOT in the run-manifest; it lives in the worktree registry at `~/.okstra/worktrees/registry.json`. If a worktree is already registered, existing branch & base are reused — omit `--base-ref` unless the user explicitly wants a different starting point. If no worktree is registered (cleaned up), `--base-ref` is mandatory — ask the user before running.
+5. Display the assembled command:
+   ```bash
+   ~/.okstra/bin/okstra.sh \
+     --project-id <project-id> \
+     --task-group <task-group> \
+     --task-id <task-id> \
+     --task-type <task-type> \
+     --task-brief <brief-path> \
+     --workers <worker-list>
+   ```
+6. Once the user confirms, execute it.
+
+### history.4 — Resume (continue an interrupted run)
+
+Continues an existing Claude session for an unfinished run. Does NOT create a new run-seq — for a fresh dispatch use `history.3`.
+
+1. Read `latestResumeCommandPath` from `history.1` (or `resumeCommandPath` from a `history.2` timeline entry).
+2. Verify the file exists on disk.
+3. If it exists: `bash <resume-command-path>`.
+4. If the path is empty or the file is missing: `No resume script available for this run. Use 'history.3' to start a fresh run instead.`

package/runtime/skills/okstra-inspect/facets/logs.md

@@ -0,0 +1,89 @@
+# okstra-inspect facet — logs
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## logs
+
+Trigger phrases: "okstra logs", "log status", "log files", "log size", "log cleanup".
+
+Read-only inventory of codex/antigravity wrapper log files written next to each prompt history file (`<prompt>.log`). Reports sizes, ages, totals, and suggests cleanup commands. **Does not delete** — the user runs whichever `find … -delete` line they like.
+
+**Background:** codex/antigravity wrappers (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`) write a sidecar log next to each prompt history file:
+
+```
+.okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
+  <worker>-worker-prompt-<phase>-<seq>.md    <-- prompt (git-tracked)
+  <worker>-worker-prompt-<phase>-<seq>.log   <-- live stdout+stderr mirror
+```
+
+The log is truncated at each dispatch (`: > "$log_path"`) — only the latest run for a given seq is preserved. Different seqs keep separate files. Long-running implementation dispatches can produce multi-MB logs; analysis-phase dispatches are typically smaller.
+
+### logs.1 — Inventory
+
+```bash
+okstra log-report --project-root <projectRoot> --json
+```
+
+Scans `<projectRoot>/.okstra/tasks/**/runs/*/prompts/*.log` and parses task/phase/worker/seq from each path. Returns (sizes are **raw bytes**, mtimes **epoch seconds**):
+- `topLargest[]` — `{path, sizeBytes, mtimeEpoch, taskKey, taskGroup, taskId, phase, worker, seq}`, size desc (widen with `--top <N>`)
+- `perTask[]` — `{taskKey, fileCount, totalBytes, oldestEpoch, newestEpoch}`, total-size desc
+- `totals` — `{fileCount, totalBytes, taskCount}`
+
+If `totals.fileCount` is 0, report `No wrapper log files found under <projectRoot>` and stop.
+
+### logs.2 — Summary tables
+
+Render from the CLI output (format bytes → KB/MB; epoch → `Nd`/`Nh` relative to now):
+
+**Table A — Top largest logs** (from `topLargest`): `| # | Task | Phase | Worker | Seq | Size | Age | Path |`.
+
+**Table B — Per-task totals** (from `perTask`): `| Task Key | Files | Total Size | Oldest | Newest |`.
+
+**Footer:** `Total: <fileCount> files, <totalBytes→MB> across <taskCount> tasks under <PROJECT_ROOT>`.
+
+### logs.3 — Suggested cleanup commands
+
+Emit a fenced bash block the user can copy-paste. Do NOT execute. Each block pairs a dry-run preview (`-print`) with the destructive (`-delete`) command:
+
+```markdown
+## Cleanup options (manual)
+
+# Delete only logs older than 7 days
+find <PROJECT_ROOT>/.okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -print    # dry-run
+find <PROJECT_ROOT>/.okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
+
+# Delete only logs older than 30 days
+find <PROJECT_ROOT>/.okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -print   # dry-run
+find <PROJECT_ROOT>/.okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
+
+# Delete all logs for a specific task-group (e.g. dev-9388)
+find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
+  -type f -name '*.log' -print    # dry-run
+find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
+  -type f -name '*.log' -delete
+
+# Delete all logs for a specific task-id (e.g. dev-9428)
+find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
+  -type f -name '*.log' -print    # dry-run
+find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
+  -type f -name '*.log' -delete
+
+# Delete everything (caution)
+find <PROJECT_ROOT>/.okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -print    # dry-run
+find <PROJECT_ROOT>/.okstra/tasks \
+  -type f -path '*/runs/*/prompts/*.log' -delete
+```
+
+Substitute the literal `<PROJECT_ROOT>` with the resolved absolute path so the commands are directly copy-pasteable.
+
+### logs.4 — Notes for the user
+
+- Logs are truncated on each re-dispatch of the same `seq`, so deleting an in-flight run's log will cause the wrapper to recreate an empty file on the next dispatch — no data loss beyond the current trace.
+- **If a dispatch is currently running, check task status first (load `facets/status.md`)** and avoid deleting logs for tasks in `in-progress` state — you will lose the live trace for the active run.
+- Prompt history files (`.md`) are separate and are NOT touched by these commands — only `.log` sidecars.
+- This sub-command **does not modify any external files itself**, including `.gitignore`. If the project commits `.okstra/`, the user may want to add `.okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore` manually to keep large logs out of git.

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -0,0 +1,96 @@
+# okstra-inspect facet — recap
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## recap
+
+Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
+
+On top of the `.okstra` artifacts accumulated for a single task-id, (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap/recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline.
+
+### recap.1 — Resolve target
+
+The same three forms as `cost` / `errors`: ① full task-key, ② bare token — the standard task-key resolution rule in `SKILL.md` (core), ③ task-root path.
+
+If the user asks for a recap without naming a task (e.g. "summarize this work"), apply the core no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back.
+
+### recap.2 — Assemble the before/after summary
+
+Use the CLI output as the source of truth:
+
+```bash
+okstra recap assemble <resolved-target> --project-root <projectRoot>
+```
+
+Parse the stdout JSON (`{taskKey, runCount, transitions[], latestPhaseStates}`) and narrate the per-run before/after transitions. For each `transitions[]` entry, show `fromPhase → toPhase` (previous run currentPhase → this run currentPhase), `status`, `lastCompletedPhase`, `nextRecommendedPhase`, and `reportPath` in chronological order. If `runCount == 0`, answer only "This task has no recorded runs." and do not claim to have read any file.
+
+For a run that has a `reportPath`, read that final-report to enrich the summary only when the user wants a deeper one (do not read them all automatically).
+
+### recap.3 — Free-form Q&A loop
+
+After the summary output, take the user's free-form questions.
+
+- **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
+- **code mode (opt-in)**: only when the user **explicitly asks** — "look at the code changes / the diff too" — additionally read `git diff` · `git log` from that task's worktree/branch and answer at the code level. Entering recap never by itself switches to code mode.
+
+### recap.4 — Persist each turn
+
+Log one summary and each Q&A answer (append-only):
+
+```bash
+okstra recap record <resolved-target> --project-root <projectRoot> \
+  --kind <summary|qa> --mode <artifact|code> \
+  --question "<question or omit>" --answer "<one or two line summary>" \
+  --citation "<path:line>" --citation "<path:line>"
+```
+
+Put a one-or-two-line summary in `--answer`, not the full answer transcript. If there are multiple citations, repeat `--citation`. Do not silently swallow a recording failure (abnormal exit) — tell the user.
+
+### recap — Output template
+
+```markdown
+## okstra Recap — <task-key>
+
+Before/after summary (runs: <N>):
+
+| # | when | task-type | from → to | status | next |
+|---|---|---|---|---|---|
+| 1 | <ts> | requirements-discovery | (start) → requirements-discovery | done | error-analysis |
+
+<Free-form questions follow. To include code changes, ask "also show me the diff".>
+```
+
+### recap.5 — Agent-authored notes (`notes/`)
+
+Leave something in `notes/` only when, during recap, you produced an artifact **for the okstra task** — verification evidence, a design/decision draft, an analysis note — that may serve as grounding for future runs, and whose content is **neither a rendered report nor a user decision**.
+
+**Route by ownership.** First determine which of the following the thing you are about to write belongs to:
+
+| Content | Lane (path) | Author |
+|---|---|---|
+| final report body | `runs/<type>/reports/*.md` (rendered from `*.data.json`) | okstra renderer — never hand-edit |
+| user's answer to a clarification | `runs/<type>/user-responses/*.md` (`created-by: user`) | user only |
+| finalized ADR | `.okstra/decisions/NNNN-*.md` | promoted / managed |
+| **Agent evidence / design draft / analysis** | **`.okstra/tasks/<group>/<id>/notes/`** | you (the AI) |
+
+If it is **your own grounding/draft** — not a rendered artifact, not a user decision — it goes to `notes/`. Do not hand-stamp the note; write it via the CLI — code guarantees the path/frontmatter/date and prints the argument to pass into the next run:
+
+```bash
+okstra recap note <resolved-target> --project-root <projectRoot> \
+  --kind <verification-evidence|decision-draft|analysis-note> \
+  --slug <short-topic-slug> \
+  --purpose "<one line — what it is and which run/decision it feeds>" \
+  --scope-note "<one line — what it is NOT, e.g. not a user decision on C-00x>" \
+  --body-file <note-body markdown path>
+```
+
+Write the body to the scratchpad as markdown first, then pass it with `--body-file` (if short, an inline `--body "<md>"` also works). The CLI creates `.okstra/tasks/<group>/<id>/notes/<slug>-<YYYY-MM-DD>.md` and returns `notePath` and `clarificationResponseArg` as stdout JSON.
+
+**self-check rules (there is no validator, so you keep them yourself):**
+
+1. **Do not hand-edit a rendered report** (`*.md` / `*.data.json` / `*.html` under `runs/*/reports/`). Because it is regenerated from `data.json`, an edit is overwritten and diverges from the SSOT. Write findings to `notes/` instead.
+2. **Do not author a `user-responses/` file or apply `created-by: user`.** That is the user's decision, and writing it for them forges a decision the user never made. If your evidence supports a particular answer, write that in `notes/` and leave the decision to the user. The one exception is the echo-back confirmation flow of the `okstra-user-response` skill — there the user makes the decision in-session and the CLI is merely a transcription channel, so recording a `created-by: user` sidecar with `write` is legitimate. This exception holds only after the user has explicitly confirmed "correct", and only for verbatim input.
+3. **Do not write to okstra-managed directories** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` is the only agent-owned lane. `recap/recap-log.jsonl` is the exception — write it, but not by hand; only via the `okstra recap record` CLI.
+4. **`notes/` is inert to okstra** — no run reads it automatically. After writing, relay the `clarificationResponseArg` the CLI printed (e.g. `--clarification-response <notePath>`) to the user verbatim, telling them it only takes effect when the next run is executed with that argument.
+
+**Guardrail:** `.okstra/` is gitignored — treat `notes/` as local scratch and never `git add` it. Creating a new note is easy to undo (delete the file), so always prefer it over editing a generated or user-owned file.

package/runtime/skills/okstra-inspect/facets/report.md

@@ -0,0 +1,61 @@
+# okstra-inspect facet — report
+
+Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step 0 preflight, the standard task-key resolution rule (0/1/N), the no-task fallback, and Output Rules — live in the core file and still apply here.
+
+## report
+
+Trigger phrases: "find report", "show report for", "read the okstra report", "continue from report".
+
+### report.1 — Resolve report path
+
+task-key format: `<project-id>:<task-group>:<task-id>`.
+
+**Normalization:** task-key matching is lowercase. Disk segments are slugified (lowercase + non-alphanumeric runs → `-`) per `scripts/okstra_ctl/ids.py:88` (`slugify_task_segment`, the SSOT; `interactive.sh` consumes it via import). Catalog lookup is case-insensitive; file path assembly uses slugified segments.
+
+Lookup methods (in priority order):
+
+A. **`task-catalog.json` (fast):** read `.okstra/discovery/task-catalog.json`, match `taskKey` lowercase. `latestReportPath` is task-type-agnostic "most recent report".
+
+B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / task-id, read `.okstra/tasks/<group-segment>/<task-id-segment>/task-manifest.json`, use `latestReportPath` (task-type-agnostic).
+
+C. **`timeline.json` (specific run):** for a specific date or run, read `.okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
+
+D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:30`. Highest seq is latest. Stage-isolated runs (`implementation`, single-stage `final-verification`) keep their reports one level deeper at `runs/<task-type-segment>/stage-<N>/reports/` — scan those subdirectories too; seq is independent per stage. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+
+### report.2 — Confirm existence
+
+1. Verify `latestReportPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
+2. If present, display the path and ask the user whether to read it.
+3. If absent, check `task-manifest.json` signals:
+   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.routingStatus` not completion-like → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
+   - Any signal indicates completion but the file is missing → `Report file does not exist: <path>`
+
+`workStatus` enum: `todo | in-progress | blocked | done`. `currentStatus`: `completed` / `contract-violated` etc. `"completed"` string does NOT exist in `workStatus` — do not confuse the two.
+
+### report.3 — Read + next-step guidance
+
+Match the depth of read to the request — final reports routinely run 300+ lines / 50K+ tokens, so ingesting the whole file just to answer "just the gist" is wasteful:
+
+- **Summary / verdict intent** ("summary", "just the key points", "conclusion", "did it pass?", "verdict"): do **not** read the whole report first. Read the `final-<task-type-segment>-<NNN>.status` sidecar under `runs/<task-type-segment>/status/` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) for the machine verdict, then read only the report's leading summary block (the first "Overall Verdict" / "Executive" / verdict heading and its body) to quote the gist. Offer to read the full report if the user wants detail.
+- **Full-read intent** ("the whole thing", "read it all", "full body"): ingest the resolved report file.
+
+After reading, surface follow-up options:
+
+1. **Proceed to implementation:** based on the report's "Recommended Next Steps" section.
+2. **Additional verification:** to launch a new okstra run with the same task-key, assemble the command through the `history` facet (load `facets/history.md`) — it offers the full option set (base-ref, workers, render-only) and renders a host-correct invocation.
+3. **Check related tasks:** if the report references related task-keys, fetch their reports too.
+
+### report — Output template
+
+```markdown
+## Report for <task-key>
+
+| Field        | Value                                              |
+| ------------ | -------------------------------------------------- |
+| Status       | `<status>`                                         |
+| Task type    | `<task-type>`                                      |
+| Run seq      | `<NNN>`                                            |
+| Run date     | `<runTimestamp ISO-8601>`                          |
+| Report (rel) | `<relative-path-from-project-root>`                |
+| Report (abs) | `<absolute-path>`                                  |
+```