okstra 0.186.7 → 0.187.0

package/docs/coding-rules.md

@@ -0,0 +1,295 @@
+# Coding Rules
+
+Rules that hold for every file this repository authors. They exist because both failure modes below
+have already shipped here, and both were invisible to the test suite at the time.
+
+Two of these are enforced mechanically. The rest are review criteria and say so. A rule with no named
+enforcement point is a wish, not a rule.
+
+| Rule | Enforcement |
+|---|---|
+| R1 — No foreign source inside a string literal | `tests-js/coding-rules.test.mjs` (runs in `npm run check`) |
+| R2 — No exception swallowed without a signal | `tests-js/coding-rules.test.mjs` |
+| R3 — No untracked `TODO` / `FIXME` / `HACK` / `XXX` | `tests-js/coding-rules.test.mjs` |
+| G1–G4 — Comment honesty | Code review. Not mechanical |
+
+Scanner: [`tools/coding-rules.mjs`](../tools/coding-rules.mjs). Allowance ledger:
+[`config/coding-rules-baseline.json`](../config/coding-rules-baseline.json).
+
+---
+
+## How the enforcement works: a ratchet, not a wall
+
+At the time these rules landed the repository already violated R1 in 138 places and R2 in 21. R3 stood at zero.
+All three are at zero today, but the ratchet stays — it is what holds them there.
+A rule that turns the whole repository red on day one never gets switched on. So the check is a ratchet.
+
+- `config/coding-rules-baseline.json` records the per-file violation count at landing time.
+- The test fails when a file's count **exceeds** its baseline entry, or when a file with no entry
+  gains a violation. New code is held to zero.
+- The test also fails when a file's count **drops below** its baseline entry and the baseline was not
+  updated. Fixing a violation must tighten the ledger in the same commit. Without this half the
+  ratchet does not ratchet.
+
+After removing violations:
+
+```bash
+node tools/coding-rules.mjs --write-baseline
+```
+
+Commit the regenerated baseline together with the fix. Never regenerate it to make a new violation pass —
+that is the one use of the flag that defeats the rule.
+
+---
+
+## R1 — No foreign source inside a string literal
+
+**A program written in language A must not carry the source of a program in language B inside a string
+literal, heredoc, or template.**
+
+### What it looks like
+
+```js
+// forbidden
+const SCRIPT = `
+import json, sys
+from okstra_project import list_project_tasks
+print(json.dumps(list_project_tasks(sys.argv[1])))
+`;
+await runPythonSnippet({ script: SCRIPT, args: [root] });
+```
+
+```bash
+# forbidden
+python3 - "$PYTHONPATH" "$explicit" <<'PY'
+from okstra_project import resolve_project_root
+print(resolve_project_root(explicit_root=sys.argv[2]))
+PY
+```
+
+### Why it is banned
+
+Embedded source is invisible to every tool that would otherwise catch a defect in it. `tsc` sees a
+string. `ruff` and `mypy` never open it. `pytest` cannot import it. Coverage reports it as one line.
+The defect is not that the code is ugly — it is that **the code is unreachable by the checks the rest
+of the repository relies on**, so a bug there survives a green `npm run check`.
+
+Escapes are the second cost: `\\n` inside a template that becomes `\n` in the emitted program is a
+class of bug that exists only because of the embedding.
+
+### What to do instead
+
+Put the code in a real file with the right extension, so its toolchain sees it, and call it by path or
+module name.
+
+```js
+// allowed — the python lives in scripts/okstra_ctl/task_list_cli.py and is importable, testable, lintable
+await runPythonModule({ module: "okstra_ctl.task_list_cli", args: [root] });
+```
+
+### Detected forms
+
+| Pattern | Example |
+|---|---|
+| `py-heredoc` | `python3 - <<'PY'` |
+| `py-dash-c` | `python3 -c "..."` |
+| `py-arg-c` | `spawn("python3", ["-c", ...])` |
+| `run-py-snippet` | `runPythonSnippet({ script: ... })` |
+| `node-dash-e` | `node -e "..."` |
+
+### Not covered by this rule
+
+- Invoking a real command with arguments — `git rev-parse HEAD`, `python3 -m okstra_ctl.run --flag v`.
+  A module or file reference is not embedded source.
+- Prompt and report templates under `prompts/` and `templates/`. They are read by humans and models,
+  never executed, and are not scanned.
+- A fixture file whose *content* is foreign source, when the fixture is a real file on disk. Inline
+  fixture strings are still violations — write the fixture to a file.
+
+---
+
+## R2 — No exception swallowed without a signal
+
+**A handler whose body neither re-raises, nor records the failure, nor returns a value the caller can
+distinguish from success, must declare itself with an `expected-miss:` tag.**
+
+### What it looks like
+
+```python
+# forbidden — the row vanishes and nothing anywhere knows
+try:
+    entry = json.loads(line)
+except Exception:
+    pass
+```
+
+```js
+// forbidden — same shape, and the comment makes it look considered
+try {
+  entries.push(JSON.parse(line));
+} catch {
+  // Drop the unparseable row.
+}
+```
+
+### Why it is banned
+
+A swallowed exception converts a defect into missing data. The program keeps running, the output is
+wrong, and there is no line anywhere that says so. This is the most direct form of hiding a bug: the
+evidence is destroyed at the moment it is produced.
+
+The comment does not help. A comment is read by whoever opens the file; it is not read by the person
+staring at output that is short by three rows.
+
+### What to do instead
+
+Pick one, in order of preference:
+
+1. Let it propagate. If the caller cannot continue without the value, that is the correct behaviour.
+2. Record it — a counter in the return value, a `stderr` line, an entry in the run error log
+   ([`okstra error-log`](cli.md)). The caller can then report "3 rows skipped".
+3. If the exception genuinely marks a non-error branch, say so with the tag:
+
+```python
+try:
+    (src_root / rel).stat()
+except FileNotFoundError:
+    # expected-miss: 페이로드에 없는 파일 = orphan. 존재하지 않는 것이 정상 분기다.
+    orphans.append(rel)
+```
+
+The tag is what makes the check pass. Its purpose is to force the author to answer one question in
+writing: *is this an error I am ignoring, or a branch that is not an error?* Those are different, and
+a bare comment does not distinguish them.
+
+An `expected-miss:` tag whose text does not name why the absence is normal is an R2 violation that
+happened to get past the scanner. Reviewers reject it under G1.
+
+---
+
+## R3 — No untracked marker
+
+**`TODO`, `FIXME`, `HACK`, `XXX` must carry a task reference or a URL on the same line, or be removed.**
+
+```js
+// forbidden
+// TODO: handle the multi-stage case
+
+// allowed
+// TODO(dev-10174): handle the multi-stage case
+```
+
+A marker without a reference is a defect that has been noticed, recorded where no tracker will find it,
+and left. Either it is worth tracking — then track it — or it is not, and the line should go.
+
+---
+
+## G1–G4 — Comment honesty (review criteria)
+
+These are not mechanically checkable. They are rejection criteria in code review.
+
+### G1 — A comment must not assert a property the code does not enforce
+
+```python
+# forbidden — nothing in this function makes that true
+def load(path: str):
+    # path 는 항상 절대경로다
+    return json.loads(open(path).read())
+```
+
+If the property matters, enforce it (assert, validate, or type it). If it does not matter, delete the
+sentence. A comment that states an unenforced invariant is worse than no comment: the next reader
+writes code that depends on it.
+
+### G2 — A comment must not justify a duplicate instead of removing it
+
+A real example from this repository, since removed. `src/commands/lifecycle/config.mts` carried:
+
+> "Mirror the python resolver order without depending on it … Python remains the source of truth at run
+> time; this is informational."
+
+The comment was accurate and the code was still wrong. Two implementations of one resolution order
+existed, one of them declared non-authoritative, and nothing detected the day they disagreed. The
+correct change is to call the authority, not to annotate the copy — which is what
+[`project_setup_cli.py`](../scripts/okstra_ctl/project_setup_cli.py) now is: one resolution, called
+from every entry point that used to keep its own copy.
+
+If a duplicate is genuinely unavoidable, the comment must name the drift detector — the test that fails
+when the two diverge. No detector, no duplicate.
+
+### G3 — A comment must not stand in for a missing test
+
+"이 경로는 테스트하기 어려워서 수동 확인함" records that a gap exists and closes the discussion. Write the
+test, or record the gap where it will be triaged (R3 applies), but do not settle it in a comment.
+
+### G4 — A comment must not argue that a known defect is acceptable
+
+The pattern: a comment explains why the wrong behaviour is fine here. It is a review conversation
+compressed into a line no reviewer will see again, and it converts a bug into a documented feature
+without anyone deciding to.
+
+Say what the code does and why it is built that way. Do not argue for it. If the defect is acceptable,
+that is a decision, and decisions belong in
+[`<PROJECT_ROOT>/.okstra/decisions/`](architecture/storage-model.md) or an ADR — somewhere with a date
+and an owner.
+
+---
+
+## What a good comment does
+
+The rules above are all prohibitions, so state the positive form once. A comment earns its line when it
+carries something the code cannot:
+
+- **Why this and not the obvious alternative.** [`src/lib/python-helper.mts:99`](../src/lib/python-helper.mts:99)
+  explains that chunks are joined once because `s += chunk` is quadratic for large rendered prompts.
+  The code shows the how; only the comment shows the why.
+- **A constraint that lives outside this file** — an upstream bug with a link, a host contract, a
+  protocol requirement.
+- **A non-obvious consequence of an ordering.** Why this call must precede that one.
+
+Repeating what the next line already says is filler. Delete it.
+
+---
+
+## Applying these to existing code
+
+The baseline is not a target to preserve. Its entries are the work list.
+
+**All three rules are at zero.** R1 started at 138, R2 at 21, R3 at zero and stayed there. The baseline
+file holds no entries; the ratchet now holds every file to zero.
+
+R1 was cleared by moving the code into files, not by loosening the rule. 44 assertion blocks came out of
+`tests-e2e/*.sh` and `validators/lib/*.sh` heredocs into `tests-e2e/checks/` and `validators/checks/`,
+byte-for-byte — each carries a header naming the shell line that calls it. The recurring one-liners
+collapsed into `tests-e2e/lib/jsonq.py`, which replaced the same three lines of JSON-field extraction in
+eight places and, unlike the inline form, exits non-zero on a missing key instead of handing the shell an
+empty string. The rest were one-offs given their own file: a branch name computed through
+`compute_branch_name` rather than assembled by hand, an N+1 fixture, a provider stub's recorder.
+
+Four sites were not embedded code at all — a docstring in `forbidden_actions.py` describing the very
+forms the rule bans, a markdown census fixture, and this file's own examples. Those were reworded or
+split so the source no longer carries the literal token while the runtime value stays the same. The
+scanner reads source text and has no waiver syntax, so quoting a banned form costs a rewording. That is
+the price of a rule with no exceptions, and it is cheap.
+
+Two extractions surfaced a fragility the heredocs had been hiding: `tests-e2e/scenario-13` and `-14` name
+the repo root rather than their own directory, and `validators/lib/*.sh` took its path from whichever
+caller had sourced it. Both produced an unbound variable the moment the code moved out of the string.
+The e2e completion marker caught the first pair; `validators/lib` now resolves `checks/` from its own
+`BASH_SOURCE` so a lib file works whether the whole validator or one contract test sourced it.
+
+**R2 was cleared the same week.** Every handler was one of two things, and the split is the point of the
+rule:
+
+- A real swallow, fixed by recording it. The malformed `LEAD_ASSIGNMENT_JSON` / `WORKER_ASSIGNMENTS_JSON`
+  fallbacks in `render.py` produced a *different* roster with no way for the caller to tell; `memory.mts`
+  dropped truncated index rows so a Memory Book came back short and looked complete; `report.js` swallowed
+  a refused clipboard copy, so the button read as broken. Each now names what it lost.
+- A branch that is not an error, declared with `expected-miss:`. `worker_runner`'s `ProcessLookupError`
+  means the group it was about to kill already exited — that is success. `install.mts` uses `fs.access`
+  as an existence probe, so the throw *is* the answer.
+
+Two handlers turned out to be both, and were split: reading a previous run's team-state
+(`okstra_token_usage/collect.py`) treats a missing file as normal and a corrupt one as worth saying, and
+the session-jsonl reader in `claude.py` does the same with `FileNotFoundError` against every other
+`OSError`. Writing the tag forces that question, which is what the rule is for.

