okstra 0.76.0 → 0.78.0

package/docs/superpowers/specs/2026-06-12-codex-lead-adapter-design.md

@@ -0,0 +1,358 @@
+# Claude Code / Codex lead adapter split design
+
+- 날짜: 2026-06-12
+- 상태: 설계 초안
+- 대상: okstra runtime, installed skills, lead orchestration contract
+
+## 1. 배경
+
+okstra 의 core runtime 은 이미 비교적 플랫폼 중립적이다.
+`prepare_task_bundle()` 이 task bundle, manifests, prompts, worktree,
+validators 를 생성하고, Node CLI 는 이 Python core 를 호출한다.
+
+문제는 lead 실행 계층이 Claude Code 전용 계약을 강하게 전제한다는 점이다.
+
+- skills 는 `~/.claude/skills/` 에 설치된다.
+- worker agents 는 `~/.claude/agents/` 에 설치된다.
+- in-session run 은 `AskUserQuestion` 과 Claude Code slash skill 흐름을 전제한다.
+- team execution 은 `TeamCreate` / `Agent(...)` / `team_name` 을 전제한다.
+- resume, token usage, team reconcile 은 Claude session jsonl 과
+  `~/.claude/projects`, `~/.claude/teams` 를 읽는다.
+
+따라서 Codex 에서 같은 저장소를 사용하려면 프로젝트를 통째로 둘로 복사하는 대신
+**lead adapter** 를 나눠야 한다.
+
+## 2. 결정
+
+okstra 는 하나의 공통 core 와 두 lead adapter 로 분리한다.
+
+```text
+okstra core
+  - prepare_task_bundle
+  - task/run manifests
+  - worktree registry
+  - final-report schema/render/validators
+  - wizard state machine
+  - worker result / convergence schemas
+
+lead adapters
+  - claude-code adapter
+  - codex adapter
+```
+
+Claude Code adapter 는 현재 동작을 유지한다. Codex adapter 는 Claude Teams 를
+흉내내지 않고 Codex 가 제공하는 방식으로 같은 artifact contract 를 채운다.
+
+## 3. 비목표
+
+- `prepare_task_bundle()` 를 Claude/Codex 별로 복제하지 않는다.
+- phase profile, schema, validator 를 provider 별로 fork 하지 않는다.
+- Codex adapter 가 Claude Code 의 `TeamCreate` 나 `Agent(...)` 를 동일하게
+  재현한다고 주장하지 않는다.
+- 기존 Claude Code slash skill UX 를 깨지 않는다.
+
+## 4. Adapter 경계
+
+### 4.1 공통 core 로 남길 것
+
+| 영역 | 이유 |
+|---|---|
+| `scripts/okstra_ctl/run.py::prepare_task_bundle` | task identity 와 artifact layout 의 single authority |
+| `scripts/okstra_ctl/worktree*.py` | provider 와 무관한 격리/동시성 계약 |
+| `scripts/okstra_ctl/workers.py` | phase profile 이 허용하는 logical roster 검증 |
+| `scripts/okstra_ctl/render*.py` | manifests, prompts, final report rendering |
+| `schemas/`, `validators/`, `templates/` | output contract 의 SSOT |
+| `prompts/profiles/*.md` | lifecycle phase 규칙의 SSOT |
+
+### 4.2 Claude Code adapter 로 남길 것
+
+| 영역 | 현재 결합 |
+|---|---|
+| installed skills | `~/.claude/skills/okstra-*` |
+| installed agents | `~/.claude/agents/*-worker.md` |
+| interactive UI | `AskUserQuestion` |
+| worker dispatch | `TeamCreate`, `Agent(...)`, `team_name` |
+| resume | `claude --resume <session-id>` |
+| session accounting | Claude session jsonl, `~/.claude/projects` |
+| team cleanup | `~/.claude/teams`, `TeamDelete` |
+
+### 4.3 Codex adapter 로 새로 둘 것
+
+Codex adapter 는 다음을 담당한다.
+
+| 책임 | Codex 방식 |
+|---|---|
+| input collection | CLI wizard JSON 을 Codex 대화/질문으로 relay |
+| task bundle prepare | 기존 `okstra render-bundle` / `prepare_task_bundle()` 호출 |
+| lead progress logging | `PROGRESS:` line 을 assistant text + run artifact 에 기록 |
+| worker fan-out | Codex sub-agent tool, or CLI wrapper process, or sequential fallback |
+| worker result persistence | 기존 `worker-results/*.md` contract 에 맞춰 파일 작성 |
+| convergence | 기존 `okstra-convergence` 알고리즘을 lead-local 로 실행 |
+| report writing | report-writer worker 가 없으면 explicit fallback status 를 기록한 뒤 lead-authored path 사용, 또는 Codex 전용 report-writer role 을 정의 |
+| resume | Codex session resume 가 아니라 run artifact checkpoint 기준 재진입 |
+
+## 5. Execution modes
+
+### 5.1 `leadRuntime=claude-code`
+
+현재 기본값이다.
+
+- 설치: `okstra install` 이 `~/.claude/skills` 와 `~/.claude/agents` 를 채운다.
+- 실행: slash skill 또는 `okstra.sh` 가 Claude lead 를 시작한다.
+- worker dispatch: `TeamCreate` / `Agent(...)`.
+- validator: 기존 session conformance 를 그대로 적용한다.
+
+### 5.2 `leadRuntime=codex`
+
+신규 모드다.
+
+- 설치: Claude assets 는 선택 설치로 바꾸고, Codex adapter assets 를 별도 설치한다.
+- 실행: `okstra codex-run` 또는 `okstra run --lead-runtime codex`.
+- worker dispatch:
+  - 가능한 경우 Codex sub-agent fan-out 사용.
+  - 불가능하면 CLI wrapper 또는 sequential local analysis 로 degrade.
+- team-state 는 Claude team fields 대신 `leadRuntime: "codex"` 와
+  `dispatchMode` 를 명시한다.
+- validator 는 `leadRuntime` 별 conformance rule 을 고른다.
+
+## 6. Contract changes
+
+### 6.1 manifest
+
+`task-manifest.json` 또는 run manifest 에 다음 필드를 추가한다.
+
+```json
+{
+  "leadRuntime": "claude-code",
+  "leadAdapter": {
+    "name": "claude-code",
+    "dispatchMode": "team",
+    "sessionAccounting": "claude-jsonl"
+  }
+}
+```
+
+Codex run 예:
+
+```json
+{
+  "leadRuntime": "codex",
+  "leadAdapter": {
+    "name": "codex",
+    "dispatchMode": "codex-subagents",
+    "sessionAccounting": "artifact-only"
+  }
+}
+```
+
+### 6.2 validator
+
+`validate_session_conformance.py` 는 현재 Claude session jsonl 을 검사한다.
+이를 다음처럼 분기한다.
+
+| runtime | conformance source |
+|---|---|
+| `claude-code` | existing Claude session jsonl scan |
+| `codex` | run artifact event log scan |
+
+Codex adapter 는 `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl`
+에 진행 이벤트를 기록한다.
+
+Token/cost validation is runtime-aware. `claude-code` keeps the existing
+fail-close `okstra token-usage --substitute-data` requirement. `codex` does
+not run the Claude session-jsonl auto-recovery path. Codex runtime worker
+usage is collected from `lead-events-*.jsonl` dispatch windows matched against
+Codex rollout / Gemini session logs, so CLI-backed worker and report-writer
+cost can be summarized without Claude wrapper jsonls. Codex lead token
+accounting is still unavailable, and validator does not yet force
+final-report token substitution for Codex runs.
+
+### 6.3 report author
+
+기존 규칙은 "report-writer worker 가 roster 에 있으면 lead 가 직접 쓰지 않는다"이다.
+Codex adapter 에서도 이 원칙은 유지하되, report-writer role 의 구현을 runtime 별로 둔다.
+
+```text
+logical role: report-writer
+  claude-code implementation: Agent(subagent_type=report-writer-worker)
+  codex implementation: Codex report-writer subagent or explicit recorded fallback
+```
+
+## 7. Install layout
+
+현재 설치는 Claude Code 를 전제로 한다. 설치 command 를 runtime-aware 로 분리한다.
+
+```bash
+okstra install --runtime claude-code   # default, current behavior
+okstra install --runtime codex         # codex adapter assets only
+okstra install --runtime all           # both adapters
+```
+
+권장 내부 구조:
+
+```text
+adapters/
+  claude-code/
+    skills/
+    agents/
+    settings/
+  codex/
+    skills/
+    prompts/
+    adapter.md
+```
+
+단, 첫 구현에서는 물리 디렉터리 이동 없이 installer option 과 manifest field 만
+도입해도 된다. 대규모 파일 이동은 후속 cleanup 으로 둔다.
+
+## 8. 단계별 구현 계획
+
+### Stage 1 — runtime marker only
+
+- `--lead-runtime <claude-code|codex>` flag 를 `render-bundle` / `okstra.sh` /
+  `prepare_task_bundle()` 에 추가한다.
+- 기본값은 `claude-code`.
+- manifests 와 team-state 에 `leadRuntime` / `leadAdapter` 를 기록한다.
+- `codex` 는 dispatch adapter 가 생기기 전까지 `--render-only` 에서만 허용하고,
+  non-render prepare 는 명확히 fail 한다.
+
+### Stage 2 — Codex dry-run adapter
+
+- `okstra codex-run` 를 추가한다.
+- wrapper 가 `--render-only --lead-runtime codex` 를 소유하고, 사용자가 직접
+  중복 전달하면 거부한다.
+- wizard/render-bundle 로 task bundle 을 만들고, Codex lead prompt 를 출력한다.
+- worker dispatch 는 하지 않는다.
+- 목적: Codex 에서 task bundle intake, profile reading, phase boundary 를 안정화.
+
+### Stage 3 — Codex artifact event log
+
+- `lead-events-*.jsonl` writer/reader 를 추가한다.
+- `runs/<task-type>/state/lead-events-<task-type>-<seq>.jsonl` 를
+  team-state / run-manifest / task-manifest artifacts 에 노출한다.
+- Codex render-only adapter 는 우선 `bundle-prepared` event 를 기록한다.
+- validator 는 `leadRuntime=codex` 일 때 Claude session jsonl 대신 event log 를
+  읽고 `progress` / `artifact-read` 이벤트를 checkpoint / implementation
+  sidecar-read 증거로 사용한다.
+- 후속 dispatch 단계에서 `worker-dispatched`, `worker-result-collected` event 를
+  기록한다.
+
+### Stage 4 — Codex worker dispatch
+
+- logical worker role 을 유지하면서 Codex adapter 의 dispatch backend 를 붙인다.
+- backend 우선순위:
+  1. Codex sub-agent dispatch
+  2. CLI wrapper dispatch
+  3. sequential fallback with terminal status markers
+- 모든 backend 는 기존 `worker-results/*.md`, prompt history, errors sidecar 를
+  같은 path 에 써야 한다.
+- 첫 구현 범위(2026-06-12): `okstra codex-run` 으로 준비된 run manifest 를
+  입력으로 받는 `okstra codex-dispatch` 보조 명령을 추가한다.
+  - 지원 worker: 기존 CLI wrapper 계약이 있는 `codex`, `gemini`.
+  - `report-writer` 는 Stage 5 의 명시 opt-in 경로에서 지원한다.
+  - 미지원 worker: `--workers` 를 생략한 기본 dispatch 에서는 `claude` 같은
+    Codex-side 미지원 roster 항목을 건너뛴다. 사용자가 `--workers claude` 처럼
+    명시 요청하면 Codex-native 구현 전까지 즉시 unsupported 로 실패한다.
+  - 실행 방식: shell 없이 wrapper 를 `subprocess.run([...])` 으로 호출하고,
+    team-state worker status 와 `lead-events-*.jsonl` 의
+    `worker-dispatched` / `worker-result-collected` / `worker-failed` 이벤트를
+    갱신한다.
+  - prompt history 파일이 아직 없으면 run manifest / active-run-context 에서
+    자동 생성한다. 기존 prompt 파일은 덮어쓰지 않는다.
+  - dispatch plan 과 lead-events 는 worker 별 `backend` / `dispatchMode` 를
+    기록한다. 현재 값은 모두 `cli-wrapper` 이며, `_run_worker()` 는 backend router
+    로 분리되어 미지원 backend 를 wrapper 실행 전에 거부한다.
+  - 비범위: Claude TeamCreate 대체, final-report Phase 7 token substitution,
+    report-writer 후처리, token/session accounting. 이후 Stage 5 에서
+    report-writer 후처리가 추가됐고, Stage 5.5 에서 worker CLI token accounting
+    이 추가됐다.
+
+### Stage 5 — Codex report-writer
+
+- report-writer logical role 을 Codex sub-agent 로 구현한다.
+- 실패 시 기존 fallback 규칙처럼 dispatch attempt 와 terminal status 를 기록한다.
+- final-report data.json -> renderer -> views -> token/cost placeholder 처리 순서는
+  Claude adapter 와 동일하게 유지한다.
+- 첫 구현 범위(2026-06-12): `okstra codex-dispatch` 에 준비된
+  report-writer prompt 를 Codex wrapper 로 실행하는 opt-in 경로를 추가한다.
+  - 사용자는 `--workers report-writer --enable-codex-report-writer
+    --report-writer-codex-model <model>` 을 명시해야 한다.
+  - 이유: run manifest 의 report-writer model assignment 는 아직 Claude provider
+    기준(`REPORT_WRITER_MODEL_EXECUTION_VALUE`)으로 렌더되므로, Codex CLI 에
+    넘길 모델은 dispatch 단계에서 명시 override 해야 한다.
+  - dispatcher 는 prompt 의 `**Model:** Report writer worker, ...` header 를
+    override 값으로 갱신하고, wrapper 실행 성공 후 세 artifact 를 모두 확인한다:
+    `reports/final-report-*.data.json`, 렌더된 `reports/final-report-*.md`,
+    `worker-results/report-writer-worker-*.md` audit sidecar.
+  - artifact 확인 후 idempotent 한 후처리 네 개를 실행한다:
+    `okstra-token-usage.py --write --substitute-data` 로 token/cost 값을
+    data.json 과 markdown 에 치환하고,
+    `okstra-render-report-views.py` 로 HTML view 를 렌더하고,
+    `okstra-spawn-followups.py` 로 `followUpTasks[]` 의 auto-spawn 항목을
+    task stub 으로 만들고,
+    `validators/validate-run.py` 로 final-report schema / markdown contract /
+    report-view contract 를 검증한다. HTML view 가 치환 후 markdown 을 읽도록
+    token substitution 이 항상 render-views 보다 먼저 실행되며, validation 은
+    더 이상 실패할 후처리 단계가 없는 마지막 gate 로 실행된다. 후처리가 실패하면
+    report-writer 는 failed 로 기록한다.
+  - report-writer prompt history 파일이 아직 없으면 dispatcher 가 자동 생성한다.
+    이때 `Result Path` 는 `.data.json`, `Worker Result Path` 는 audit sidecar,
+    `Report Language` 는 project/global config 또는 task brief 추론값으로 채운다.
+  - 비범위: Codex lead 자체 token/cost accounting.
+
+### Stage 5.5 — Codex worker CLI token accounting
+
+- Codex runtime 은 Claude Agent wrapper session 을 생성하지 않으므로,
+  `okstra token-usage` 가 `lead-events-*.jsonl` 의 worker dispatch window 를
+  session source 로 사용한다.
+- `codex` worker 와 Codex opt-in `report-writer` 는 Codex rollout JSONL 을,
+  `gemini` worker 는 Gemini chat session JSON 을 window 안에서 매칭한다.
+- `usageSummary.workerTotalTokens` 와 `estimatedCostUsd.cliWorkers` 는 CLI worker
+  totals 를 반영한다.
+- report-writer 후처리 중에는 `worker-result-collected` 이벤트가 아직 append
+  되기 전이므로, collector 는 `status=running` worker 의 active dispatch 를
+  수집 시각까지의 open window 로 사용할 수 있다.
+- Codex lead 자체 token/cost 는 아직 공식 수집원이 없어 `leadUsage.source =
+  "unavailable"` 로 남긴다.
+- validator 는 Codex run 에 대해 token substitution auto-recovery 를 강제하지
+  않는다. 이 단계의 목적은 collector data 를 먼저 정확히 채우는 것이다.
+
+### Stage 6 — install packaging cleanup
+
+- `okstra install --runtime <claude-code|codex|all>` 을 추가한다.
+  - `claude-code` 기본값은 기존 동작 그대로 공유 runtime + Claude skills/agents 를
+    설치한다.
+  - `codex` 는 공유 runtime/bin/templates/schema/validators/settings 만 설치하고
+    `~/.claude/skills` / `~/.claude/agents` 를 건드리지 않는다.
+  - `all` 은 Claude assets 포함 설치와 동일하다. 별도 Codex-only asset tree 가
+    생기면 여기서 함께 설치한다.
+- `okstra ensure-installed --runtime <...>` 는 같은 runtime 으로 재설치하며,
+  `codex` 는 Claude skill/agent drift 검사를 건너뛴다.
+- `okstra doctor --runtime <...>` 는 `codex` 에서 Claude skill checks 를 제외하고
+  JSON 출력에 선택 runtime 을 포함한다.
+- `~/.okstra/installed-runtimes.json` 을 추가해 선택 runtime 과 asset 범위를
+  `installed-skills.json` / `installed-agents.json` 과 분리해 기록한다.
+  codex-only manifest 는 uninstall 이 레거시 fallback 으로 `~/.claude` 자산을
+  제거하지 않도록 막는다.
+- README / docs 는 Codex-only install + doctor 경로를 노출한다.
+- 남은 cleanup: Codex 전용 skill/adapter asset 이 생기면
+  `installed-runtimes.json` 의 Codex asset 범위를 실제 파일 manifest 로 확장한다.
+
+## 9. 위험과 대응
+
+| 위험 | 대응 |
+|---|---|
+| validator 가 Claude session jsonl 만 신뢰 | `leadRuntime` 별 conformance source 분기 |
+| worker output contract drift | logical worker role/schema 는 공유하고 dispatch backend 만 교체 |
+| report-writer authorship 규칙 훼손 | runtime 별 report-writer implementation 을 두고 fallback 은 명시 기록 |
+| 설치 경로 혼란 | `okstra doctor --runtime <name>` 로 runtime 별 진단 |
+| 두 버전 문서 drift | phase profile/schema/validator 는 fork 금지, adapter docs 만 분리 |
+
+## 10. 결론
+
+가능하다. 단, "Claude Code 버전"과 "Codex 버전"을 제품 복사본으로 나누는 것이
+아니라, **lead runtime adapter 를 나누는 방식**이어야 한다.
+
+가장 작고 안전한 첫 PR 은 `leadRuntime` marker 와 Codex dry-run adapter 이다.
+이 PR 은 기존 Claude Code 사용자를 깨지 않으면서 Codex 실행 경로를 공식적으로
+받아들일 수 있는 구조를 만든다.

