okstra 0.76.0 → 0.78.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 (65) hide show
  1. package/README.kr.md +5 -3
  2. package/README.md +5 -3
  3. package/bin/okstra +1 -117
  4. package/docs/contributor-change-matrix.md +12 -0
  5. package/docs/kr/architecture.md +1 -1
  6. package/docs/kr/cli.md +22 -5
  7. package/docs/pr-template-usage.md +3 -3
  8. package/docs/project-structure-overview.md +1 -1
  9. package/docs/superpowers/plans/2026-05-25-okstra-project-root-rename.md +1 -1
  10. package/docs/superpowers/plans/2026-06-13-repo-risk-hardening.md +493 -0
  11. package/docs/superpowers/specs/2026-06-12-codex-lead-adapter-design.md +358 -0
  12. package/docs/superpowers/specs/2026-06-13-forbidden-actions-ssot-design.md +134 -0
  13. package/docs/superpowers/specs/2026-06-13-neutral-tmux-lead-adapter-design.md +284 -0
  14. package/package.json +5 -2
  15. package/runtime/BUILD.json +2 -2
  16. package/runtime/DO_NOT_EDIT.md +21 -0
  17. package/runtime/agents/SKILL.md +3 -0
  18. package/runtime/bin/lib/okstra/cli.sh +5 -1
  19. package/runtime/bin/lib/okstra/globals.sh +1 -0
  20. package/runtime/bin/lib/okstra/usage.sh +6 -4
  21. package/runtime/bin/okstra-trace-cleanup.sh +16 -12
  22. package/runtime/bin/okstra.sh +1 -0
  23. package/runtime/prompts/launch.template.md +4 -13
  24. package/runtime/prompts/profiles/error-analysis.md +6 -0
  25. package/runtime/prompts/profiles/forbidden-actions.json +69 -0
  26. package/runtime/prompts/profiles/implementation.md +1 -8
  27. package/runtime/prompts/profiles/improvement-discovery.md +5 -0
  28. package/runtime/prompts/profiles/release-handoff.md +3 -17
  29. package/runtime/python/okstra_ctl/analysis_packet.py +17 -0
  30. package/runtime/python/okstra_ctl/codex_dispatch.py +1552 -0
  31. package/runtime/python/okstra_ctl/context_cost.py +1 -1
  32. package/runtime/python/okstra_ctl/dispatch_core.py +897 -0
  33. package/runtime/python/okstra_ctl/doctor.py +292 -0
  34. package/runtime/python/okstra_ctl/lead_events.py +129 -0
  35. package/runtime/python/okstra_ctl/lead_runtime.py +72 -0
  36. package/runtime/python/okstra_ctl/paths.py +3 -0
  37. package/runtime/python/okstra_ctl/pr_template.py +1 -1
  38. package/runtime/python/okstra_ctl/render.py +211 -29
  39. package/runtime/python/okstra_ctl/run.py +89 -18
  40. package/runtime/python/okstra_ctl/team.py +267 -0
  41. package/runtime/python/okstra_ctl/tmux.py +181 -10
  42. package/runtime/python/okstra_ctl/workflow.py +30 -71
  43. package/runtime/python/okstra_ctl/wrapper_status.py +55 -0
  44. package/runtime/python/okstra_token_usage/codex.py +12 -7
  45. package/runtime/python/okstra_token_usage/collect.py +243 -54
  46. package/runtime/python/okstra_token_usage/gemini.py +12 -7
  47. package/runtime/schemas/final-report-v1.0.schema.json +3 -1
  48. package/runtime/skills/okstra-convergence/SKILL.md +3 -0
  49. package/runtime/skills/okstra-report-writer/SKILL.md +3 -0
  50. package/runtime/skills/okstra-setup/SKILL.md +1 -1
  51. package/runtime/skills/okstra-team-contract/SKILL.md +12 -0
  52. package/runtime/validators/forbidden_actions.py +135 -0
  53. package/runtime/validators/validate-run.py +112 -22
  54. package/runtime/validators/validate_session_conformance.py +127 -5
  55. package/src/cli-registry.mjs +277 -0
  56. package/src/codex-dispatch.mjs +70 -0
  57. package/src/codex-run.mjs +68 -0
  58. package/src/doctor.mjs +130 -5
  59. package/src/install.mjs +123 -26
  60. package/src/paths.mjs +17 -3
  61. package/src/render-bundle.mjs +2 -0
  62. package/src/runtime-manifest.mjs +29 -0
  63. package/src/team.mjs +63 -0
  64. package/src/uninstall.mjs +27 -4
  65. /package/runtime/{skills/okstra-run/templates → templates/prd}/pr-body.template.md +0 -0