package/docs/container.md

@@ -1,16 +1,16 @@
 # okstra container — CLI Reference
 
-> `okstra container` is a nonlinear tool that launches code from a verified task as a local docker compose group and monitors each container. Because it is a separate entry point from the phase flags in `okstra.sh`, it is documented here rather than in [cli.md](cli.md). See [project-structure-overview](project-structure-overview.md) §4.3 for the module location.
+> `okstra container` is a nonlinear tool that launches code from a verified task as a local docker compose group. Because it is a separate entry point from the phase flags in `okstra.sh`, it is documented here rather than in [cli.md](cli.md). See [project-structure-overview](project-structure-overview.md) §4.3 for the module location.
 
 ---
 
 ## Overview
 
-- **What it is:** Deploys (`up`) the integrated code for a specific task to a task-specific docker compose container group, continuously monitors logs with a watcher for each container, and manages the lifecycle through `status`/`logs`/`stop-watcher`/`down`.
+- **What it is:** Deploys (`up`) the integrated code for a specific task to a task-specific docker compose container group and manages the lifecycle through `status`/`down`.
 - **Orchestration only (does not generate files):** **Reuses** the target project's existing `docker-compose.yml`. It does not generate configuration files; if `docker-compose.yml` is missing, it reports what is missing and stops (the same applies if only a `Dockerfile` exists).
 - **Nonlinear:** This is not a phase in `PHASE_SEQUENCE`. Any task key can be launched regardless of whether it has passed verification.
 - **Single entry point:** The `/okstra-container-build` skill, `bin okstra container`, and Python `okstra_ctl.container` all converge on [`scripts/okstra_ctl/container.py`](../scripts/okstra_ctl/container.py) and its `provision_container_group`.
