okstra 0.229.0 → 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.
Files changed (119) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +105 -16
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +11 -18
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/prompts/launch.template.md +5 -5
  16. package/runtime/prompts/lead/convergence.md +4 -4
  17. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  18. package/runtime/prompts/lead/phase-routing.md +1 -1
  19. package/runtime/prompts/lead/report-writer.md +3 -3
  20. package/runtime/prompts/lead/team-contract.md +3 -3
  21. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  22. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  23. package/runtime/python/okstra_ctl/cmux.py +4 -2
  24. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  26. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  27. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  28. package/runtime/python/okstra_ctl/conformance.py +30 -0
  29. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  30. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  31. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  33. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  34. package/runtime/python/okstra_ctl/ids.py +1 -41
  35. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  36. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  37. package/runtime/python/okstra_ctl/locks.py +28 -1
  38. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  39. package/runtime/python/okstra_ctl/paths.py +75 -33
  40. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  41. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  42. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  43. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  44. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  45. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  46. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  48. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  49. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  50. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  53. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  54. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  55. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  63. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  64. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  66. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  67. package/runtime/python/okstra_ctl/process_group.py +26 -3
  68. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  69. package/runtime/python/okstra_ctl/recap.py +1 -2
  70. package/runtime/python/okstra_ctl/render.py +10 -2
  71. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  72. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  73. package/runtime/python/okstra_ctl/run.py +24 -20
  74. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  75. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  76. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  77. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  78. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  79. package/runtime/python/okstra_ctl/verification_generation.py +22 -12
  80. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  81. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  82. package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
  83. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  84. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  85. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  86. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  87. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  88. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  89. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  90. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  91. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  92. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  93. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  94. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  95. package/runtime/skills/okstra-run/SKILL.md +6 -6
  96. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  97. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  98. package/runtime/validators/validate-run.py +110 -19
  99. package/docs/cli.md +0 -1060
  100. package/docs/container.md +0 -100
  101. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  102. package/docs/performance-improvement-plan-v2.md +0 -369
  103. package/runtime/python/okstra_ctl/container.py +0 -702
  104. package/runtime/python/okstra_ctl/rollup.py +0 -241
  105. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  106. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  107. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  108. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  109. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  110. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  111. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  112. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  113. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  114. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  115. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  116. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  117. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  118. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  119. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -1,167 +0,0 @@