@@ -32,14 +32,7 @@
32
32
  - Approval gate (phase-specific addendum to shared authority rule):
33
33
  - the pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination.
34
34
  - Forbidden actions — universal (any occurrence → terminal status `contract-violated`):
35
- - **`git push` of any kind**, including `--dry-run` against a real remote that produces side-effects
36
- - publishing or release commands: `npm publish`, `cargo publish`, `pip publish`, `gh release`, `docker push`
37
- - real database migrations or schema changes that touch shared environments
38
- - production credentials, deploy commands, infra mutation against non-local clusters
39
- - external API WRITE calls (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures
40
- - dispatching parallel sub-agents beyond the required worker roster
41
- - any Edit/Write before the pre-implementation gate has passed
42
- - source edits or Bash mutations performed by any verifier role (verifier-specific deny-list lives in the verifier sidecar)
35
+ {{PHASE_FORBIDDEN_ACTIONS}}
43
36
  - In-phase debugging:
44
37
  - isolate root cause before changing the fix direction, but the executor MUST NOT route to a separate `error-analysis` phase mid-run; if a defect blocks plan progress, the executor records findings and routes to a new run after this one ends.
45
38
 
@@ -20,6 +20,11 @@
20
20
  - per-candidate evidence (path:line) and scope mapping
21
21
  - per-candidate severity / effort / recommended-next-phase
22
22
  - convergence classification (full / partial / contested / worker-unique) across workers
23
+ - Worker diversity rule:
24
+ - every analyser inspects every priority lens, but each starts with a different primary pass so the run does not rely on model randomness for diversity. Order lenses exactly as they appear in the brief; `claude` starts at lens 1, `codex` at lens 2, and `gemini` at lens 3, wrapping around when fewer lenses are present.
25
+ - before broadening to the remaining lenses, each worker must either produce at least one candidate from its primary pass or record a no-candidate rationale with the highest-signal path:line evidence it inspected.
26
+ - two workers' candidates are the same candidate only when they cite the same underlying design/code problem and the same remediation direction. Shared evidence paths alone are not enough to merge; keep distinct failure modes distinct.
27
+ - when a candidate from one worker overlaps another worker's evidence, convergence must verify whether it is duplicate, broader/narrower, or conflicting. Do not collapse contested candidates just to meet the candidate cap.
23
28
  - Phase 1.5 — Lead reflect-back grilling (runs after Phase 1 context loading and before Phase 4 worker dispatch):
24
29
  - Lead inspects scan-scope paths via `ls` / `Grep` / `Read` to map modules, entry points, dependencies, approximate LOC, and recent commit patterns.
25
30
  - Lead emits a single reflect-back message covering: (a) understood scope per path (one-line summary), (b) understood meaning of each priority lens in this scope, (c) understood out-of-scope rationale, (d) ordered list of N open questions.
@@ -20,9 +20,9 @@
20
20
  - the lead MUST confirm `git log --oneline <base>..HEAD` contains at least one implementation commit. If it is empty, the run MUST end with status `blocked` and route back to `implementation`.
21
21
  - User interaction protocol (Claude lead — performed in order, using `AskUserQuestion` or the equivalent interactive prompt):
22
22
  1. **Action selection** — present three choices and capture exactly one:
23
- - `local only` — record the accepted, already-committed branch and end without push or PR.
23
+ - `local only` — complete the handoff as a local delivery record: record the accepted, already-committed branch and end without push or PR.
24
24
  - `push + PR` — push the feature branch, then open or reuse a pull request.
25
- - `skip` — record the verified state and end the run without any git command.
25
+ - `skip` — cancel delivery actions for now: record that release-handoff was intentionally skipped and end the run without any git command.
26
26
  If the user picks `skip`, route directly to the final-report self-review pass.
27
27
  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage confirmation, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
28
28
  1g. **G2 — stage confirmation**: the stage selection already happened before the run (wizard `handoff_stage_pick`, or the CLI `--stages` flag) and is fixed in `HANDOFF_STAGES`. Display it as a one-line confirmation (`PR 대상 stage: <csv> — 진행합니다`) and proceed; do NOT re-ask the multi-select. Only if `HANDOFF_MODE` is `stage-group` but `HANDOFF_STAGES` is empty (defensive, should not happen) run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and ask the user to pick from the eligible stages.
@@ -60,21 +60,7 @@
60
60
  - after `gh pr create` succeeds (or an existing PR is reused), the lead MUST run `okstra handoff record-pr --plan-run-root <...> --stages <csv> --branch <head branch> --url <pr url>` and quote the command + exit code in the final report. This applies to BOTH modes — whole-task runs record `--stages` as the full Stage Map list — so duplicate-PR prevention converges on one consumers record.
61
61
  - stage-group helpers: `okstra handoff eligible`, `okstra handoff assemble`, `okstra handoff record-pr`. The assemble step is the ONLY path that may create commits (merge commits on the collector branch) in this phase.
62
62
  - Forbidden actions (any occurrence → terminal status `contract-violated`):
63
- - local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` run by the lead. The single exception is the merge commits `okstra handoff assemble` itself creates on the collector branch — the lead never merges by hand.
64
- - any of the following git push variants, regardless of intent or whether the user said "force it":
65
- - `git push --force`
66
- - `git push --force-with-lease`
67
- - `git push -f`
68
- - `git push +<refspec>`
69
- - any other invocation that rewrites remote history
70
- - pushing directly to a base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the PR base in this run. The only permitted push target is the current feature branch.
71
- - bypassing repo safeguards: `--no-verify` / `-n` on `git push`, disabling safeguards via equivalent flags, or any hook bypass.
72
- - release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.
73
- - source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.
74
- - executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local only`; pushing when the user picked `skip`; switching the PR base branch silently after the user already chose one.
75
- - retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.
76
- - `TeamCreate`, `Agent(...)` dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Claude lead.
77
- - silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim.
63
+ {{PHASE_FORBIDDEN_ACTIONS}}
78
64
  - Required deliverable shape (final report, in addition to the standard sections):
79
65
  - **Source Verification Report**: relative path of the originating `final-verification` final-report file plus the literal quoted `Verdict Token` row whose value is `accepted`.
80
66
  - **Feature Branch & Working-Tree State**: branch name from `git rev-parse --abbrev-ref HEAD`, output of `git status --short` at run start.
@@ -27,12 +27,28 @@ PROFILE_SECTIONS = (
27
27
  "Clarification request policy",
28
28
  )
29
29
  PROFILE_SECTIONS_BY_TASK_TYPE = {
30
+ "requirements-discovery": (
31
+ "Fan-out",
32
+ "Decision-tree walk",
33
+ ),
34
+ "error-analysis": (
35
+ "Diagnosis loop",
36
+ ),
30
37
  "implementation-planning": (
31
38
  "Section heading contract",
32
39
  "Required deliverable shape",
33
40
  "No-placeholder rule",
34
41
  "Self-review pass before finalising the report",
35
42
  ),
43
+ "final-verification": (
44
+ "Required deliverable shape",
45
+ "Self-review pass before finalising the report",
46
+ ),
47
+ "improvement-discovery": (
48
+ "Phase 1.5 — Lead reflect-back grilling",
49
+ "Worker diversity rule",
50
+ "Decision-tree walk",
51
+ ),
36
52
  }
37
53
  CLARIFICATION_SECTIONS = (
38
54
  "Clarification Items",
@@ -261,6 +277,7 @@ def _top_level_bullet_heading(line: str) -> str:
261
277
  if not line.startswith("- ") or ":" not in line:
262
278
  return ""
263
279
  label = line[2:].split(":", 1)[0].strip().strip("*")
280
+ label = label.split(" (", 1)[0].strip()
264
281
  return label
265
282
 
266
283