-- **Source of truth (SSOT) for container existence:** Docker labels. `registry.json` is a secondary index containing only tmux sessions/panes/findings.
+- **Source of truth (SSOT) for container existence:** Docker labels.
 
 ## Prerequisites
 
@@ -21,16 +21,14 @@
 ## Command format
 
 ```
-okstra container <up|status|logs|stop-watcher|down> --project-root <PATH> --task-key <KEY> [--text] [options]
+okstra container <up|status|down> --project-root <PATH> --task-key <KEY> [--text] [options]
 ```
 
 | sub-command | Behavior | Additional options |
 |---|---|---|
-| `up` | Verify stage integration → validate `docker-compose.yml` → compose env override → `docker compose -p <project> up -d` → poll health checks → start a tail/watcher pane for each container | — |
+| `up` | Verify stage integration → validate `docker-compose.yml` → compose env override → `docker compose -p <project> up -d` → poll health checks | — |
 | `status` | Show the live container group status by querying Docker labels | — |
-| `logs` | Report the watcher directory and registered watcher entries; it does not stream Docker container logs | `--service <NAME>` (filters watcher metadata; all registered watchers when omitted) |
-| `stop-watcher` | Stop the watcher panes for the task (containers remain running) | — |
-| `down` | Tear down the container group and stop attached watchers | `--all` |
+| `down` | Tear down the container group | `--all` |
 
 ## Arguments
 