1
- # okstra-inspect facet — recap
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
- ## recap
6
-
7
- Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
8
-
9
- On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs the `recap-log.jsonl` append, the `notes/` note authoring (recap.5), and the group-context reconciliation that note triggers (recap.6); it never edits `task-manifest.json` / catalog / timeline itself (`recap record` / `recap note` with a task-key target, and `recap-input --task-group`, go through the lookup that may self-heal a finished implementation phase — see `SKILL.md`), and it touches `group-context.md` only in the authored sections above the `<!-- okstra:task-memory:begin -->` marker.
10
-
11
- ### recap.1 — Resolve target
12
-
13
- Two scopes. Decide the scope before resolving anything:
14
-
15
- - **Task scope** — the same three forms as `cost` / `errors`: ① full task-key, ② bare token — the standard task-key resolution rule in `SKILL.md` (core), ③ task-root path.
16
- - **Group scope** — the user names a task-group ("recap the cache group", "how far is the `cache` group", "group progress") or the bare token resolves with every match `Matched via: taskGroup`. Do **not** drop to the N-match picker in that case; carry the group name as `<task-group>` and follow recap.2g / recap.4g below. A group-scope request still takes the one-task path when the user picks a single task from it.
17
-
18
- If the user asks for a recap without naming a task or a group (e.g. "summarize this work"), apply the core no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back.
19
-
20
- ### recap.2 — Assemble the before/after summary
21
-
22
- When `Direct work record` is present, read that work record and report its summary, evidence,
23
- limitations, and current `Work status`, including when `Run count` is zero. Direct work records
24
- are JSON work artifacts, not final reports; do not send them to `render-final-report`. In group
25
- output, `Memory source: direct` identifies these records even when `Memory run` is empty.
26
-
27
- Use the CLI output as the source of truth:
28
-
29
- ```bash
30
- okstra model-io recap-input --project-root <projectRoot> --task-ref <resolved-target>
31
- ```
32
-
33
- Read the fixed-text `Run count` and repeated `Transition` blocks. Narrate each block's `From phase → To phase`, `Status`, `Last completed phase`, `Next phase`, and `Report` in the emitted chronological order. `Status`, `Last completed phase`, and `Next phase` are each run's end state from its own run-manifest, so a `prepared` transition is a run that was prepared and never ran, and it carries no `Report`. If `Run count: 0` and `Direct work record` is absent, report that the task has no recorded runs alongside its current work status.
34
-
35
- `Next phase` is already a fixed scalar projection. Narrate it when non-empty, and otherwise use `Next phase status`: `pending` means that run did not settle the route, `blocked` means it stopped on something outside the run, and `terminal` means the lifecycle ended there.
36
-
37
- For a transition that has a `Report`, run `okstra render-final-report <Report>` and read the rendered Markdown only when the user wants a deeper summary. Do not open the report data JSON directly and do not render every report automatically.
38
-
39
- ### recap.2g — Assemble the group status (group scope)
40
-
41
- ```bash
42
- okstra model-io recap-input --project-root <projectRoot> --task-group <task-group>
43
- ```
44
-
45
- The projection joins three sources and is the only place to read them from — do not re-derive the queue from the brief directory, the catalog, or `group-context.md` by hand:
46
-
47
- - the group's briefs give the start order (brief ordinal) and the `waits for` edges;
48
- - the catalog / each `task-manifest.json` gives the real `Status` (`done` / `in progress` / `not started`), `Progress` (`<phase> (<state>)`), run count, next phase, and report path;
49
- - the group document's Task Memory gives each recorded task's `Headline`, `Decision N`, `Watch out N`, `Follow-up N`. A task with `Memory run: -` finished before group memory existed — its conclusion lives only in its `Report`.
50
-
51
- Read the head lines (`Brief count`, `Task count`, `Next in group`), then the repeated `Queue entry` blocks in order, then the repeated `Task` blocks. Narrate the group as: how many briefs, how many started, which are done, which is next (`Next in group` — `-` means every brief has started), and any `Waits for` that names a ticket not yet done. `Human sections: absent` means the group has no authored `group-context.md` context yet (only okstra's memory region) — say so once when the user asks why the group exists; do not offer to write it here (that is `okstra group-context init` via okstra-brief-gen).
52
-
53
- Numbers beyond run count (CPU, wall clock, error totals) are okstra-rollup's; if the user asks for them, point to `/okstra-rollup --task-group <task-group>` instead of summing anything here.
54
-
55
- ### recap.3 — Free-form Q&A loop
56
-
57
- After the summary output, take the user's free-form questions.
58
-
59
- - **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report; in group scope also `.okstra/briefs/<task-group>/group-context.md` and each member task's artifacts). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
60
- - **code mode (opt-in)**: only when the user **explicitly asks** — "look at the code changes / the diff too" — additionally read `git diff` · `git log` from that task's worktree/branch and answer at the code level. Entering recap never by itself switches to code mode.
61
-
62
- ### recap.4 — Persist each turn
63
-
64
- Log one summary and each Q&A answer (append-only):
65
-
66
- ```bash
67
- okstra recap record <resolved-target> --project-root <projectRoot> \
68
- --kind <summary|qa> --mode <artifact|code> \
69
- --question "<question or omit>" --answer "<one or two line summary>" \
70
- --citation "<path:line>" --citation "<path:line>"
71
- ```
72
-
73
- Put a one-or-two-line summary in `--answer`, not the full answer transcript. If there are multiple citations, repeat `--citation`. Do not silently swallow a recording failure (abnormal exit) — tell the user.
74
-
75
- ### recap.4g — Persist each turn (group scope)
76
-
77
- Same flags, but the group replaces the target and the log lands at `.okstra/tasks/<task-group>/.recap/recap-log.jsonl`:
78
-
79
- ```bash
80
- okstra recap record --task-group <task-group> --project-root <projectRoot> \
81
- --kind <summary|qa> --mode <artifact|code> \
82
- --question "<question or omit>" --answer "<one or two line summary>" \
83
- --citation "<path:line>"
84
- ```
85
-
86
- `recap note` has no group form — a note belongs to the task whose next run will carry it, so write it against that task-key.
87
-
88
- ### recap — Output template
89
-
90
- ```markdown
91
- ## okstra Recap — <task-key>
92
-
93
- Before/after summary (runs: <N>):
94
-
95
- | # | when | task-type | from → to | status | next |
96
- |---|---|---|---|---|---|
97
- | 1 | <ts> | requirements-discovery | (start) → requirements-discovery | done | error-analysis |
98
-
99
- <Free-form questions follow. To include code changes, ask "also show me the diff".>
100
- ```
101
-
102
- Group scope:
103
-
104
- ```markdown
105
- ## okstra Recap — task-group <task-group> (briefs: <Brief count>, started: <Task count>)
106
-
107
- | # | task | status | progress | waits for | latest conclusion |
108
- |---|---|---|---|---|---|
109
- | 1 | dev-10626-1-… | done | release-handoff (completed) | — | <Headline, or "report only" when Memory run is -> |
110
- | 2 | dev-10627-2-… | in progress | implementation-option-selection (prepared) | DEV-10642 | <Headline> |
111
- | 3 | dev-10628-3-… | not started | — | — | — |
112
-
113
- Next in group: <Next in group or "every brief has started">
114
-
115
- <Free-form questions follow.>
116
- ```
117
-
118
- ### recap.5 — Agent-authored notes (`notes/`)
119
-
120
- Leave something in `notes/` only when, during recap, you produced an artifact **for the okstra task** — verification evidence, a design/decision draft, an analysis note — that may serve as grounding for future runs, and whose content is **neither a rendered report nor a user decision**.
121
-
122
- **Route by ownership.** First determine which of the following the thing you are about to write belongs to:
123
-
124
- | Content | Lane (path) | Author |
125
- |---|---|---|
126
- | final report body | `runs/<type>/reports/*.md` (rendered from `*.data.json`) | okstra renderer — never hand-edit |
127
- | user's answer to a clarification | `runs/<type>/user-responses/*.md` (`created-by: user`) | user only |
128
- | finalized ADR | `.okstra/decisions/NNNN-*.md` | promoted / managed |
129
- | **Agent evidence / design draft / analysis** | **`.okstra/tasks/<group>/<id>/notes/`** | you (the AI) |
130
-
131
- If it is **your own grounding/draft** — not a rendered artifact, not a user decision — it goes to `notes/`. Do not hand-stamp the note; write it via the CLI — code guarantees the path/frontmatter/date and prints the argument to pass into the next run:
132
-
133
- ```bash
134
- okstra recap note <resolved-target> --project-root <projectRoot> \
135
- --kind <verification-evidence|decision-draft|analysis-note> \
136
- --slug <short-topic-slug> \
137
- --purpose "<one line — what it is and which run/decision it feeds>" \
138
- --scope-note "<one line — what it is NOT, e.g. not a user decision on C-00x>" \
139
- --body-file <note-body markdown path>
140
- ```
141
-
142
- Write the body to the scratchpad as markdown first, then pass it with `--body-file` (if short, an inline `--body "<md>"` also works). The CLI creates `.okstra/tasks/<group>/<id>/notes/<slug>-<YYYY-MM-DD>.md` and returns `notePath` and `clarificationResponseArg` as stdout JSON.
143
-
144
- **self-check rules (there is no validator, so you keep them yourself):**
145
-
146
- 1. **Do not hand-edit a rendered report** (`*.md` / `*.data.json` / `*.html` under `runs/*/reports/`). Report assembly regenerates those artifacts, so write findings to `notes/` instead.
147
- 2. **Do not author a `user-responses/` file or apply `created-by: user`.** That is the user's decision, and writing it for them forges a decision the user never made. If your evidence supports a particular answer, write that in `notes/` and leave the decision to the user. The one exception is the echo-back confirmation flow of the `okstra-user-response` skill — there the user makes the decision in-session and the CLI is merely a transcription channel, so publishing the `created-by: user` sidecar through that skill's `begin` → `answer` → `finalize` transaction is legitimate (`okstra user-response` has no `write` command). This exception holds only after the user has explicitly confirmed "correct", and only for verbatim input.
148
- 3. **Do not write to okstra-managed directories** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` is the only agent-owned lane. `recap/recap-log.jsonl` is the exception — write it, but not by hand; only via the `okstra recap record` CLI.
149
- 4. **`notes/` is inert to okstra** — no run reads it automatically. After writing, relay the `clarificationResponseArg` the CLI printed (e.g. `--clarification-response <notePath>`) to the user verbatim, telling them it only takes effect when the next run is executed with that argument.
150
-
151
- **Guardrail:** `.okstra/` is gitignored — treat `notes/` as local scratch and never `git add` it. Creating a new note is easy to undo (delete the file), so always prefer it over editing a generated or user-owned file.
152
-
153
- ### recap.6 — Reconcile the task-group context (required whenever recap.5 writes a note)
154
-
155
- A group's shared context does not stay true while its tasks run. Figures get re-measured, a success signal turns out to be satisfiable without a fix, a constraint names the wrong place. `group-context.md` states in its own header that okstra copies it into each run's `instruction-set/task-group-context.md` and carries it in the analysis packet's `## Task-Group Context` section, **ahead of the brief extract** — so a stale sentence there outranks a corrected brief for every task in the group.
156
-
157
- **After writing a note, read `<PROJECT_ROOT>/.okstra/briefs/<task-group>/group-context.md` if it exists.** If anything the note establishes touches its Definition of Better figures, success signals, Group-Wide Constraints, Ticket Relations, or its statement of what is executable from the project root, update those sections **in the same response that wrote the note**. A note written without that check is an incomplete deliverable, the same way a `.project-docs/` document without its index row is.
158
-
159
- Three rules for the edit:
160
-
161
- 1. **Only above the marker.** Edit the authored sections above `<!-- okstra:task-memory:begin -->`. The region below is okstra's projection — start order, per-task status, recorded runs — and it is redrawn from the task manifests at every `report-finalize`, at `okstra set-work-status`, and before each run copies the file. Anything you write there is overwritten without warning.
162
- 2. **Qualify a diverged figure; do not delete it.** An audit number is the baseline for the window it was measured in, not a current reading. Where a direct measurement contradicts it, say so with the measurement's date and method, and keep both. Deleting the old figure destroys the reason the group exists.
163
- 3. **Say which task and note the correction came from.** The next reader needs to get from the sentence back to its evidence.
164
-
165
- If the group has no `group-context.md`, do not create one here — `okstra group-context init` (via okstra-brief-gen) owns that skeleton, and creating an empty one pre-empts the sections a human meant to author.
166
-
167
- The same exposure applies to any other edit that supersedes group-wide facts, a brief rewrite most of all. Treat this check as belonging to the fact, not to this sub-command.
@@ -1,57 +0,0 @@
1
- # okstra-inspect facet — report
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
- ## report
6
-
7
- Trigger phrases: "find report", "show report for", "read the okstra report", "continue from report".
8
-
9
- ### report.1 — Resolve report path
10
-
11
- task-key format: `<project-id>:<task-group>:<task-id>`.
12
-
13
- **Normalization:** task-key matching is lowercase. Disk segments are slugified (lowercase + non-alphanumeric runs → `-`) per `slugify_task_segment` (`scripts/okstra_ctl/ids.py:78`); the `model-io` projections build task paths with `okstra_project.slugify` (`scripts/okstra_project/slug.py:16`), which applies the same rule. Catalog lookup is case-insensitive; file path assembly uses slugified segments.
14
-
15
- Run `okstra model-io report-input --project-root <projectRoot> --task-ref
16
- <task-key>` and use `Latest report`. For a specific date, run `okstra model-io
17
- history-input --project-root <projectRoot> --task-ref <task-key>` and select the
18
- matching numbered run block's `Report` line. If the user wants the full reading copy,
19
- render the selected record with `okstra render-final-report <report-path>`.
20
-
21
- ### report.2 — Confirm existence
22
-
23
- 1. Verify `latestReportRecordPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
24
- 2. If present, display the path and ask the user whether to read it.
25
- 3. If absent, check the `Current status`, `Work status`, and `Next phase status` projection lines:
26
- - `latestReportRecordPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.nextRecommendedPhase.status != "terminal"` → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
27
- - Any signal indicates completion but the file is missing → `Report file does not exist: <path>`
28
-
29
- `workStatus` enum: `todo | in-progress | blocked | done`. `currentStatus`: `completed` / `contract-violated` etc. `"completed"` string does NOT exist in `workStatus` — do not confuse the two.
30
-
31
- ### report.3 — Read + next-step guidance
32
-
33
- Match the depth of read to the request — final reports routinely run 300+ lines / 50K+ tokens, so ingesting the whole file just to answer "just the gist" is wasteful:
34
-
35
- - **Summary / verdict intent** ("summary", "just the key points", "conclusion", "did it pass?", "verdict"): do **not** read the whole report first. Read the `final-<task-type-segment>-<NNN>.status` sidecar under `runs/<task-type-segment>/status/` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) for the machine verdict, then read only the report's leading summary block (the first "Overall Verdict" / "Executive" / verdict heading and its body) to quote the gist. Offer to read the full report if the user wants detail.
36
- - **Full-read intent** ("the whole thing", "read it all", "full body"): ingest the resolved report file.
37
-
38
- After reading, surface follow-up options:
39
-
40
- 1. **Proceed to implementation:** based on the report's "Recommended Next Steps" section.
41
- 2. **Additional verification:** to launch a new okstra run with the same task-key, assemble the command through the `history` facet (load `facets/history.md`) — it offers the full option set (base-ref, workers, render-only) and renders a host-correct invocation.
42
- 3. **Check related tasks:** if the report references related task-keys, fetch their reports too.
43
-
44
- ### report — Output template
45
-
46
- ```markdown
47
- ## Report for <task-key>
48
-
49
- | Field | Value |
50
- | ------------ | -------------------------------------------------- |
51
- | Status | `<status>` |
52
- | Task type | `<task-type>` |
53
- | Run seq | `<NNN>` |
54
- | Run date | `<runTimestamp ISO-8601>` |
55
- | Report (rel) | `<relative-path-from-project-root>` |
56
- | Report (abs) | `<absolute-path>` |
57
- ```
@@ -1,34 +0,0 @@
1
- # okstra-inspect facet — run-audit
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
- ## run-audit
6
-
7
- Trigger phrases: "okstra run-audit", "run audit", "진행 점검", "태스크들 제대로 가고 있나", "silent failures".
8
-
9
- Check every run's artifacts against progress invariants. This catches what the error log cannot: a run that never logged a failure but still ended wrong. Read-only.
10
-
11
- ### run-audit.1 — Run the audit
12
-
13
- ```bash
14
- okstra run-audit
15
- ```
16
-
17
- ### run-audit.2 — Report (Korean)
18
-
19
- Group the `violations` array by `invariant` and report one section each:
20
-
21
- | invariant | 위반 태스크 수 | 프로젝트 수 |
22
- |---|---:|---|
23
-
24
- Under each, list the affected `taskKey` values with their `detail` and `source`. Always cite `source` — the reader must be able to open the file the verdict came from.
25
-
26
- ### run-audit.3 — Split the two outcomes
27
-
28
- State plainly which violations are this task's own state versus a repeated okstra defect:
29
-
30
- - an invariant broken in **one** task → that task's own state; tell the user what to do about that task
31
- - an invariant broken across **two or more** tasks → a repeated okstra defect; say so and cite every affected `taskKey` so the user can decide what to do with it
32
- - `approval-not-forgotten` is the exception no matter how far it spreads. It means a human has not approved yet, not that okstra did something wrong. Report it as a to-do list of tasks awaiting the user's approval instead.
33
-
34
- This facet reports; it never files anything anywhere.
@@ -1,163 +0,0 @@
1
- # okstra-inspect facet — status
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
- ## status
6
-
7
- Trigger phrases: "okstra status", "task status", "current phase", "next phase", "what is pending", "resume point", "okstra status set", "okstra mark", "<task-id> done", "<task-id> in-progress", "<task-id> in progress", "<task-id> complete".
8
-
9
- ### status.1 — Overall project status
10
-
11
- Run `okstra model-io status-input --project-root <projectRoot>`. Use the fixed
12
- text task blocks as the overview source.
13
-
14
- | Field | Description |
15
- |------|------|
16
- | `taskKey` | `<project-id>:<task-group>:<task-id>` |
17
- | `taskType` | latest task type |
18
- | `workCategory` | bugfix / feature / improvement / refactor / ops / unknown. Display `unknown` as-is, but flag with `(unset)` annotation so the reader knows the requirements-discovery classification was skipped or no `--work-category` flag was passed. |
19
- | `currentStatus` | task-level status |
20
- | `currentPhase` | lifecycle current phase |
21
- | `currentPhaseState` | lifecycle phase state |
22
- | `nextRecommendedPhase` | next-phase pointer — an **object** `{phase, status, rationale}`, never a string. `status` is `ready` / `pending` / `blocked` / `terminal`. `phase` is non-empty only under `ready`, a property of the projection rather than a constraint the struct enforces — `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal state to read. Decide launchability from `status` alone. Render `phase` (or `--` when it is empty) — never the object itself. |
23
- | `awaitingApproval` | whether awaiting approval |
24
- | `latestRunStatus` | latest run status |
25
- | `latestReportRecordPath` | latest report path |
26
- | `latestResumeCommandPath` | latest resume command |
27
- | `workStatus` | user-managed work status (todo / in-progress / blocked / done; default in-progress) |
28
- | `updatedAt` | last update time |
29
-
30
- Sort by `updatedAt` desc, then `taskKey`.
31
-
32
- The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, the pointer's status and rationale, approval gate, last run status, resume path, etc.) tell the user to run `/okstra-inspect status <task-key>` for the detail view in `status.2`.
33
-
34
- The `Next` cell is `nextRecommendedPhase.phase`, or `--` when that string is empty. If `awaitingApproval` is true OR `nextRecommendedPhase.status` is anything other than `ready`, append a `*` to the cell and explain the marker once below the table — an unset or non-`ready` pointer means no next run is launchable yet.
35
-
36
- ```markdown
37
- ## okstra Status — <project-id>
38
-
39
- | # | Task Key | Category | Phase | workStatus | Next |
40
- |---|----------|----------|-------|------------|------|
41
- | 1 | proj:group:id | bugfix | error-analysis | in-progress | implementation-planning |
42
- | 2 | proj:group:id2 | feature | requirements-discovery | done | --* |
43
-
44
- `*` = awaiting user approval, or the next-phase pointer is not `ready`. Run `/okstra-inspect status <task-key>` for details.
45
- ```
46
-
47
- ### status.2 — Specific task status
48
-
49
- Given a specific `task-key` or `task-group + task-id`:
50
-
51
- 1. Run `okstra model-io status-input --project-root <projectRoot> --task-ref <task-key>`.
52
- 2. Use only the named lines in that fixed text projection.
53
-
54
- Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportRecordPath`, `latestResumeCommandPath`, `historyTimelinePath`.
55
-
56
- The projection renders next phase, status, and rationale as separate lines.
57
- It has already promoted legacy values.
58
-
59
- ```markdown
60
- ## okstra Task Status — <task-key>
61
-
62
- - Work category: `<category>`
63
- - Current phase: `<phase>`
64
- - Current phase state: `<phase-state>`
65
- - Last completed phase: `<phase-or-->`
66
- - Next phase pointer: `<phase-or-->` (`<status>`) — `<rationale-or-->`
67
- - Awaiting approval: `<yes|no>`
68
- - Task status: `<task-status>`
69
- - Latest run status: `<run-status>`
70
- - Latest report: `<relative-path-or-->`
71
- - Resume command: `<relative-path-or-->`
72
- - workStatus: `<todo|in-progress|blocked|done>` (updated `<workStatusUpdatedAt-or-->`)
73
- - workStatus note: `<workStatusNote-or-->`
74
-
75
- ### Phase States
76
-
77
- - `requirements-discovery`: `<state>`
78
- - `error-analysis`: `<state>`
79
- - `implementation-planning`: `<state>`
80
- - `implementation`: `<state>`
81
- - `final-verification`: `<state>`
82
- - `release-handoff`: `<state>`
83
-
84
- ### Safe Resume Checkpoint
85
-
86
- - Label: `<checkpoint-label>`
87
- - Run manifest: `<relative-path-or-->`
88
- - Team state: `<relative-path-or-->`
89
- - Report: `<relative-path-or-->`
90
- - Resume command: `<relative-path-or-->`
91
- ```
92
-
93
- ### status.3 — Resume / next-step guidance
94
-
95
- The status response always includes one of:
96
-
97
- 1. **Resume current run** — if `latestResumeCommandPath` exists, display that path.
98
- 2. **Ask the user to approve** — if `workflow.awaitingApproval` is true. Tell the user to approve the plan (`okstra-run` with `--task-type implementation`, which asks `approve_plan_confirm`, or `--approve`). Quote `nextRecommendedPhase.rationale`. A `ready` pointer to `implementation` here means implementation is next after approval, not that it may launch as if already approved. Do not re-run `implementation-planning`.
99
- 3. **Answer the open clarifications** — after `implementation-planning`, when `latestReportRecordPath` is non-empty and the pointer is not `ready`. Route to `okstra-user-response`; its first step (`okstra user-response list-view`) prints this task's open-item count, and a non-zero count means the report published with `Blocks=approval` rows still open. This branch holds even when `latestRunStatus` reads `contract-violated` / `failed` and the pointer's `rationale` prescribes re-running the phase — the answers are the missing input, so a planning re-run without them reproduces the same block. Do not start implementation.
100
- 4. **Restart current phase** — only when there is nothing to answer: `latestReportRecordPath` is empty, or the open-item count is zero and `latestRunStatus` is `contract-violated`. Only an allowlisted blocking-class failure produces that status; findings demoted to `validation.advisories` leave the run passed and are not a reason to re-run. The task can be re-run with the same `task-key` and current `taskType`.
101
- Branches 5–7 are decided by `workflow.nextRecommendedPhase.status` when `awaitingApproval` is false — one status, one branch:
102
-
103
- 5. **Start next phase** — `status` is `ready` and `awaitingApproval` is false. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched without a prior approval ask, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies a final-verification verdict of `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false` (the report validator refuses that routing target otherwise), so do not re-gate it here.
104
- 6. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. After `implementation-planning`, branch 3 already owns the routing: the `C-NNN` answers come first, and planning is not re-run until they exist.
105
- 7. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
106
-
107
- ### status.4 — Update workStatus (write)
108
-
109
- Recognize requests to change a task's `workStatus` and update the corresponding `task-manifest.json`.
110
-
111
- This includes briefs whose tasks have never run. Call this command directly with the named
112
- token; do not require a catalog match or a prior `okstra-run`. The command resolves the brief
113
- and registers it when needed. For "do this small task directly and record completion", perform
114
- the authorized work, then record `done` with `--note` or `--note-file` containing the changes,
115
- verification results or reasons checks were not run, and remaining limitations. `set-work-status`
116
- refuses a direct completion whose note is empty (`test_okstra_set_work_status.py`); it does not
117
- check the note's content, so including those three parts is on you.
118
-
119
- Read `Direct work record` alongside `Work status`. A direct result is user-recorded work,
120
- not a passed cross-verification run. The command shares the result in group context and
121
- later run inputs. `Stage: share` with `Status recorded: True` means the status was saved
122
- but sharing failed; report both facts and retry the same command. Do not report full success.
123
-
124
- **Trigger patterns** (recognize both):
125
-
126
- Natural language: "change DEV-6827 to done", "mark PROD-1623 as blocked", "set DEV-9047 in progress", "Mark DEV-6827 as done".
127
-
128
- Explicit phrasing (recognized user utterances — normalize each to a `okstra set-work-status` call below):
129
- - `okstra status set <task-id> <status>`
130
- - `okstra status set <task-group> <task-id> <status>` (disambiguation)
131
- - `okstra mark <task-id> <status>`
132
- - `okstra status set <task-id> <status> --note "<note>"`
133
-
134
- Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
135
-
136
- **Procedure:** run the update through the CLI (one Bash call, literal `okstra` token) — never edit `task-manifest.json` by hand:
137
-
138
- ```bash
139
- okstra set-work-status <token> <status> --project-root <projectRoot> --text
140
- ```
141
-
142
- - `<token>` is a full task-key or a bare task-id. Add `--task-group <group>` to scope a duplicated id, `--note "<note>"` to set `workStatusNote` (flag omitted → any existing note is left untouched).
143
- - Branch on the fixed text labels: `OK: True` → confirm below. `Stage: ambiguous` → list each `Match` via a 3-option picker and retry with the chosen full task-key. `Stage: not-found` → `<TASK-ID> cannot be found.` An invalid `<status>` makes the CLI exit 2 with the allowed-values list — surface it verbatim; nothing was modified.
144
-
145
- Confirm in Korean (the block below shows the message shape only — render the actual confirmation text in Korean):
146
- ```
147
- ✓ <TASK-ID> workStatus: <previousWorkStatus> → <workStatus>
148
- ✓ task-manifest.json updated
149
- ```
150
- `<previousWorkStatus>` = `(none)` when the JSON's `previousWorkStatus` is empty.
151
-
152
- **Default value convention:** if `workStatus` is missing or empty, infer the display value from lifecycle state (DO NOT default to a static `in-progress`):
153
-
154
- | Manifest state | Inferred display |
155
- |---|---|
156
- | `currentStatus == "completed"` AND `workflow.nextRecommendedPhase.status == "terminal"` | `done` (inferred) |
157
- | `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
158
- | `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
159
- | anything else | `in-progress` (default) |
160
-
161
- Annotate inferred values with `(inferred)` or `(default)`. Do not back-fill on read; only write when the user explicitly issues an update.
162
-
163
- The projection commands own catalog/manifest reconciliation; do not repair their storage while inspecting status.
@@ -1,57 +0,0 @@
1
- # okstra-inspect facet — time
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
- ## time
6
-
7
- Trigger phrases: "work time", "elapsed time", "time summary", "duration", "elapsed", "how long did it take", "time analysis".
8
-
9
- Aggregate elapsed work time for a task, grouped by **task type** and broken down by **worker** (lead + each worker). The `time-report` CLI reads both data sources (`history/timeline.json` runs + each run's `team-state-*.json` usage blocks) and does **all** aggregation — cross-run sums, CPU-sum vs wall-clock, timestamp parsing, unavailable detection. You only resolve the task-key, call it, and render. **Never recompute durations by hand.**
10
-
11
- ### time.1 — Resolve the task-key
12
-
13
- Apply the standard task-key resolution rule from `SKILL.md` (core): full task-key → use directly; bare token → the resolver CLI and the 0/1/N branch. If no okstra history exists, say `No okstra history found. Run /okstra-run first.`
14
-
15
- ### time.2 — Fetch aggregated data
16
-
17
- ```bash
18
- okstra time-report <task-key> --project-root <projectRoot> --text
19
- ```
20
-
21
- Returns fixed labeled text (all durations are **raw milliseconds**):
22
- - Top-level total labels — `Total runs`, `Total lead ms`, `Total workers ms`, `Total CPU sum ms`
23
- - Repeated `## Task type` blocks — `Task type`, `Runs`, `Lead ms`, `Workers ms`, `CPU sum ms`
24
- - Repeated `## Worker` blocks — `Task type`, `Worker ID`, `Agents` (comma-separated agent labels that differ from the worker ID), `Runs`, `Total ms`, `Average ms`; only workers with a nonzero run appear
25
- - Repeated `## Run wall clock` blocks — `Run timestamp`, `Task type`, `Wall clock ms` (max `endedAt` − min `startedAt` per run)
26
- - Repeated `## Phase` blocks, one per phase marker — `Run timestamp`, `Task type`, `Phase`, `First at`, `Wall ms to next`
27
- - Repeated `## Unavailable run` blocks — `Run timestamp`, `Task type`, `Reason` for runs with no Phase-7 durations (never summed into totals)
28
-
29
- ### time.3 — Render
30
-
31
- Convert every `ms` label to `HH:MM:SS` (zero-pad; never show raw ms). `## Task type` blocks are already in chronological (first-appearance) order.
32
-
33
- - **By task type** — `| Task type | Runs | CPU sum | Lead | Workers |` from the `## Task type` blocks, plus a total row from the `Total …` labels. `CPU sum` (= Lead + Workers) overlaps because workers run inside the lead's window — it is *not* wall-clock. Surface wall-clock only when the user explicitly asks, from the `## Run wall clock` blocks.
34
- - **Per worker** (per task type) — `| Worker | Runs | Total | Avg/run |` from the `## Worker` blocks. Render the worker as bare `Worker ID` when `Agents` is `-`, else `<Worker ID> (agent1, agent2)`.
35
- - **Phase breakdown** — "by stage"/"per stage"/"which stage took longest" in okstra most often means the **lifecycle stage (task-type)** view, which the *By task type* table above already answers — lead with that table, do not treat the request as unanswerable. Render the intra-run phase timeline only when the user clearly means within-a-run phases ("which phase", "Phase 1~7", "phase timeline"): one table per run from the `## Phase` blocks grouped by `Run timestamp`: `| Phase | Start | Wall to next |` using `First at`/`Wall ms to next` (`-` → `--`). When there is no `## Phase` block, do **not** headline "not measurable" — the By-task-type table is the stage answer; mention the missing intra-run markers only as a trailing footnote.
36
- - If any `## Unavailable run` block exists, append a trailing note listing each run with its reason. Never fold them into totals.
37
- - Show the resolved `<task-key>` in the heading.
38
-
39
- ```markdown
40
- ## Time summary — <task-key>
41
-
42
- ### By task type
43
-
44
- | Task type | Runs | CPU sum | Lead | Workers |
45
- |------------------------|------|-----------|----------|----------|
46
- | requirements-discovery | 2 | 00:33:12 | 00:12:08 | 00:21:04 |
47
- | **Grand total** | 6 | **03:03:06** | 01:05:49 | 01:57:17 |
48
-
49
- ### Per worker — requirements-discovery
50
-
51
- | Worker | Runs | Total | Avg/run |
52
- |----------------------|------|----------|----------|
53
- | lead | 2 | 00:12:08 | 00:06:04 |
54
- | claude (sonnet-eval) | 2 | 00:09:12 | 00:04:36 |
55
-
56
- > Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — Phase 7 not reached
57
- ```
@@ -1,75 +0,0 @@
1
- ---
2
- name: okstra-rollup
3
- description: |
4
- Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "cross-task summary", "consolidated group report", "organize all tasks", "run results all at once", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap, or "where does the group stand" (per-brief status, what is next), use okstra-inspect; this skill is for the numbers and the cross-task digest. For a forward-looking work plan over non-done tasks use okstra-schedule-gen.
5
- ---
6
-
7
- # OKSTRA Rollup
8
-
9
- Cross-task roll-up: collect every catalog task's run results (optionally scoped to one task-group) and summarize them together. The `rollup` CLI does all deterministic aggregation — counts, time sums, error tallies, status/category/phase distributions. You resolve scope, call it, render the table, and synthesize the prose digest from the report files. **Never recompute totals or re-tally by hand** — the CLI is the SSOT for the numbers.
10
-
11
- The skill itself writes nothing. `okstra rollup` resolves every catalog task by task-key, and that lookup self-heals a finished implementation phase. When a task's current phase is `implementation`, that lookup 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 that task's catalog entry. Nothing else is written.
12
-
13
- ## Step 0: Preflight
14
-
15
- <!-- BEGIN FRAGMENT: host-runtime-selection -->
16
- 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.
17
- <!-- END FRAGMENT: host-runtime-selection -->
18
-
19
- <!-- BEGIN FRAGMENT: bash-invocation-rule -->
20
- 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):
21
- <!-- END FRAGMENT: bash-invocation-rule -->
22
-
23
- ```bash
24
- okstra preflight --runtime <host-runtime>
25
- ```
26
-
27
- On `Okstra preflight: ready`, carry the fixed `Project root` line. On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
28
-
29
- <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
30
- 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).
31
- <!-- END FRAGMENT: preflight-outdated-cli -->
32
-
33
- ## Step 1: Resolve scope
34
-
35
- - User named a task-group (e.g. "summarize the alpha group") → use it as `--task-group <group>`.
36
- - User asked for the whole project ("all tasks", "the whole project") or named no scope → omit `--task-group` (whole catalog).
37
- - If genuinely ambiguous, ask once: one task-group, or the whole project? Do not silently guess a specific group.
38
-
39
- ## Step 2: Fetch the roll-up
40
-
41
- ```bash
42
- okstra rollup --task-group <group> --project-root <projectRoot> --text
43
- ```
44
-
45
- Omit `--task-group` for the whole project. The command returns fixed, ordered label/value lines. Read only those labels; do not request machine output or open an artifact to recover omitted fields. Durations are raw milliseconds. If `Task count` is `0`, tell the user there are no okstra tasks in that scope and stop.
46
-
47
- ## Step 3: Render the roll-up table
48
-
49
- Convert each returned `ms` label to `HH:MM:SS` (zero-pad; never show raw ms). CPU sum includes overlapping lead and worker time. Use the returned task order.
50
-
51
- ```markdown
52
- ## okstra Rollup — <task-group or "whole project"> (<taskCount> tasks)
53
-
54
- | Task | Category | workStatus | Phase | Runs | CPU | Errors | Report |
55
- |------|----------|------------|-------|------|-----|--------|--------|
56
- | DEV-1 | bugfix | done | final-verification | 2 | 00:25:00 | 2 | ✓ |
57
- | DEV-2 | feature | in-progress | implementation | 1 | 00:00:00 | 0 | — |
58
-
59
- **Totals:** 3 runs · CPU 00:25:00 · 2 errors
60
- **workStatus:** done 1 · in-progress 1 **category:** bugfix 1 · feature 1
61
- ```
62
-
63
- Render `Report` as `✓` when the corresponding `Task N report path` holds a path, else `—`. An absent path prints as `-`. Use the numbered fixed labels and total labels verbatim; do not re-count tasks.
64
-
65
- ## Step 4: Synthesize the digest (the summary)
66
-
67
- This is the skill's value-add over a bare table. When the user asked to "summarize"/"digest"/"organize" (the common case), produce a short cross-task narrative:
68
-
69
- 1. For each task whose `Task N report path` is not `-` and whose file exists under `<projectRoot>/<Task N report path>`, read it and write a 1–2 line summary of what it accomplished and its recommended next step.
70
- 2. Above the per-task lines, write a 2–4 sentence group-level synthesis: what was delivered across the group, where the open work sits (use the `Work status N name/count` and `Current phase N name/count` lines), and any error hot-spots (tasks with a high `Task N errors`).
71
- 3. Cite each per-task claim with its `Task N report path` value so the reader can open it.
72
-
73
- For tasks with no report, state the current phase/workStatus instead of inventing a summary — do not read non-report artifacts to fill the gap.
74
-
75
- Keep the digest to what the reports actually say; if a report is missing or empty, say so rather than guessing. For a deeper single-task drill-down (full report, per-worker time, error breakdown, run-to-run recap), point the user to `/okstra-inspect`.
@@ -1,71 +0,0 @@
1
- ---
2
- name: okstra-usage
3
- description: >-
4
- Show project-wide okstra resource usage over a recent day window. Use when the
5
- user asks for okstra usage, token usage, estimated spend, CPU/wall time, usage
6
- coverage, or which lifecycle task types consumed resources. Defaults to the
7
- whole current project for the last 30 days. For one task's elapsed/context
8
- detail use okstra-inspect; for status/report digests use okstra-rollup.
9
- ---
10
-
11
- # OKSTRA Usage
12
-
13
- Project usage snapshot. The skill itself writes nothing. `okstra usage-report` resolves every catalog task by task-key, and that lookup self-heals a finished implementation phase. When a task's current phase is `implementation`, that lookup 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 that task's catalog entry. Nothing else is written. The CLI owns every sum; never re-add rows.
14
-
15
- ## Step 0: Preflight
16
-
17
- <!-- BEGIN FRAGMENT: host-runtime-selection -->
18
- 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.
19
- <!-- END FRAGMENT: host-runtime-selection -->
20
-
21
- Run one literal Bash call:
22
-
23
- ```bash
24
- okstra preflight --runtime <host-runtime>
25
- ```
26
-
27
- On `Okstra preflight: ready`, carry the fixed `Project root` line. On
28
- `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.
29
-
30
- <!-- BEGIN FRAGMENT: preflight-outdated-cli -->
31
- 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).
32
- <!-- END FRAGMENT: preflight-outdated-cli -->
33
-
34
- ## Step 1: Resolve the day window
35
-
36
- - No period stated: `30`.
37
- - “last N days”: use N only when it is a positive integer.
38
- - A calendar range, task/group/model/worker breakdown, forecast, or budget is
39
- outside this MVP; state that limitation instead of inventing flags.
40
-
41
- ## Step 2: Fetch once
42
-
43
- ```bash
44
- okstra usage-report --days 30 --project-root <projectRoot> --text
45
- ```
46
-
47
- Replace `30` only with the resolved positive integer. Do not wrap the command in
48
- `if`, `eval`, command substitution, variable assignment, `&&`, `||`, or `npx`.
49
-
50
- ## Step 3: Render
51
-
52
- If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop. If `Runs total` is `0`, say
53
- `No okstra usage found in the last N days.`, omit the table, and continue to Step 4.
54
-
55
- Otherwise, render the numbered `Task type N ...` fixed fields in returned order:
56
-
57
- | Task type | Runs | Coverage | Raw tokens | Billable | Cost | CPU | Wall |
58
- |---|---:|---:|---:|---:|---:|---:|---:|
59
-
60
- - `Coverage` = returned `Task type N collection rate`; never divide or calculate a new aggregate.
61
- - Format tokens with K/M suffixes, milliseconds as zero-padded `HH:MM:SS`, and
62
- USD to two decimals. For tokens, use one decimal at `>= 1,000` (`K`) and
63
- `>= 1,000,000` (`M`), trimming a trailing `.0`; below 1,000 render the integer.
64
- - Render the fixed total labels as the final bold row.
65
- - Never treat unavailable usage as collected zero usage.
66
-
67
- ## Step 4: Diagnostics
68
-
69
- - Render non-zero numbered `Unavailable N` and `Warning N` fields after the Step 3 output.
70
- - If numbered `Unmatched model N name` fields exist, mark Cost with `*` when the table exists and
71
- always say known-price cost excludes those exact model names.