okstra 0.228.2 → 0.230.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -5
- package/dist/cli-registry.mjs +0 -18
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/lifecycle/doctor.mjs +0 -15
- package/dist/commands/lifecycle/doctor.mjs.map +1 -1
- package/dist/lib/skill-catalog.mjs +4 -4
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +179 -13
- package/docs/architecture.md +13 -14
- package/docs/contributor-change-matrix.md +5 -5
- package/docs/project-structure-overview.md +16 -21
- package/package.json +1 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/interactive.sh +2 -1
- package/runtime/bin/okstra-provider-exec.py +53 -4
- package/runtime/prompts/duties/code-reviewer.json +5 -2
- package/runtime/prompts/launch.template.md +5 -5
- package/runtime/prompts/lead/convergence.md +4 -4
- package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
- package/runtime/prompts/lead/phase-routing.md +1 -1
- package/runtime/prompts/lead/report-writer.md +3 -3
- package/runtime/prompts/lead/team-contract.md +3 -3
- package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
- package/runtime/python/okstra_ctl/cmux.py +4 -2
- package/runtime/python/okstra_ctl/code_review_census.py +194 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
- package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
- package/runtime/python/okstra_ctl/code_review_target.py +79 -25
- package/runtime/python/okstra_ctl/conformance.py +61 -0
- package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
- package/runtime/python/okstra_ctl/correction_round.py +19 -13
- package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
- package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
- package/runtime/python/okstra_ctl/generated_input.py +21 -0
- package/runtime/python/okstra_ctl/ids.py +1 -41
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
- package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
- package/runtime/python/okstra_ctl/locks.py +28 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
- package/runtime/python/okstra_ctl/paths.py +84 -31
- package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
- package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
- package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
- package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
- package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
- package/runtime/python/okstra_ctl/process_group.py +26 -3
- package/runtime/python/okstra_ctl/qa_commands.py +7 -2
- package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
- package/runtime/python/okstra_ctl/recap.py +1 -2
- package/runtime/python/okstra_ctl/render.py +10 -2
- package/runtime/python/okstra_ctl/report_finalize.py +3 -3
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
- package/runtime/python/okstra_ctl/run.py +24 -20
- package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
- package/runtime/python/okstra_ctl/verification_capture.py +291 -0
- package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
- package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
- package/runtime/python/okstra_ctl/verification_generation.py +248 -0
- package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
- package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
- package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
- package/runtime/python/okstra_ctl/verification_target.py +20 -5
- package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
- package/runtime/python/okstra_ctl/wizard/render.py +2 -1
- package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
- package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
- package/runtime/python/okstra_ctl/worker_runner.py +1 -1
- package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
- package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
- package/runtime/skills/okstra-code-review/SKILL.md +84 -48
- package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
- package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
- package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +6 -6
- package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
- package/runtime/skills/okstra-setup/SKILL.md +2 -3
- package/runtime/validators/validate-run.py +118 -52
- package/docs/cli.md +0 -1060
- package/docs/container.md +0 -100
- package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
- package/docs/performance-improvement-plan-v2.md +0 -369
- package/runtime/python/okstra_ctl/container.py +0 -702
- package/runtime/python/okstra_ctl/rollup.py +0 -241
- package/runtime/python/okstra_ctl/usage_report.py +0 -362
- package/runtime/skills/okstra-container-build/SKILL.md +0 -139
- package/runtime/skills/okstra-inspect/SKILL.md +0 -100
- package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
- package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
- package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
- package/runtime/skills/okstra-inspect/facets/history.md +0 -86
- package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
- package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
- package/runtime/skills/okstra-inspect/facets/report.md +0 -57
- package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
- package/runtime/skills/okstra-inspect/facets/status.md +0 -163
- package/runtime/skills/okstra-inspect/facets/time.md +0 -57
- package/runtime/skills/okstra-rollup/SKILL.md +0 -75
- package/runtime/skills/okstra-usage/SKILL.md +0 -71
|
@@ -1,139 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: okstra-container-build
|
|
3
|
-
description: |
|
|
4
|
-
Use to bring up, inspect, or tear down the okstra user-test container runtime for an implementation task — the docker-compose group okstra deploys from a task's worktree so a human can poke at the running build. Trigger words include "okstra container", "okstra container up", "okstra container down", "bring up the container", "spin up the container", "tear down the container", "container status", "user-test environment", "user test environment", "docker compose up please", "spin up this task in a container".
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# OKSTRA Container Build
|
|
8
|
-
|
|
9
|
-
Single entry point for the okstra user-test container runtime. okstra provisions a docker-compose group from an `implementation` task's worktree (the `docker-compose.yml` at the worktree root), and labels every service with `okstra.task-key`, `okstra.project-name`, and `okstra.run-trace`; `status` finds the group by its `okstra.project-name` label. This skill drives that lifecycle. Sub-commands:
|
|
10
|
-
|
|
11
|
-
| Sub-command | What it does |
|
|
12
|
-
|---|---|
|
|
13
|
-
| `up` | Integrate the task's stages into the worktree, run `docker compose up -d`, and poll healthchecks. |
|
|
14
|
-
| `status` | List the task's containers in any state (by `okstra.project-name` label). |
|
|
15
|
-
| `down` | Tear down the task's compose project by name; `--all` covers every task in the project that has a container deploy state. |
|
|
16
|
-
|
|
17
|
-
## Step 0: Preflight (shared)
|
|
18
|
-
|
|
19
|
-
<!-- BEGIN FRAGMENT: host-runtime-selection -->
|
|
20
|
-
Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
|
|
21
|
-
<!-- END FRAGMENT: host-runtime-selection -->
|
|
22
|
-
|
|
23
|
-
Before any sub-command:
|
|
24
|
-
|
|
25
|
-
<!-- BEGIN FRAGMENT: bash-invocation-rule -->
|
|
26
|
-
Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):
|
|
27
|
-
<!-- END FRAGMENT: bash-invocation-rule -->
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
okstra preflight --runtime <host-runtime>
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
On `Okstra preflight: ready`, carry the fixed `Project root` line and pass it as `--project-root <projectRoot>` to every `okstra container` call below. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
|
|
34
|
-
|
|
35
|
-
<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
|
|
36
|
-
If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
|
|
37
|
-
<!-- END FRAGMENT: preflight-outdated-cli -->
|
|
38
|
-
|
|
39
|
-
Docker itself must be installed and running for `up`/`status`/`down` to work. If a sub-command fails with a docker connection error, tell the user to start Docker (Desktop / daemon) and retry — do not try to start docker yourself.
|
|
40
|
-
|
|
41
|
-
<!-- BEGIN FRAGMENT: python-bootstrap-note -->
|
|
42
|
-
Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
|
|
43
|
-
<!-- END FRAGMENT: python-bootstrap-note -->
|
|
44
|
-
|
|
45
|
-
## Step 1: Dispatch by intent
|
|
46
|
-
|
|
47
|
-
Classify the user's request into one sub-command using the sub-command table above.
|
|
48
|
-
|
|
49
|
-
- Clear verbs route directly: "bring up/deploy/up" → `up`; "status" → `status`; "tear down/down" → `down`.
|
|
50
|
-
- If the request is ambiguous (e.g. "take a look at the okstra container"), present a numbered picker. Recommend the 1–2 most likely facets first, and make the **last option always "Enter directly"** so the user can name any facet:
|
|
51
|
-
|
|
52
|
-
```
|
|
53
|
-
What would you like to do?
|
|
54
|
-
1. status — check the running containers (recommended)
|
|
55
|
-
2. up — bring up this task's containers
|
|
56
|
-
3. Enter directly (one of up / status / down)
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
The full facet list is the `Sub-command | What it does` table above — never hide a facet; if the user picks "Enter directly", let them name any row.
|
|
60
|
-
|
|
61
|
-
When the user chains multiple facets in one message (e.g. "bring it up, then show me the status"), execute them sequentially — Step 0 runs once, each sub-command section runs once.
|
|
62
|
-
|
|
63
|
-
Every sub-command needs a **task-key** (`<project-id>:<task-group>:<task-id>`) — the container group is bound to one implementation task's worktree. Resolve it the same way across sub-commands:
|
|
64
|
-
|
|
65
|
-
1. If the user gave a full task-key, use it.
|
|
66
|
-
2. If the user gave only a task-id, run `okstra model-io task-selection-input --project-root <projectRoot> --task-ref <task-id>`. Use the fixed `Selection status`, `Task key`, and numbered `Candidate` lines: one match → use its task key; multiple → list candidates and ask (3-option picker); none → report not found.
|
|
67
|
-
3. `down --all` is the only call that does not need a task-key (see `down`).
|
|
68
|
-
|
|
69
|
-
---
|
|
70
|
-
|
|
71
|
-
## up
|
|
72
|
-
|
|
73
|
-
Brings up the task's container group: integrates the implementation stages into the task worktree, synthesizes the compose env override, runs `docker compose up -d`, and polls healthchecks.
|
|
74
|
-
|
|
75
|
-
**Preconditions** (state them if unmet, do not guess):
|
|
76
|
-
- The task's worktree must be registered in `~/.okstra/worktrees/registry.json`, and the task must have a done `implementation-planning` run. `up` does not check the task type. If `up` refuses because the task-key's worktree is not in the registry → surface the message verbatim; the task has no worktree yet, so the user runs a phase of the task (normally `implementation`) first.
|
|
77
|
-
- The worktree root must contain a `docker-compose.yml`. If `up` refuses because the worktree root has no `docker-compose.yml` → no compose file shipped with this task; surface the message verbatim.
|
|
78
|
-
- Every stage declared in the approved plan's Stage Map must be `done`. `up` integrates the whole task, so a partially-finished task (e.g. only stage 1 of 3 done) is refused rather than deployed as if complete (gate in `stage_targets.py`, shared with whole-task `final-verification`). If `up` fails with `final-verification(whole-task): stage N not done — run implementation --stage N first`, surface that message verbatim and tell the user to finish the named stage via the `implementation` phase with `--stage N`.
|
|
79
|
-
|
|
80
|
-
Run:
|
|
81
|
-
|
|
82
|
-
```bash
|
|
83
|
-
okstra container up --project-root <projectRoot> --task-key <task-key> --text
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
Read the fixed output fields and report the provisioned services. If a service failed its healthcheck, the call surfaces the failing services and the `docker compose ... logs` line to inspect — relay that line; do not invent your own.
|
|
87
|
-
|
|
88
|
-
After a successful `up`, run the `status --text` command below and read its numbered container `ports` fields to tell the user how to reach the running build. Also explain that `okstra container status --project-root <projectRoot> --task-key <task-key>` / `okstra container down --project-root <projectRoot> --task-key <task-key>` manage it from here. For *what to verify* once it is up, point the user to the implementation report's §5.7.9 Manual User Test (Draft) — its steps and expected results are the manual test script for this build.
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## status
|
|
93
|
-
|
|
94
|
-
Reports the task's containers, queried by the `okstra.project-name` label with `docker ps -a` — so stopped and exited containers are listed too. The label query is the source of truth for "is it up".
|
|
95
|
-
|
|
96
|
-
```bash
|
|
97
|
-
okstra container status --project-root <projectRoot> --task-key <task-key> --text
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
Read the fixed `Project name` and numbered `Container` fields and report:
|
|
101
|
-
|
|
102
|
-
| Field | Meaning |
|
|
103
|
-
|---|---|
|
|
104
|
-
| `projectName` | the compose project name (label group) |
|
|
105
|
-
| `containers` | containers found by label, in any state — empty array means no container exists; a non-empty list is up only where `state` is `running` |
|
|
106
|
-
|
|
107
|
-
If `containers` is empty, or no container's `state` is `running`, say the group is not running and offer `up`.
|
|
108
|
-
|
|
109
|
-
To follow a service's live logs, the user runs `docker compose -p <projectName> logs -f <service>` (get `<projectName>` from `status`).
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
## down
|
|
114
|
-
|
|
115
|
-
Tears down the container group by compose project name — no label query. `--all` finds its targets from the tasks that have a `container/deploy-state.json`.
|
|
116
|
-
|
|
117
|
-
Single task:
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
okstra container down --project-root <projectRoot> --task-key <task-key> --text
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Every container group in the project (no task-key needed):
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
okstra container down --project-root <projectRoot> --all --text
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
Read the fixed `Downed` fields and report each torn-down project name. `down` runs `docker compose -p <name> down --remove-orphans` — a compose-native teardown that removes the project's containers and the compose network, but deliberately keeps named volumes (e.g. DB data) by NOT passing `-v`. Confirm with the user before running `--all`, since it takes down every okstra container group in the project at once. A single-task `down` is safe to run directly once the task-key is resolved.
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## Output Rules (shared)
|
|
134
|
-
|
|
135
|
-
- Responses should be concise and written in Korean unless the user requests otherwise.
|
|
136
|
-
- The fixed text fields from each `okstra container` call are the source of truth — do not run raw `docker` commands to second-guess them unless the CLI fails and the user explicitly asks for a manual fallback.
|
|
137
|
-
- Show the resolved `<task-key>` in the heading so the user can confirm disambiguation.
|
|
138
|
-
- Surface failure messages from the CLI verbatim (compose-up failures, missing worktree/compose file) — do not paraphrase the remediation line.
|
|
139
|
-
- Display container/service states as-is from the fixed fields; do not normalize or remap.
|
|
@@ -1,100 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: okstra-inspect
|
|
3
|
-
description: >-
|
|
4
|
-
Inspect okstra tasks and record user-managed status, including direct completion of brief-backed tasks that have never run. The tell is usually a named task id (PROD-1623, dev-9184) without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed; its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report. The recap facet also takes a task-group: which briefs are done / in progress / not started, what is next, each task's latest conclusion. Also builds an anonymized cross-project error zip and audits run health. NOT for starting a run (okstra-run), a group's run/time/error totals (okstra-rollup), schedules (okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# OKSTRA Inspect
|
|
8
|
-
|
|
9
|
-
Also handles tasks that have never run: a status mutation can register an existing brief,
|
|
10
|
-
and direct completion records are available to status, recap, group context, and later runs.
|
|
11
|
-
For an explicit status change, dispatch to status.4 before catalog-only task selection.
|
|
12
|
-
An unregistered brief will not appear in that selection yet.
|
|
13
|
-
|
|
14
|
-
Single read-side entry point for okstra runtime inspection plus the one status mutation that belongs here (`workStatus`) and read-derived artifact rendering (`errors` report). One more write sits underneath: the task-key lookup used by `time-report`, `context-cost`, `error-report`, `recap record`, `recap note`, and `model-io recap-input --task-group` self-heals a finished implementation phase — when a task's current phase is `implementation`, it appends a `done` row to `runs/implementation-planning/consumers.jsonl` for each stage whose carry file is complete but has no settled row, and when every stage of the latest plan has a `done` row and a pass-grade carry it marks the phase completed in `task-manifest.json` (`workflow`, `phaseOutcome.implementation`) and refreshes the catalog entry. `status-input`, `history-input`, `report-input`, and task-scope `recap-input` do not take that path. Each sub-command's full procedure lives in a lazily loaded facet file — after dispatch, Read exactly the one facet you need.
|
|
15
|
-
|
|
16
|
-
| Sub-command | Facet file | What it does |
|
|
17
|
-
|---|---|---|
|
|
18
|
-
| `status` | `facets/status.md` | Task / phase status, blockers, approval state. Also writes `workStatus` on user request. |
|
|
19
|
-
| `history` | `facets/history.md` | List past okstra runs; assemble re-run or resume command. |
|
|
20
|
-
| `report` | `facets/report.md` | Resolve final-report path for a task-key. Optionally read it. |
|
|
21
|
-
| `time` | `facets/time.md` | Per-task-type and per-worker duration breakdown for a task. |
|
|
22
|
-
| `logs` | `facets/logs.md` | Inventory codex/antigravity wrapper `.log` sidecars; emit cleanup commands. |
|
|
23
|
-
| `cost` | `facets/cost.md` | Estimate file/read context cost for a task bundle. |
|
|
24
|
-
| `errors` | `facets/errors.md` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
|
|
25
|
-
| `error-zip` | `facets/error-zip.md` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
|
|
26
|
-
| `run-audit` | `facets/run-audit.md` | Check every run's artifacts against progress invariants; report what went wrong without an error ever being logged. |
|
|
27
|
-
| `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions — or a task-group's start order, per-brief status, and each task's latest conclusion — then answer free-form questions over the `.okstra` artifacts. Appends each summary/Q&A to `recap-log.jsonl` (task `recap/`, group `.recap/`), and writes agent-authored notes to `notes/` for feeding into later runs. |
|
|
28
|
-
|
|
29
|
-
## Step 0: Preflight (shared)
|
|
30
|
-
|
|
31
|
-
<!-- BEGIN FRAGMENT: host-runtime-selection -->
|
|
32
|
-
Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present; otherwise use the registered host ID declared by the current harness. Do not infer the host from worker models, installed executables, or `PATH`. If neither source identifies the host, report that it is unknown instead of substituting another host. Keep the same resolved host when retrying against another project directory.
|
|
33
|
-
<!-- END FRAGMENT: host-runtime-selection -->
|
|
34
|
-
|
|
35
|
-
<!-- BEGIN FRAGMENT: bash-invocation-rule -->
|
|
36
|
-
Run one shell-command tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — literal command tokens keep execution permissions reviewable):
|
|
37
|
-
<!-- END FRAGMENT: bash-invocation-rule -->
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
okstra preflight --runtime <host-runtime>
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
The project check only sees the cwd of the Bash call. When the user is asking about a project that is **not** the cwd (a sibling repo, a monorepo subdir, or a project named explicitly in the request), the bare form can report `Okstra preflight: failed` — a false negative, not a missing setup; do not hard-stop on it.
|
|
44
|
-
|
|
45
|
-
Branch on the fixed first line:
|
|
46
|
-
- `Okstra preflight: ready` → carry `Project root` as a literal string; it is the base for every sub-command step below.
|
|
47
|
-
- `Okstra preflight: failed` → before concluding "no setup", ask whether the user pointed at a specific project directory. If they did, re-run targeting it: `okstra preflight --runtime <host-runtime> --cwd <that-dir>` (`--cwd` is the sanctioned way to target a project — a leading `cd` would break the permission match). Only if this also fails do you show `Reason` and `Recovery`, then stop.
|
|
48
|
-
|
|
49
|
-
<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
|
|
50
|
-
If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
|
|
51
|
-
<!-- END FRAGMENT: preflight-outdated-cli -->
|
|
52
|
-
|
|
53
|
-
Carry the resolved `projectRoot` into the sub-commands: read file artifacts under `<projectRoot>/.okstra/...`, and for sub-command CLIs that accept it (e.g. `recap`, `context-cost`) pass `--cwd <projectRoot>` / `--project-root <projectRoot>` so they target the same project rather than the Bash cwd.
|
|
54
|
-
|
|
55
|
-
<!-- BEGIN FRAGMENT: python-bootstrap-note -->
|
|
56
|
-
Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
|
|
57
|
-
<!-- END FRAGMENT: python-bootstrap-note -->
|
|
58
|
-
|
|
59
|
-
## Step 1: Dispatch by intent
|
|
60
|
-
|
|
61
|
-
Classify the user's request into one sub-command using the trigger table above. If ambiguous (e.g. "show me okstra"), ask which facet — do not silently default. After routing, **Read the chosen row's facet file** (path relative to this skill's base directory) and follow it for the rest of the response. Load exactly one facet per sub-command — never preload the others.
|
|
62
|
-
|
|
63
|
-
When you ask which facet, the option list is **authoritative**: enumerate every sub-command in the dispatch table above as a numbered text list, in table order, each with its one-line description, and let the user pick by number or name. Never present a hand-picked subset — the current host's native option limit is not a reason to drop facets; render the full menu as text in the question body so no facet (e.g. a newly added one) is ever hidden. The table is the single source of truth for this menu; adding a row there (plus its facet file) is all it takes for the facet to appear here.
|
|
64
|
-
|
|
65
|
-
When the user chains multiple facets in one message (e.g. "status, and then time for DEV-9047"), execute them sequentially — Step 0 runs once, then load and run each facet in turn.
|
|
66
|
-
|
|
67
|
-
## Shared rules (referenced by facets)
|
|
68
|
-
|
|
69
|
-
### Standard task-key resolution (0/1/N)
|
|
70
|
-
|
|
71
|
-
Facets that accept a bare token (a task-id like `DEV-9184` **or** a task-group like `PROD`) resolve it through the fixed text projection:
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
okstra model-io task-selection-input --project-root <projectRoot> --task-ref <token>
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
Branch on `Match count` in the projection and use only its repeated `Task`,
|
|
78
|
-
`Updated at`, and `Matched via` lines:
|
|
79
|
-
- **0** → report the task cannot be found. Do not guess.
|
|
80
|
-
- **1** → use that entry's `taskKey`.
|
|
81
|
-
- **N** → list the candidate `taskKey`s (with `updatedAt`, and `_matchedVia` so the user sees which came from a task-id vs a task-group) and ask via a 3-option picker (1–2 recommendations + `Enter directly`), then use the chosen `taskKey`.
|
|
82
|
-
|
|
83
|
-
### No-task fallback
|
|
84
|
-
|
|
85
|
-
When a facet needs a task but the user did not name one:
|
|
86
|
-
|
|
87
|
-
1. Run `okstra model-io task-selection-input --project-root <projectRoot>`.
|
|
88
|
-
2. Branch on `Match count`; if exactly one task exists, use it.
|
|
89
|
-
3. If multiple tasks exist, show the latest 10 by `updatedAt` as real task-keys and ask which one. Do not guess, and do not answer with placeholder forms only.
|
|
90
|
-
|
|
91
|
-
## Output Rules (shared)
|
|
92
|
-
|
|
93
|
-
- Write responses in Korean unless the user requests otherwise. Spell out task ids, phase names, and
|
|
94
|
-
status values the first time each appears — the reader has not seen the report you are summarizing.
|
|
95
|
-
- Use project-relative paths whenever possible.
|
|
96
|
-
- If there is no recent report, display `--`.
|
|
97
|
-
- If a specific task does not exist, explicitly state that the task resolver returned no match.
|
|
98
|
-
- If `awaitingApproval` is true, clearly indicate that the task is awaiting user approval.
|
|
99
|
-
- Display status fields as-is from disk (`completed`, `contract-violated`, `todo`, `error`, empty, ...). Do not normalize or remap.
|
|
100
|
-
- Dates in `YYYY-MM-DD HH:MM` format.
|
|
@@ -1,84 +0,0 @@
|
|
|
1
|
-
# okstra-inspect facet — cost
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## cost
|
|
6
|
-
|
|
7
|
-
Trigger phrases: "okstra context-cost", "context cost", "context-cost", "read cost", "artifact cost", "task bundle cost", "agent read cost".
|
|
8
|
-
|
|
9
|
-
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 itself; a task-key target goes through the lookup that may self-heal a finished implementation phase (see `SKILL.md`).
|
|
10
|
-
|
|
11
|
-
### cost.1 — Resolve target
|
|
12
|
-
|
|
13
|
-
Accepted target forms:
|
|
14
|
-
|
|
15
|
-
1. Full task-key: `<project-id>:<task-group>:<task-id>`.
|
|
16
|
-
2. Bare token — a task-id (e.g. `DEV-9184`) **or** a task-group (e.g. `PROD`).
|
|
17
|
-
3. Task root path, e.g. `<projectRoot>/.okstra/tasks/<group>/<task-id>`.
|
|
18
|
-
|
|
19
|
-
If the user gives a task root path, run `okstra context-cost <absolute-or-user-provided-path>` directly.
|
|
20
|
-
|
|
21
|
-
If the user gives a full task-key, run:
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
okstra context-cost <task-key> --project-root <projectRoot>
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
If the user gives a bare token, resolve it via the standard task-key resolution rule in `SKILL.md` (core).
|
|
28
|
-
|
|
29
|
-
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.
|
|
30
|
-
|
|
31
|
-
### cost.2 — Run estimator
|
|
32
|
-
|
|
33
|
-
Use the CLI output as the source of truth:
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
okstra context-cost <resolved-target> --project-root <projectRoot>
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Do not re-count files manually unless the CLI fails and the user explicitly asks for manual fallback.
|
|
40
|
-
|
|
41
|
-
### cost.3 — Render
|
|
42
|
-
|
|
43
|
-
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.
|
|
44
|
-
|
|
45
|
-
Field-specific notes (these affect interpretation, not just display):
|
|
46
|
-
- 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).
|
|
47
|
-
- `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.
|
|
48
|
-
- `skillAssets` = the per-run hot-path instruction assets loaded OUTSIDE the task bundle (skill bodies + agent specs), sorted by size — the prompt-diet target.
|
|
49
|
-
|
|
50
|
-
### cost.4 — Output template
|
|
51
|
-
|
|
52
|
-
```markdown
|
|
53
|
-
## okstra Context Cost — <task-key>
|
|
54
|
-
|
|
55
|
-
| Surface | Files | Size | ~Tokens |
|
|
56
|
-
|---|---:|---:|---:|
|
|
57
|
-
| Task bundle | <N> | <bytes> (<human>) | - |
|
|
58
|
-
| Current run | <N> | <bytes> (<human>) | - |
|
|
59
|
-
| Instruction set | <N> | <bytes> (<human>) | <estimatedTokens> |
|
|
60
|
-
| Lead Phase 1 (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokens> |
|
|
61
|
-
| Analysis worker / worker (`<mode>`) | <N> | <bytes> (<human>) | <estimatedTokensPerWorker> |
|
|
62
|
-
| Report writer synthesis | <N> | <bytes> (<human>) | <estimatedTokens> |
|
|
63
|
-
| Skill assets (hot path) | <N> | <bytes> (<human>) | <estimatedTokens> |
|
|
64
|
-
|
|
65
|
-
- Current run: `<currentRunPath-or-->`
|
|
66
|
-
- Legacy timestamp artifacts: `<N>`
|
|
67
|
-
- Legacy full worker contract: `<legacyFullContractBytesPerWorker>` bytes (`<human>`) per analysis worker
|
|
68
|
-
- Packet estimate: `<estimatedPacketModeBytesPerWorker>` bytes (`<human>`) per analysis worker
|
|
69
|
-
- Estimated worker-input reduction: `<percent>%`
|
|
70
|
-
|
|
71
|
-
### Reading
|
|
72
|
-
|
|
73
|
-
<One or two Korean sentences explaining the main bottleneck and the next likely optimization target.>
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Interpretation rules:
|
|
77
|
-
|
|
78
|
-
- `leadPhase1.mode == "active-run-context"` means the compact lead intake file is present and should be treated as the primary lead read surface.
|
|
79
|
-
- `leadPhase1.mode == "legacy-five-file"` means this task was prepared before active-run-context, or the manifest does not reference it.
|
|
80
|
-
- `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.
|
|
81
|
-
- If `analysisWorker.mode == "full-input-contract"` and `estimatedReductionPercent` is low, the next target is worker prompt/input contract slimming.
|
|
82
|
-
- If `reportWriter.bytes` dominates, the next target is a compact `synthesis-input` artifact.
|
|
83
|
-
- 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.
|
|
84
|
-
- If `legacyTimestampFileCount` is high, recommend current-view/cold-artifact separation or retention cleanup, not destructive deletion by default.
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
# okstra-inspect facet — error-zip
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## error-zip
|
|
6
|
-
|
|
7
|
-
Trigger phrases: "okstra error-zip", "error zip", "error feedback", "error bundle", "cross-project errors".
|
|
8
|
-
|
|
9
|
-
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/`.
|
|
10
|
-
|
|
11
|
-
### error-zip.1 — Decide the output path (picker)
|
|
12
|
-
|
|
13
|
-
First run the fixed text projection below. If `Previous output path` is not `-`,
|
|
14
|
-
offer it as the recommended first option. Otherwise recommend
|
|
15
|
-
`~/okstra-error-feedback-<YYYY-MM-DD>.zip`. Keep `Enter directly` last.
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
okstra model-io error-zip-input
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
### error-zip.2 — Run the renderer
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
okstra error-zip --out <resolved-path> --text
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
### error-zip.3 — Report the summary
|
|
28
|
-
|
|
29
|
-
Use the fixed text labels and report:
|
|
30
|
-
|
|
31
|
-
| Field | Label |
|
|
32
|
-
|---|---|
|
|
33
|
-
| Output zip | `Output zip` |
|
|
34
|
-
| Total errors | `Total errors` |
|
|
35
|
-
| Logs (runs) | `Run count` |
|
|
36
|
-
| Unreachable runs | `Unreachable runs` |
|
|
37
|
-
| Cluster count | `Cluster count` |
|
|
38
|
-
| Project count | `Project count` |
|
|
39
|
-
|
|
40
|
-
- If `Unreachable runs` > 0, surface it (no silent omission).
|
|
41
|
-
- 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."
|
|
@@ -1,69 +0,0 @@
|
|
|
1
|
-
# okstra-inspect facet — errors
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## errors
|
|
6
|
-
|
|
7
|
-
Trigger phrases: "okstra errors", "error report", "error summary", "gather the errors", "clean up failure logs".
|
|
8
|
-
|
|
9
|
-
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) and never edits task state itself (`task-manifest.json`, catalog, timeline); a task-key target goes through the lookup that may self-heal a finished implementation phase (see `SKILL.md`).
|
|
10
|
-
|
|
11
|
-
### errors.1 — Resolve target
|
|
12
|
-
|
|
13
|
-
Accepted target forms (same as `cost`):
|
|
14
|
-
|
|
15
|
-
1. Full task-key: `<project-id>:<task-group>:<task-id>`.
|
|
16
|
-
2. Bare token (task-id or task-group) — resolve via the standard task-key resolution rule in `SKILL.md` (core).
|
|
17
|
-
3. Task root path.
|
|
18
|
-
|
|
19
|
-
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.
|
|
20
|
-
|
|
21
|
-
### errors.2 — Run the renderer
|
|
22
|
-
|
|
23
|
-
Use the CLI output as the source of truth:
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
okstra error-report <resolved-target> --project-root <projectRoot> --text
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
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.
|
|
30
|
-
|
|
31
|
-
### errors.3 — Summarize output
|
|
32
|
-
|
|
33
|
-
Use the fixed text labels and report:
|
|
34
|
-
|
|
35
|
-
| Field | Label |
|
|
36
|
-
|---|---|
|
|
37
|
-
| Report file | `Report path` (project-root-relative `.md`) |
|
|
38
|
-
| Total errors | `Total errors` |
|
|
39
|
-
| Logs (runs) | `Run count` |
|
|
40
|
-
| By errorType | `Error type <name>` lines (tool-failure / cli-failure / contract-violation) |
|
|
41
|
-
| By source | `Source <name>` lines (lead-observed / worker-reported) |
|
|
42
|
-
| By phase | `Phase <name>` lines |
|
|
43
|
-
| By agent | `Agent <name>` lines |
|
|
44
|
-
| Parse-skipped lines | `Parse skipped` |
|
|
45
|
-
|
|
46
|
-
- If `Report path` is `-` AND `Total errors` is 0: report `This task has no recorded error logs.` and do not claim a file was written.
|
|
47
|
-
- Otherwise show the `.md` path and offer to read it.
|
|
48
|
-
- If `Parse skipped` > 0, surface it (do not silently hide malformed lines).
|
|
49
|
-
|
|
50
|
-
### errors — Output template
|
|
51
|
-
|
|
52
|
-
```markdown
|
|
53
|
-
## okstra Error Report — <task-key>
|
|
54
|
-
|
|
55
|
-
- Report: `<Report path-or-->`
|
|
56
|
-
- Total errors: <N> across <Run count> log(s)
|
|
57
|
-
- By type: <tool-failure: a, cli-failure: b, ...>
|
|
58
|
-
- By source: <lead-observed: x, worker-reported: y>
|
|
59
|
-
|
|
60
|
-
| Phase | Count |
|
|
61
|
-
|---|---:|
|
|
62
|
-
| implementation | 3 |
|
|
63
|
-
|
|
64
|
-
| Agent | Count |
|
|
65
|
-
|---|---:|
|
|
66
|
-
| codex-worker | 2 |
|
|
67
|
-
|
|
68
|
-
<If Parse skipped > 0: "⚠ Parse-skipped lines: <N>">
|
|
69
|
-
```
|
|
@@ -1,86 +0,0 @@
|
|
|
1
|
-
# okstra-inspect facet — history
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## history
|
|
6
|
-
|
|
7
|
-
Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list tasks", "run again", "resume", "continue".
|
|
8
|
-
|
|
9
|
-
**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.
|
|
10
|
-
|
|
11
|
-
### history.1 — Project task history
|
|
12
|
-
|
|
13
|
-
1. Run `okstra model-io history-input --project-root <projectRoot>`.
|
|
14
|
-
2. Apply filters from user input (all optional, AND-combined):
|
|
15
|
-
- `--task-type <type>` → keep entries whose `taskType` matches.
|
|
16
|
-
- `--latest-run-status <status>` → keep entries whose `latestRunStatus` matches (`completed`, `contract-violated`, `error`).
|
|
17
|
-
- `--task-group <group>` → keep entries whose `taskGroup` matches.
|
|
18
|
-
3. Sort by `updatedAt` desc.
|
|
19
|
-
4. Page: default `--limit 20`. If truncated, add `... <N> more (pass --limit <N> to see all)`.
|
|
20
|
-
5. Use the task/status/time/report lines emitted by the fixed text projection.
|
|
21
|
-
|
|
22
|
-
```markdown
|
|
23
|
-
## okstra Task History — <project-id>
|
|
24
|
-
|
|
25
|
-
| # | Task Key | Type | currentStatus | latestRunStatus | Last Run | Report |
|
|
26
|
-
|---|----------|------|---------------|------------------|----------|--------|
|
|
27
|
-
| 1 | proj:group:id | error-analysis | completed | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.data.json |
|
|
28
|
-
| 2 | proj:group:id2 | final-verification | todo | error | 2026-04-04 15:30 | -- |
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
If stdout `taskCount` is zero, answer `There is no okstra execution history yet.`
|
|
32
|
-
|
|
33
|
-
### history.2 — Run history by task
|
|
34
|
-
|
|
35
|
-
When a user selects a specific task:
|
|
36
|
-
|
|
37
|
-
1. Run `okstra model-io history-input --project-root <projectRoot> --task-ref <task-key>`.
|
|
38
|
-
2. Use each numbered run block for chronological status, report, run-manifest, and resume paths.
|
|
39
|
-
`Status` is the run's current status from its own run-manifest (the timeline entry itself only records the prepare-time value). `Report` is `-` for a run that never validated a report — a prepared run that was superseded before it ran — so two runs never share one report in this list.
|
|
40
|
-
|
|
41
|
-
```markdown
|
|
42
|
-
## Runs for <task-key>
|
|
43
|
-
|
|
44
|
-
| # | Timestamp | Type | Status | Report |
|
|
45
|
-
|---|-----------|------|--------|--------|
|
|
46
|
-
| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.data.json |
|
|
47
|
-
| 2 | 2026-04-04 15:30 | error-analysis | error | -- |
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### history.3 — Re-run (NEW run from old parameters)
|
|
51
|
-
|
|
52
|
-
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.
|
|
53
|
-
|
|
54
|
-
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.
|
|
55
|
-
2. Run `okstra model-io rerun-input --run-manifest <runManifestPath>` and use its required argument lines:
|
|
56
|
-
- `projectId` → `--project-id`
|
|
57
|
-
- `taskGroup` → `--task-group`
|
|
58
|
-
- `taskId` → `--task-id`
|
|
59
|
-
- `taskType` → `--task-type`
|
|
60
|
-
- `taskBriefPath` → `--task-brief`
|
|
61
|
-
3. Optional arguments (include only when present in source):
|
|
62
|
-
- each `Role count` line → one `--role-count <role>=<N>` (only roles whose count can change appear)
|
|
63
|
-
- each `Role model` line → one `--role-model <role>=<provider>/<model>`, in the printed order (pass the values verbatim; never rebuild them from a roster)
|
|
64
|
-
- `Related tasks` → `--related-tasks`
|
|
65
|
-
4. **`taskType: implementation` only — resolve `--base-ref`:** do not inspect the worktree registry. Omit `--base-ref` to reuse an existing registration. If the launch reports that no worktree is registered and a base is required, ask the user before retrying.
|
|
66
|
-
5. Display the assembled command:
|
|
67
|
-
```bash
|
|
68
|
-
~/.okstra/bin/okstra.sh \
|
|
69
|
-
--project-id <project-id> \
|
|
70
|
-
--task-group <task-group> \
|
|
71
|
-
--task-id <task-id> \
|
|
72
|
-
--task-type <task-type> \
|
|
73
|
-
--task-brief <brief-path> \
|
|
74
|
-
--role-count <role>=<N> \
|
|
75
|
-
--role-model <role>=<provider>/<model>
|
|
76
|
-
```
|
|
77
|
-
6. Once the user confirms, execute it.
|
|
78
|
-
|
|
79
|
-
### history.4 — Resume (continue an interrupted run)
|
|
80
|
-
|
|
81
|
-
Continues an existing Claude session for an unfinished run. Does NOT create a new run-seq — for a fresh dispatch use `history.3`.
|
|
82
|
-
|
|
83
|
-
1. Use `Latest resume command` from status input or `Resume command` from a history run block.
|
|
84
|
-
2. Verify the file exists on disk.
|
|
85
|
-
3. If it exists: `bash <resume-command-path>`.
|
|
86
|
-
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.`
|
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
# okstra-inspect facet — logs
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## logs
|
|
6
|
-
|
|
7
|
-
Trigger phrases: "okstra logs", "log status", "log files", "log size", "log cleanup".
|
|
8
|
-
|
|
9
|
-
Read-only inventory of the worker 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.
|
|
10
|
-
|
|
11
|
-
**Background:** every CLI-worker dispatch writes a sidecar log next to its prompt history file. All five providers go through the same shared runner (`~/.okstra/lib/python/okstra_ctl/worker_runner.py`), so the file is there whichever provider ran:
|
|
12
|
-
|
|
13
|
-
```
|
|
14
|
-
.okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
|
|
15
|
-
<worker>-worker-prompt-<phase>-<seq>.md <-- prompt (git-tracked)
|
|
16
|
-
<worker>-worker-prompt-<phase>-<seq>.log <-- the run's archive of what the worker did
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
The log is rewritten from scratch at each dispatch — only the latest run for a given seq is preserved. Different seqs keep separate files. It holds one row per tool call and per tool result plus the worker's closing text, and drops thinking; a provider that emits plain text instead of an event stream has its progress copy capped at 5000 lines per run, with `[okstra log-cap] N progress line(s) elided` marking what was dropped. Long-running implementation dispatches can still produce multi-MB logs; analysis-phase dispatches are typically smaller.
|
|
20
|
-
|
|
21
|
-
### logs.1 — Inventory
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
okstra log-report --project-root <projectRoot> --text
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Scans `<projectRoot>/.okstra/tasks/**/runs/*/prompts/*.log` and returns fixed labeled text (sizes are **raw bytes**, mtimes **epoch seconds**):
|
|
28
|
-
- Top-level total labels — `File count`, `Total bytes`, `Task count` (plus `Prompt bytes`, `Transcript bytes`, `Paired file count`)
|
|
29
|
-
- Repeated `## Log` blocks, size desc (widen with `--top <N>`) — `Task key`, `Phase`, `Worker`, `Sequence`, `Size bytes`, `Modified epoch`, `Path`
|
|
30
|
-
- Repeated `## Task total` blocks, total-size desc — `Task key`, `File count`, `Total bytes`, `Oldest epoch`, `Newest epoch`
|
|
31
|
-
|
|
32
|
-
If the top-level `File count` is 0, report `No worker log files found under <projectRoot>` and stop.
|
|
33
|
-
|
|
34
|
-
### logs.2 — Summary tables
|
|
35
|
-
|
|
36
|
-
Render from the CLI output (format bytes → KB/MB; epoch → `Nd`/`Nh` relative to now):
|
|
37
|
-
|
|
38
|
-
**Table A — Top largest logs** (from the `## Log` blocks): `| # | Task | Phase | Worker | Seq | Size | Age | Path |`.
|
|
39
|
-
|
|
40
|
-
**Table B — Per-task totals** (from the `## Task total` blocks): `| Task Key | Files | Total Size | Oldest | Newest |`.
|
|
41
|
-
|
|
42
|
-
**Footer:** `Total: <File count> files, <Total bytes→MB> across <Task count> tasks under <PROJECT_ROOT>`.
|
|
43
|
-
|
|
44
|
-
### logs.3 — Suggested cleanup commands
|
|
45
|
-
|
|
46
|
-
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:
|
|
47
|
-
|
|
48
|
-
```markdown
|
|
49
|
-
## Cleanup options (manual)
|
|
50
|
-
|
|
51
|
-
# Delete only logs older than 7 days
|
|
52
|
-
find <PROJECT_ROOT>/.okstra/tasks \
|
|
53
|
-
-type f -path '*/runs/*/prompts/*.log' -mtime +7 -print # dry-run
|
|
54
|
-
find <PROJECT_ROOT>/.okstra/tasks \
|
|
55
|
-
-type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
|
|
56
|
-
|
|
57
|
-
# Delete only logs older than 30 days
|
|
58
|
-
find <PROJECT_ROOT>/.okstra/tasks \
|
|
59
|
-
-type f -path '*/runs/*/prompts/*.log' -mtime +30 -print # dry-run
|
|
60
|
-
find <PROJECT_ROOT>/.okstra/tasks \
|
|
61
|
-
-type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
|
|
62
|
-
|
|
63
|
-
# Delete all logs for a specific task-group (e.g. dev-9388)
|
|
64
|
-
find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
|
|
65
|
-
-type f -name '*.log' -print # dry-run
|
|
66
|
-
find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
|
|
67
|
-
-type f -name '*.log' -delete
|
|
68
|
-
|
|
69
|
-
# Delete all logs for a specific task-id (e.g. dev-9428)
|
|
70
|
-
find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
|
|
71
|
-
-type f -name '*.log' -print # dry-run
|
|
72
|
-
find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
|
|
73
|
-
-type f -name '*.log' -delete
|
|
74
|
-
|
|
75
|
-
# Delete everything (caution)
|
|
76
|
-
find <PROJECT_ROOT>/.okstra/tasks \
|
|
77
|
-
-type f -path '*/runs/*/prompts/*.log' -print # dry-run
|
|
78
|
-
find <PROJECT_ROOT>/.okstra/tasks \
|
|
79
|
-
-type f -path '*/runs/*/prompts/*.log' -delete
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
Substitute the literal `<PROJECT_ROOT>` with the resolved absolute path so the commands are directly copy-pasteable.
|
|
83
|
-
|
|
84
|
-
### logs.4 — Notes for the user
|
|
85
|
-
|
|
86
|
-
- 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.
|
|
87
|
-
- **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.
|
|
88
|
-
- Prompt history files (`.md`) are separate and are NOT touched by these commands — only `.log` sidecars.
|
|
89
|
-
- 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.
|