@@ -40,15 +38,10 @@ Absolute path to the target project root. Required for every sub-command.
 ### `--task-key` (effectively required)
 Identifier of the task to deploy, in the form `<project-id>:<task-group>:<task-id>`. The default is an empty string, but actual operations require a valid task key.
 
-### `--service` (`logs` only)
-`--service <NAME>` filters the returned watcher metadata by compose service name. When omitted, all registered watcher entries are returned; an unknown name produces an empty `watchers` object.
-
-The actual `logs` output from `logs_container_group()` contains `watchersDir` and registered watcher entries in `watchers`. It does not run `docker compose logs` and does not stream Docker container logs. Inspect each watcher's `findings_path` and the files beneath `watchersDir` for monitoring results.
-
 `--text` emits command-specific fixed labels for model-facing skills. Without it, the command preserves the full machine JSON bytes and exit codes.
 
 ### `--all` (`down` only)
-Clean up **all** task container groups and watchers within the current project root's `.okstra/` scope. The boundary is limited to the `<project-root>/.okstra/` prefix, so panes belonging to **other projects** in concurrent sessions are never touched. Without `--all`, a single `down` cleans up exactly the panes for the specified task.
+Tear down **all** task container groups discovered under the current project root's `.okstra/` scope. Without `--all`, `down` tears down exactly the group named by `--task-key`.
 
 ## How `up` works
 