package/docs/superpowers/specs/2026-06-13-forbidden-actions-ssot-design.md

@@ -0,0 +1,134 @@
+# Forbidden-Actions SSOT Design (P2-2)
+
+**Goal:** Eliminate the drift between the two places per-phase *forbidden actions* are authored, by making one JSON file the single source of truth (SSOT) from which both the launch-prompt boundary and the profile body derive.
+
+**Scope:** `forbidden` only. `allowed`, required-workers, and profile `Purpose`/`Non-goals` are explicitly out of scope (user decision; see Non-goals).
+
+**Format:** JSON data file (no YAML — the repo deliberately ships no YAML parser; `scripts/okstra_ctl/wizard.py:128` hand-parses frontmatter "no yaml dep", CLAUDE.md "stdlib first"). User-confirmed.
+
+---
+
+## 1. Current state (verified)
+
+Per-phase forbidden actions are authored in **two** places and injected into the lead from **two** surfaces in a single run:
+
+- **Python literal** — [`scripts/okstra_ctl/workflow.py:36`](../../../scripts/okstra_ctl/workflow.py) `PHASE_RULES[<phase>]["forbidden"]`, a `"  - item\n"`-joined string. `compute_workflow_state` ([workflow.py:233](../../../scripts/okstra_ctl/workflow.py)) emits it as `PHASE_FORBIDDEN_ACTIONS`, injected into [`prompts/launch.template.md:16`](../../../prompts/launch.template.md) "Current Phase Boundary".
+- **Profile prose** — `prompts/profiles/<phase>.md`. The full profile body is rendered into `analysis-profile.md` ([run.py:1812](../../../scripts/okstra_ctl/run.py)) and read by the lead.
+
+Crucially, only **2 of 7** profiles carry a `Forbidden actions` block that duplicates `PHASE_RULES`:
+
+| task type | profile forbidden block? | PHASE_RULES.forbidden? | duplicated? |
+|---|---|---|---|
+| requirements-discovery | no (`Non-goals` only, [requirements-discovery.md:57](../../../prompts/profiles/requirements-discovery.md)) | yes | no |
+| improvement-discovery | no (`Non-goals` only) | yes | no |
+| error-analysis | no (`Non-goals` only) | yes | no |
+| implementation-planning | no (`Non-goals` only) | yes | no |
+| **implementation** | **yes** ([implementation.md:34](../../../prompts/profiles/implementation.md), 8 items) | yes (13 items) | **yes, divergent** |
+| final-verification | no (`Non-goals` only) | yes | no |
+| **release-handoff** | **yes** ([release-handoff.md:62](../../../prompts/profiles/release-handoff.md), 15 items) | yes (11 items) | **yes, divergent** |
+
+`Non-goals` is a *distinct concept* (scope guidance) from `Forbidden actions` (`contract-violated` safety rules). It is **not** consolidated by this work.
+
+So the drift-prone duplication is exactly **implementation** and **release-handoff**, where the profile block and `PHASE_RULES` have diverged (different item counts, wording, ordering) with no test guarding them.
+
+---
+
+## 2. Design
+
+### 2.1 SSOT file
+
+Create `prompts/profiles/forbidden-actions.json`:
+
+```json
+{
+  "requirements-discovery": ["...", "..."],
+  "improvement-discovery": ["..."],
+  "error-analysis": ["..."],
+  "implementation-planning": ["..."],
+  "implementation": ["..."],
+  "final-verification": ["..."],
+  "release-handoff": ["..."],
+  "unknown": ["..."]
+}
+```
+
+- Each value is the ordered list of forbidden-action items (one string per current `  - ` bullet, **without** the leading `  - `).
+- `unknown` mirrors `PHASE_RULES_UNKNOWN["forbidden"]`.
+- Lives under `prompts/profiles/` so it resolves the same way the profile `.md` files do (`workspace_root / "prompts" / "profiles" / ...`, [run.py:1073](../../../scripts/okstra_ctl/run.py)) and is synced into `runtime/` by `tools/build.mjs` (prompts/ is a build source).
+
+### 2.2 Rendering & injection
+
+In `workflow.py`:
+
+- `def load_phase_forbidden(workspace_root: Path) -> dict[str, str]` — explicit IO: `json.load` the file, render each phase's list to the existing `"  - item\n"` string shape via a pure helper `render_forbidden(items: list[str]) -> str`. Raise `FileNotFoundError`/`PrepareError`-style if missing (fail loud, no silent stale fallback).
+- `compute_workflow_state(..., forbidden_by_phase: dict[str, str])` — new **required** keyword arg; `PHASE_FORBIDDEN_ACTIONS = forbidden_by_phase.get(task_type, forbidden_by_phase["unknown"])`.
+- **Delete** the `"forbidden"` key from every `PHASE_RULES` entry and from `PHASE_RULES_UNKNOWN`. `PHASE_RULES` keeps `"allowed"` only.
+
+In `run.py` (the only two `compute_workflow_state` call sites, [run.py:2012](../../../scripts/okstra_ctl/run.py), [run.py:2232](../../../scripts/okstra_ctl/run.py)):
+
+- Load `forbidden_by_phase = workflow.load_phase_forbidden(workspace_root)` once (where `workspace_root` is already resolved for the profile file) and pass it to both calls.
+- In `_write_instruction_set_sources` ([run.py:1798](../../../scripts/okstra_ctl/run.py)), add `{{PHASE_FORBIDDEN_ACTIONS}}` to the placeholder substitution applied to `profile_rendered`, using the rendered string for `inp.task_type`.
+
+### 2.3 Profile body changes (only impl + release-handoff)
+
+- [implementation.md:34-42](../../../prompts/profiles/implementation.md): keep the header line `- Forbidden actions — universal (any occurrence → terminal status \`contract-violated\`):`, replace the 8 hand-written bullets with the single token `{{PHASE_FORBIDDEN_ACTIONS}}`.
+- [release-handoff.md:62-77](../../../prompts/profiles/release-handoff.md): keep the header line `- Forbidden actions (any occurrence → terminal status \`contract-violated\`):`, replace the 15 hand-written bullets (incl. the nested push-variant sub-list) with `{{PHASE_FORBIDDEN_ACTIONS}}`.
+- The other 5 profiles are **untouched** (their `Non-goals` blocks stay; they have no forbidden duplication).
+
+### 2.4 Canonical content (reconciliation)
+
+For the 5 non-duplicated phases, the JSON list = current `PHASE_RULES.forbidden`, **verbatim** (launch injection byte-identical, nothing else references it).
+
+For the 2 duplicated phases the JSON list = the **union** (lose no rule from either source):
+
+- **implementation** = `PHASE_RULES["implementation"]["forbidden"]` (13 items, the near-superset) with the profile's `git push ... --dry-run` nuance folded into the publish/push item. Every profile item maps into a PHASE_RULES item (git push, publish, DB, infra, API-write, sub-agents, Edit/Write-before-gate, verifier-read-only).
+- **release-handoff** = the profile's detailed 15-item list ([release-handoff.md:62-77](../../../prompts/profiles/release-handoff.md), the superset: explicit `--force`/`--force-with-lease`/`-f`/`+refspec`, base-branch push, `--no-verify`, `gh release create`/`edit` + `twine upload` + publish set, source edits, unselected command, weaker-flag retry, `TeamCreate`/`Agent` ban, unrecognised-reply). All `PHASE_RULES` release-handoff items are already covered by it.
+
+### 2.5 Disclosed behavior changes
+
+Nothing is lost; one surface becomes *more complete* for the 2 phases:
+
+- **implementation**: profile body forbidden grows 8 → 13 items (now equals the launch boundary). Launch injection ≈ unchanged.
+- **release-handoff**: launch boundary forbidden grows 11 → 15 items (now equals the detailed profile list). Profile body ≈ unchanged.
+
+All other phases: byte-identical on both surfaces.
+
+---
+
+## 3. Tests (TDD)
+
+- `tests/test_phase_forbidden_ssot.py`:
+  - `load_phase_forbidden` covers every key in `PHASE_RULES` + `unknown` (no phase missing; no extra phase).
+  - `render_forbidden(["a","b"]) == "  - a\n  - b"` (exact shape match for injection).
+  - `compute_workflow_state(..., forbidden_by_phase=load_phase_forbidden(repo_root))` emits `PHASE_FORBIDDEN_ACTIONS` equal to the rendered JSON for a sample phase.
+  - `PHASE_RULES` no longer contains a `"forbidden"` key (regression guard against re-introducing the duplicate).
+- `tests/test_profile_forbidden_placeholder.py` (or extend an existing profile/prompt-metadata test):
+  - `implementation.md` and `release-handoff.md` contain `{{PHASE_FORBIDDEN_ACTIONS}}` and **no** hand-written bullet under the `Forbidden actions` header.
+  - the 5 other profiles contain neither a `Forbidden actions` block nor the placeholder (untouched).
+- Existing suite must stay green, especially `tests/test_workflow_phase_sequence.py` (update its `compute_workflow_state` calls to pass `forbidden_by_phase`), `validators/validate-workflow.sh`, and the launch-template render tests.
+
+---
+
+## 4. Non-goals
+
+- `allowed` outputs consolidation — left as-is, including the `release-handoff.md:54` "Allowed actions" block that also overlaps `PHASE_RULES` allowed. (Possible future P2-2b.)
+- Required/optional workers, `Purpose`, `Non-goals` — untouched (different parsers, no forbidden drift).
+- The 5 non-duplicated profiles' `Non-goals` prose — untouched.
+- No new third-party dependency (JSON via stdlib).
+- `runtime/` is never hand-edited; `npm run build` syncs the new JSON.
+
+---
+
+## 5. File summary
+
+| File | Change |
+|---|---|
+| `prompts/profiles/forbidden-actions.json` | **create** — the SSOT (7 phases + `unknown`) |
+| `scripts/okstra_ctl/workflow.py` | add `render_forbidden`, `load_phase_forbidden`; `compute_workflow_state` takes `forbidden_by_phase`; delete `PHASE_RULES[*]["forbidden"]` |
+| `scripts/okstra_ctl/run.py` | load `forbidden_by_phase`, pass to both `compute_workflow_state` calls, add `{{PHASE_FORBIDDEN_ACTIONS}}` to profile rendering |
+| `prompts/profiles/implementation.md` | replace forbidden bullets with placeholder |
+| `prompts/profiles/release-handoff.md` | replace forbidden bullets with placeholder |
+| `tests/test_phase_forbidden_ssot.py` | **create** |
+| `tests/test_profile_forbidden_placeholder.py` | **create** |
+| `tests/test_workflow_phase_sequence.py` | update `compute_workflow_state` calls |
+| `CHANGES.md`, plan doc | record |