@@ -58,7 +51,6 @@ Clean up **all** task container groups and watchers within the current project r
 4. **Compose env override** — In the okstra-owned worktree, layer task overrides over `.env`, write the result to `env.override`, and pass the files in the order `--env-file <worktree .env> --env-file <env.override>` (the latter takes precedence).
 5. **Deploy** — Run `docker compose -p <project-name> ... up -d`. Obtain the service list from `docker compose config --services` (the canonical source).
 6. **Poll health checks** — Use `docker compose ps` to verify that each service has started. Success means reaching healthy for services with a health check, or `running` for services without one.
-7. **Start monitoring** — If `tmux` is available, start a tail pane and watcher agent for each container in the detached session `okstra-container-<slug>`. If it is unavailable, launch only the containers and state "monitoring disabled (tmux unavailable)" in the result.
 
 ### Fixed defaults (not currently exposed as CLI flags)
 
@@ -66,19 +58,9 @@ Clean up **all** task container groups and watchers within the current project r
 |---|---|---|
 | healthcheck timeout | 120 seconds | Stop and report services that failed to start after this limit |
 | healthcheck interval | 3 seconds | Polling interval for `docker compose ps` |
-| watcher scan interval | 5 seconds | Interval for scanning incremental watcher logs |
 
 > These values exist as named arguments to `provision_container_group`, but because they are not exposed as CLI flags, they currently operate as fixed values.
 
-## watcher (two-stage error trigger)
-
-One watcher per container runs in the detached session.
-
-1. **Lightweight scan** — Fetch incremental logs with `docker compose logs --since` and match only regular expressions (`ERROR`/`FATAL`/`Exception`/`Traceback`/abnormal exit codes, and so on). If there are no matches, proceed to the next interval without an LLM call → zero token cost during healthy periods.
-2. **Deep analysis** — Only when a pattern is detected, the watcher AI analyzes the relevant log window and appends its findings to `findings.md`. Identical error signatures are debounced (meaningful numbers such as HTTP statuses and exit codes are preserved, while only noise such as timestamps and pids is normalized). The watcher **only detects and reports**; it does not modify code or configuration.
-
-Watcher/tail panes carry only the dedicated `@okstra_container_run` tag and survive a Claude session ending — no session-end hook reclaims panes any more. Stop them with `stop-watcher` or `down`.
-
 ## Labels and artifacts
 
 Three labels are attached to deployed containers. The label queries used by `status`/`down` use them to locate the group.
@@ -87,16 +69,14 @@ Three labels are attached to deployed containers. The label queries used by `sta
 |---|---|
 | `okstra.task-key` | `<project-id>:<task-group>:<task-id>` |
 | `okstra.project-name` | compose project name `okstra-<proj>-<group>-<task>` |
-| `okstra.run-trace` | container session name (`okstra-container-<slug>`) |
+| `okstra.run-trace` | run-trace slug (`okstra-container-<slug>`) |
 
 All okstra artifacts are stored under `<project-root>/.okstra/tasks/<group>/<task-id>/container/` (the original project files remain unchanged):
 
 ```
 container/
 ├── env.override            # per-task variables layered over the project .env
-├── registry.json           # tmux sessions/panes/findings (flock-guarded secondary index)
-├── deploy-state.json       # compose project name, running containers, labels
-└── watchers/<service>-findings.md   # per-watcher error analysis log
+└── deploy-state.json       # compose project name, running containers, labels
 ```
 
 ## Exit behavior/output
@@ -106,18 +86,12 @@ Each sub-command returns exit code 0 on success. `--text` writes its command-spe
 ## Usage examples
 
 ```bash
-# Deploy and start monitoring
+# Deploy
 okstra container up --project-root /path/to/proj --task-key proj:auth:login-fix --text
 
 # Status
 okstra container status --project-root /path/to/proj --task-key proj:auth:login-fix
 
-# Filter watcher metadata for one service
-okstra container logs --project-root /path/to/proj --task-key proj:auth:login-fix --service api
-
-# Stop only the watcher (keep containers running)
-okstra container stop-watcher --project-root /path/to/proj --task-key proj:auth:login-fix
-
 # Tear down the group
 okstra container down --project-root /path/to/proj --task-key proj:auth:login-fix
 

package/docs/contributor-change-matrix.md

@@ -7,7 +7,7 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
 | Add Node subcommand | `src/cli-registry.mts`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
 | Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
-| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.py` |
+| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/cli-wrapper-contract.test.mjs`, `tests/test_okstra_manager_*.py` |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |

package/docs/for-ai/skills/okstra-code-review.md

@@ -7,7 +7,6 @@
 - Review calibration: [`skills/okstra-code-review/references/review-calibration.md`](../../../skills/okstra-code-review/references/review-calibration.md)
 - Target core (CLI): [`scripts/okstra_ctl/code_review_target.py`](../../../scripts/okstra_ctl/code_review_target.py)
 - Review path core: [`scripts/okstra_ctl/code_review_paths.py`](../../../scripts/okstra_ctl/code_review_paths.py)
-- Node wrapper: [`src/commands/inspect/code-review.mjs`](../../../src/commands/inspect/code-review.mjs)
 - Rules the review applies: [`prompts/coding-preflight/`](../../../prompts/coding-preflight/)
 
 ## Purpose

package/docs/for-ai/skills/okstra-container-build.md

@@ -3,24 +3,21 @@
 ## Source
 
 - Skill source: [`skills/okstra-container-build/SKILL.md`](../../../skills/okstra-container-build/SKILL.md)
-- container CLI wrapper: [`src/commands/inspect/container.mjs`](../../../src/commands/inspect/container.mjs)
+- container CLI: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
 - container runtime: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
-- container registry: [`scripts/okstra_ctl/container_registry.py`](../../../scripts/okstra_ctl/container_registry.py)
 - stage integration gate: [`scripts/okstra_ctl/stage_targets.py`](../../../scripts/okstra_ctl/stage_targets.py)
 
 ## Purpose
 
-`okstra-container-build` manages a user-test container group using the `docker-compose.yml` in an implementation task worktree. okstra labels the compose group with the task/run trace and observes logs/status through a tmux watcher pane.
+`okstra-container-build` manages a user-test container group using the `docker-compose.yml` in an implementation task worktree. okstra labels the compose group with the task/run trace so later sub-commands can find it.
 
 ## sub-command
 
 | Sub-command | Role | side effect |
 |---|---|---|
-| `up` | Integrate the implementation stages into the task worktree, then `docker compose up -d`, poll healthchecks, attach the watcher pane | create/start containers, create watcher pane |
-| `status` | Check running containers (by label query) plus watcher metadata | read |
-| `logs` | Point at the watcher findings dir and watcher entries | read |
-| `stop-watcher` | Reap the watcher/tail tmux panes only | keep containers, remove panes |
-| `down` | Remove the container group by label query, reap orphan watcher panes | stop/remove containers |
+| `up` | Integrate the implementation stages into the task worktree, then `docker compose up -d`, poll healthchecks | create/start containers |
+| `status` | Check running containers (by label query) | read |
+| `down` | Remove the container group by label query | stop/remove containers |
 
 ## Preflight
 
@@ -55,8 +52,6 @@ Clear verbs:
 
 - "bring up/deploy", "up": `up`
 - "status": `status`
-- "logs": `logs`
-- "stop watcher", "stop-watcher": `stop-watcher`
 - "tear down", "down": `down`
 
 If ambiguous, show the full facet list and offer an Enter directly option. When multiple facets are in one message, run Step 0 once and execute the sub-commands sequentially.
@@ -82,7 +77,7 @@ Handling failure messages:
 - `final-verification(whole-task): stage N not done`: tell the user to finish that stage via implementation.
 - healthcheck failure: relay the failing service and the `docker compose ... logs` line the CLI provides, verbatim.
 
-On success, read the fixed `Service` and `Watcher` rows, then run the `status --text` command below and read its numbered container `ports` fields. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
+On success, read the fixed `Service` rows, then run the `status --text` command below and read its numbered container `ports` fields. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
 
 ## status
 
@@ -96,35 +91,8 @@ Fixed fields:
 
 - `projectName`: compose project name
 - `containers`: running containers found by run-trace label
-- `watchers`: watcher metadata from the registry
 
-The `containers` label query is authoritative for whether it is alive. The watcher registry can lag. If `containers` is empty, say the group is not running and offer `up`.
-
-## logs
-
-Run:
-
-```bash
-okstra container logs --project-root <projectRoot> --task-key <task-key> --text
-```
-
-service scope:
-
-```bash
-okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service> --text
-```
-
-Show the fixed `Watchers dir` and numbered `Watchers` rows. The live stream is in the tmux watcher pane, not a file. If raw compose logs are needed, get `Project name` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
-
-## stop-watcher
-
-Run:
-
-```bash
-okstra container stop-watcher --project-root <projectRoot> --task-key <task-key> --text
-```
-
-Remove only the watcher/tail panes and keep the containers. Summarize the fixed `Reaped panes` and `Note` rows. If the user actually intends to bring the containers down, route to `down`.
+The label query is authoritative for whether it is alive. If `containers` is empty, say the group is not running and offer `up`. To follow a service's live logs, get `Project name` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
 
 ## down
 
@@ -142,7 +110,7 @@ okstra container down --project-root <projectRoot> --all --text
 
 A single-task down is fine to run after resolving the task-key. `--all` takes down every okstra container group in the project, so confirm with the user before running it.
 
-Report the fixed `Downed` and `Orphan panes reaped` rows. Show each project name and the reaped panes.
+Report the fixed `Downed` rows. Show each torn-down project name.
 
 ## Output rules
 
@@ -157,6 +125,5 @@ Report the fixed `Downed` and `Orphan panes reaped` rows. Show each project name
 - Trying to start the Docker daemon yourself.
 - Guessing the cause of an `up` failure and editing the compose file.
 - Dressing up a partial-stage task as deployable.
-- Judging a container as alive from the watcher registry alone.
 - Running `down --all` without user confirmation.
 - Overriding the CLI result arbitrarily with a raw docker query.

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

@@ -5,10 +5,10 @@
 - Skill source: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
 - Facet bodies: `skills/okstra-inspect/facets/<sub-command>.md` — the skill is a thin core (preflight + dispatch + shared rules); each sub-command's full procedure is a lazily loaded facet file, guarded by `tests/contract/test_okstra_inspect_facets.py`
 - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- context-cost CLI: `src/commands/inspect/context-cost.mjs`
-- time-report CLI: `src/commands/inspect/time-report.mjs`
-- log-report CLI: `src/commands/inspect/log-report.mjs`
-- error-report CLI: `src/commands/inspect/error-report.mjs`
+- context-cost CLI: `scripts/okstra_ctl/context_cost.py`
+- time-report CLI: `scripts/okstra_ctl/time_report.py`
+- log-report CLI: `scripts/okstra_ctl/log_report.py`
+- error-report CLI: `scripts/okstra_ctl/error_report.py`
 - container is a separate skill: [`okstra-container-build.md`](okstra-container-build.md)
 
 ## Purpose

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

@@ -1,6 +1,6 @@
 # okstra-manager
 
-Use this to bundle okstra tasks across multiple projects into a single manager-owned context. The authoritative contract is [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md); the CLI implementation is [`src/commands/manager.mjs`](../../../src/commands/manager.mjs) and [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py).
+Use this to bundle okstra tasks across multiple projects into a single manager-owned context. The authoritative contract is [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md); the CLI implementation is [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py).
 
 ## When to Use
 
@@ -60,7 +60,7 @@ 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`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
+- `Backend`: always `subagent-child-lead`
 - `Worker dispatch backend`: always `subagent` in v1
 - `Project root`: the child project root
 - `Context path`: the manager child context markdown

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

@@ -4,7 +4,6 @@
 
 - Skill source: [`skills/okstra-rollup/SKILL.md`](../../../skills/okstra-rollup/SKILL.md)
 - aggregation core (CLI): [`scripts/okstra_ctl/rollup.py`](../../../scripts/okstra_ctl/rollup.py)
-- Node wrapper: [`src/commands/inspect/rollup.mjs`](../../../src/commands/inspect/rollup.mjs)
 - reused single-task aggregators: [`scripts/okstra_ctl/time_report.py`](../../../scripts/okstra_ctl/time_report.py), [`scripts/okstra_ctl/error_log_core.py`](../../../scripts/okstra_ctl/error_log_core.py)
 - catalog enumeration helper: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py) (`list_project_tasks`)
 - unit tests: [`tests/inspect/test_okstra_rollup.py`](../../../tests/inspect/test_okstra_rollup.py)

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

@@ -213,7 +213,7 @@ Read the scope and path from the persist action of `okstra wizard outcome`, not
 
 ## Okstra lead takeover
 
-After render-bundle, read `<INSTRUCTION_SET_PATH>/lead-execution-prompt.md` verbatim and proceed from Phase 1 in that prompt's order. Before any in-run approval or clarification question, follow the lead contract "User confirmation before an approval blocker": read cited plan items, worker findings, and files, then ask in the user's language with each option's outcome.
+After render-bundle, read the run manifest's `resources.leadExecutionPromptPath` (project-relative, under `runs/<task-type>/prompts/`), read that file verbatim, and proceed from Phase 1 in that prompt's order. Before any in-run approval or clarification question, follow the lead contract "User confirmation before an approval blocker": read cited plan items, worker findings, and files, then ask in the user's language with each option's outcome.
 
 Inform the user on one line.
 
@@ -221,7 +221,7 @@ Inform the user on one line.
 Took over as Okstra lead (`<host-runtime>`) for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
 ```
 
-For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements. When the run is over, close with the user's next action — one command they can run now. A prohibition is not a next action. After `implementation-planning`: open approval blockers → `/okstra-user-response`; a recorded `accept-risk` / `select` / `answer` is not an open blocker; awaiting approval → `/okstra-run` → `implementation` or `--approve` (do not start another planning run); `validate-run` failed → one-line cause then `/okstra-run` or `/okstra-inspect recap`; pointer `ready` → `/okstra-run` for that phase.
+For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements. When the run is over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take it from the `report-finalize` result: `nextCommand` (`{command, note}`) is the table below already applied, and `nextRecommendedPhase` (`phase`, `status`, `rationale`) is what it was applied to — do not re-derive either from the report, and treat `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. After `implementation-planning`: open approval blockers → `/okstra-user-response`; a recorded `accept-risk` / `select` / `answer` is not an open blocker; no open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type: pointer `ready` → `/okstra-run` for that phase; `validate-run` failed → one-line cause then `/okstra-run`; otherwise `/okstra-inspect status`.
 
 ## implementation unattended chaining (chain-stages)
 
@@ -230,7 +230,7 @@ When `task-type == implementation` and the render-args `chain-stages` CSV has 2
 1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
 3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary. A `status:"failed"` row in place of `done` means the stage ended `FAIL` — stop the queue per the FAIL branch below.
-4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
+4. One-line report at each stage start/finish: `stage N start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion.
 

package/docs/for-ai/skills/okstra-user-response.md

@@ -4,7 +4,6 @@
 
 - Skill source: [`skills/okstra-user-response/SKILL.md`](../../../skills/okstra-user-response/SKILL.md)
 - Response core: [`scripts/okstra_ctl/user_response.py`](../../../scripts/okstra_ctl/user_response.py)
-- Node wrapper: [`src/commands/inspect/user-response.mts`](../../../src/commands/inspect/user-response.mts)
 
 ## Purpose
 

package/docs/performance-improvement-plan-v2.md

@@ -82,7 +82,7 @@ Therefore, "P1 convergence improvement" in this document does not change the tas
 
 `prepare_task_bundle()` writes the instruction set and manifest-related files sequentially.
 
-- Instruction set: `analysis-profile.md`, `analysis-material.md`, `task-brief.md`, optional carry-in/directive, `reference-expectations.md`, `final-report-template.md`, canonical `lead-execution-prompt.md`, and the prompt snapshot.
+- Instruction set: `analysis-profile.md`, `analysis-material.md`, `task-brief.md`, optional carry-in/directive, `reference-expectations.md`, `final-report-template.md`. The lead prompt is written separately, to `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md`.
 - Manifest/discovery: `team-state`, `task-manifest`, `task-index`, `run-manifest`, `timeline`, task catalog, and latest task.
 
 This serial rendering has room for improvement, but it is generally cheaper than external worker dispatch. Render parallelization is therefore not the first priority.