okstra 0.77.0 → 0.78.1

package/docs/superpowers/plans/2026-06-13-repo-risk-hardening.md

@@ -0,0 +1,493 @@
+# repo 유지보수 리스크 하드닝 구현 계획
+
+> **For agentic workers:** 이 문서는 `okstra` 저장소 자체의 유지보수 리스크를 줄이기 위한 구현 계획이다. 단계별 체크박스(`- [ ]`)를 갱신하며 진행한다. `runtime/`은 build output이므로 직접 수정하지 않는다.
+
+**Goal:** 문서 drift, generated runtime 직접 수정, profile/workflow/worker contract 불일치, 로컬/CI 검증 경로 부재로 생기는 유지보수 리스크를 낮춘다.
+
+**Architecture:** 구조를 크게 바꾸지 않는 P0 안정화부터 적용한다. `package.json`을 version SSOT로 두고, `tools/build.mjs`가 `runtime/DO_NOT_EDIT.md`를 생성하며, pytest contract tests가 `workflow.py` ↔ `prompts/profiles/*.md` ↔ `workers.py`의 최소 일관성을 검증한다. CI는 같은 명령을 실행해 regression을 빠르게 잡는다.
+
+**Tech Stack:** Node.js 22+, Python 3.11+, pytest, GitHub Actions.
+
+---
+
+## Scope
+
+### P0 — 이번 구현 범위
+
+1. 문서의 고정 package version 제거
+2. `runtime/DO_NOT_EDIT.md` build-time 생성
+3. repo contract pytest 추가
+4. `package.json` check scripts 추가
+5. GitHub Actions CI 추가
+6. `CHANGES.md`에 사용자 영향 기록
+
+### P1 — 후속 개선
+
+1. [x] `okstra doctor --phase <phase>` 추가
+2. [x] contributor change matrix 문서 추가
+3. [x] final-report template/schema/validator contract test 강화
+
+### P2 — 구조 개선 후보
+
+1. [x] command metadata registry 도입 (P2-1)
+2. [x] profile meta yaml 도입 → forbidden actions JSON SSOT로 구현 (P2-2; spec: docs/superpowers/specs/2026-06-13-forbidden-actions-ssot-design.md). 범위는 forbidden만(allowed/workers/Non-goals 제외).
+3. [x] forbidden action post-run audit 자동화 (P2-3)
+
+---
+
+## Non-goals
+
+- `prepare_task_bundle()` orchestration 구조 변경 없음
+- phase 추가/삭제 없음
+- worker roster 정책 변경 없음
+- `runtime/` 산출물을 git tracked file로 만들지 않음
+- `doctor --phase`는 이번 P0 구현에 포함하지 않음
+
+---
+
+## Task 1: 문서 drift 제거
+
+**Files:**
+
+- Modify: `docs/project-structure-overview.md`
+
+**Implementation:**
+
+- [x] `package version: \`0.50.0\`` 같은 고정 semver를 제거한다.
+- [x] 다음 중 하나로 변경한다.
+
+```md
+- package version: see `package.json`
+```
+
+또는 version line 자체를 제거한다.
+
+**Rationale:**
+
+`package.json`이 version SSOT다. 문서에 release version을 수동으로 넣으면 release마다 drift가 발생한다.
+
+**Validation:**
+
+- [x] 신규 `tests/test_repo_contracts.py`에서 문서 내 고정 package version을 금지한다.
+
+---
+
+## Task 2: generated `runtime/` 경고 파일 생성
+
+**Files:**
+
+- Modify: `tools/build.mjs`
+
+**Implementation:**
+
+- [x] `writeDoNotEditNotice()` 함수를 추가한다.
+- [x] build sequence 마지막에 `runtime/DO_NOT_EDIT.md`를 생성한다.
+- [x] 파일 내용은 `runtime/`이 generated output이고 원본 수정 위치가 어디인지 명시한다.
+
+Suggested content:
+
+```md
+# Do not edit runtime/
+
+This directory is generated by `npm run build`.
+
+Edit source files under:
+
+- scripts/
+- skills/
+- agents/
+- prompts/
+- schemas/
+- templates/
+- validators/
+
+Then run:
+
+```bash
+npm run build
+```
+
+Direct edits under runtime/ are overwritten.
+```
+
+**Important:**
+
+`runtime/*`은 `.gitignore`로 ignore된다. `runtime/DO_NOT_EDIT.md`를 직접 커밋하지 말고 build 산출물로만 만든다.
+
+**Validation:**
+
+```bash
+npm run build
+test -f runtime/DO_NOT_EDIT.md
+```
+
+---
+
+## Task 3: repo contract tests 추가
+
+**Files:**
+
+- Add: `tests/test_repo_contracts.py`
+
+**Implementation:**
+
+- [x] repo root를 기준으로 `scripts/`를 `sys.path`에 추가한다.
+- [x] `okstra_ctl.workflow`와 `okstra_ctl.workers`를 import한다.
+- [x] 아래 contract를 검증한다.
+
+### Contract 3.1 — workflow phase와 profile 파일 일치
+
+- [x] `PHASE_SEQUENCE`의 모든 phase에 `prompts/profiles/<phase>.md`가 존재한다.
+- [x] `PHASE_RULES`의 모든 non-private task type에 profile 파일이 존재한다.
+- [x] `improvement-discovery` profile도 존재한다.
+
+### Contract 3.2 — worker roster 일관성
+
+- [x] `release-handoff`는 required worker가 없어야 한다.
+- [x] `release-handoff` 외 profile은 required worker가 있어야 한다.
+- [x] required worker는 모두 `ALLOWED_WORKERS` 안에 있어야 한다.
+- [x] optional worker도 모두 `ALLOWED_WORKERS` 안에 있어야 한다.
+- [x] required worker 중복이 없어야 한다.
+- [x] optional worker 중복이 없어야 한다.
+
+### Contract 3.3 — docs version drift 방지
+
+- [x] `docs/project-structure-overview.md`에 `package version: 0.0.0` 형태의 고정 semver가 남지 않아야 한다.
+
+Suggested regex:
+
+```python
+r"package version:\s*`?\d+\.\d+\.\d+`?"
+```
+
+**Validation:**
+
+```bash
+python3 -m pytest tests/test_repo_contracts.py -q
+```
+
+---
+
+## Task 4: package scripts 정리
+
+**Files:**
+
+- Modify: `package.json`
+
+**Implementation:**
+
+- [x] 아래 scripts를 추가한다.
+
+```json
+{
+  "test:py": "python3 -m pytest tests/",
+  "test:workflow": "bash validators/validate-workflow.sh",
+  "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow"
+}
+```
+
+**Rationale:**
+
+로컬과 CI가 같은 검증 명령을 사용하게 만든다.
+
+**Validation:**
+
+```bash
+npm run check
+```
+
+---
+
+## Task 5: CI workflow 추가
+
+**Files:**
+
+- Add: `.github/workflows/ci.yml`
+
+**Implementation:**
+
+- [x] `pull_request`와 `main` push에서 실행한다.
+- [x] Node 22와 Python 3.11을 설정한다.
+- [x] pytest를 설치한다.
+- [x] `npm run check`를 실행한다.
+
+Suggested workflow:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Python test dependencies
+        run: python -m pip install pytest
+
+      - name: Run full check
+        run: npm run check
+```
+
+**Note:**
+
+`git diff --exit-code runtime/`는 이 저장소에 적합하지 않다. `runtime/*`은 gitignored build output이므로 CI는 build 성공과 테스트 통과를 검증한다.
+
+---
+
+## Task 6: 변경 이력 기록
+
+**Files:**
+
+- Modify: `CHANGES.md`
+
+**Implementation:**
+
+- [x] `2026-06-13` 섹션에 아래 항목을 추가한다.
+
+```md
+### chore(repo): 문서 drift와 runtime 수정 실수 방지 장치 추가
+
+- **배경**: package version 같은 수동 문서 값과 generated `runtime/` 경계가 drift / 실수 위험을 만들 수 있었다.
+- **해결**: 문서의 고정 version을 제거하고, build 시 `runtime/DO_NOT_EDIT.md`를 생성하며, workflow/profile contract test와 CI check를 추가했다.
+- 사용자 영향: 기여자가 잘못된 파일을 수정하거나 profile/worker 계약을 깨뜨리는 변경을 더 빨리 발견할 수 있다.
+```
+
+---
+
+## Final validation
+
+Run in order:
+
+```bash
+npm run build
+python3 -m pytest tests/test_repo_contracts.py -q
+npm run test:js
+python3 -m pytest tests/
+bash validators/validate-workflow.sh
+npm run check
+```
+
+Expected result: all pass.
+
+---
+
+## Rollback plan
+
+If CI/test failures are unrelated or too broad:
+
+1. Keep Task 1 and Task 3 if they pass independently.
+2. Revert `.github/workflows/ci.yml` first if GitHub Actions environment issues appear.
+3. Revert `package.json` `check` script only if local command composition is problematic.
+4. Do not modify `runtime/` manually; rerun `npm run build` after any `tools/build.mjs` revert.
+
+---
+
+## Follow-up design notes
+
+### P1. `okstra doctor --phase <phase>`
+
+Potential checks:
+
+| Phase | Checks |
+|---|---|
+| `implementation` | git repo, worktree support, approved-plan marker, worker agents |
+| `final-verification` | worktree lookup, validation command availability, final-report prerequisites |
+| `release-handoff` | `gh auth status`, clean git tree, remote exists, non-base current branch |
+| `improvement-discovery` | gemini worker installed, lens whitelist importable |
+
+### P1. contributor change matrix
+
+Add `docs/contributor-change-matrix.md` with rows like:
+
+| Change | Must update | Tests |
+|---|---|---|
+| Add CLI flag | `src/*`, `scripts/okstra_ctl/run.py`, `docs/kr/cli.md`, wizard prompts | JS + pytest |
+| Add phase | `workflow.py`, `prompts/profiles`, validators, tests | workflow validator |
+| Change worker roster | profile `Required workers`, `workers.py`, tests | worker contract tests |
+| Change report section | schema, template, renderer, validator | final-report tests |
+
+### P2. profile meta yaml
+
+Possible future shape:
+
+```yaml
+taskType: implementation
+requiredWorkers:
+  - claude
+  - codex
+  - report-writer
+optionalWorkers:
+  - gemini
+executorAllowed:
+  - claude
+  - codex
+  - gemini
+```
+
+For now, markdown `Required workers:` remains the authority.
+
+---
+
+## P2 구현 계획 (P2-1 + P2-3 먼저, 이후 P2-2)
+
+조사 근거: `agent://CommandRegistryProbe`, `agent://ForbiddenAuditProbe`, `agent://ProfileMetaProbe`.
+P2-2(profile meta yaml)는 파서 3개 + `PHASE_RULES`↔profile 산문의 기존 divergence reconcile 이 필요해 1차에서는 보류했으나, 이후 forbidden 범위로 좁혀 JSON SSOT(docs/superpowers/specs/2026-06-13-forbidden-actions-ssot-design.md)로 구현 완료했다.
+
+### P2-1: command metadata registry
+
+**Files:**
+- Create: `src/cli-registry.mjs` — `COMMAND_REGISTRY` 배열 + 파생 `COMMANDS`(Map) + 파생 `USAGE`(string).
+- Modify: `bin/okstra` — 인라인 `COMMANDS`/`USAGE` 제거, `src/cli-registry.mjs` 에서 import.
+- Test: `tests-js/cli-registry.test.mjs`.
+
+**Registry entry shape:**
+```js
+// { name, module, export: exportName, category, summary }
+// category ∈ { "admin", "introspection" }
+// summary: string[]  (1번째=요약 첫 줄, 이후=연속행. 들여쓰기 미포함)
+```
+- 디스플레이 순서 = 현재 USAGE 순서(admin 11개, introspection 16개)를 verbatim 보존.
+- `export` 필드로 install 3종(`runInstall`/`runEnsureInstalled`/`runUninstall`) 흡수, 나머지는 `run`.
+- USAGE 렌더: static preamble/footer 유지, 각 행 `"  " + name.padEnd(23) + summary[0]`, 연속행 `" ".repeat(25) + line` (현재 컬럼=25 실측).
+- `COMMANDS` = `new Map(COMMAND_REGISTRY.map(c => [c.name, () => import(c.module).then(m => m[c.export])]))`.
+- per-command `--help`(모듈 소유)와 외부 doc table(Option D)은 범위 밖.
+
+**TDD:**
+1. RED `tests-js/cli-registry.test.mjs`:
+   - `buildCommandsMap()` 키 집합 == `COMMAND_REGISTRY` name 집합.
+   - 모든 registry name 이 `USAGE` 에 등장, admin/introspection 헤더 아래 개수가 category 카운트와 일치.
+   - name 중복 없음, 각 name 은 정확히 1개 category.
+   - byte-anchor: `USAGE` 에 `codex-run` / `codex-dispatch` 의 현재 요약 첫 줄 정확히 포함(기존 top-level help 테스트와 정합).
+2. GREEN: `src/cli-registry.mjs` 구현 후 `bin/okstra` 가 import 하도록 교체.
+3. 기존 `tests-js/*.test.mjs` (codex-run/codex-dispatch top-level help, cli-script-wrappers) 회귀 통과.
+
+### P2-3: forbidden action post-run audit 자동화
+
+**Files:**
+- Create: `validators/forbidden_actions.py` — per-phase 구조화 deny-list(regex SSOT) + `scan_forbidden_actions(...)`.
+- Modify: `validators/validate-run.py` — `_validate_session_conformance` 옆(`if task_type:` 블록, line ~2230)에 `_validate_forbidden_actions(...)` hook, 실패는 `forbidden-action: ` 접두로 fold.
+- Test: `tests/test_validate_forbidden_actions.py`.
+
+**Deny-list SSOT (보수적 — 맥락 무관 항상 위반만):**
+```python
+# 모든 phase 공통: okstra 어느 phase 도 publish/deploy/force-push 안 함
+_UNIVERSAL = [
+    ("npm publish", r"\bnpm\s+publish\b"),
+    ("cargo publish", r"\bcargo\s+publish\b"),
+    ("pip publish", r"\bpip\s+publish\b"),
+    ("twine upload", r"\btwine\s+upload\b"),
+    ("gh release", r"\bgh\s+release\s+(create|edit)\b"),
+    ("docker push", r"\bdocker\s+push\b"),
+    ("terraform apply", r"\bterraform\s+apply\b"),
+    ("kubectl apply", r"\bkubectl\s+apply\b"),
+    ("git push --force", r"\bgit\s+push\b.*--force(-with-lease)?\b"),
+]
+# release-handoff 는 feature-branch `git push` 허용 → bare push 는 비-handoff phase 에서만 위반
+_NON_HANDOFF_PUSH = ("git push", r"\bgit\s+push\b")
+```
+- phase → 적용 패턴: 모든 phase 에 `_UNIVERSAL`; `release-handoff` 외 phase 에 `_NON_HANDOFF_PUSH` 추가.
+
+**Scanner:**
+- `find_claude_team_sessions(project_root, resolve_team_name(team_state), lead_sid, projects_root)` 로 lead+worker 세션 jsonl 발견(conformance seam 재사용).
+- `resolve_run_window` 로 [since, until] 스코프. assistant 레코드 & `not isSidechain` 만, `tool_use` && `name == "Bash"` 의 `input.command` 를 패턴 매칭.
+- 위반 1건당 `f"{label} 명령이 {agent} 세션에서 실행됨: {command[:120]}"`.
+- codex/gemini wrapper 의 셸 명령은 claude jsonl 밖 → 문서화된 한계(스캐너는 claude lead + claude worker 세션만).
+
+**TDD:**
+1. RED `tests/test_validate_forbidden_actions.py` (conformance 테스트의 Fixture 패턴 차용 — `claude_projects_dir` 주입, team-needle 태그 jsonl):
+   - implementation 세션에 `git push origin x` Bash → 위반 1건.
+   - implementation 세션에 `npm publish` → 위반.
+   - release-handoff 세션에 `git push -u origin feat` → 위반 없음(허용).
+   - release-handoff 세션에 `git push --force origin feat` → 위반(force).
+   - 깨끗한 세션(`npm test`, `git status`) → 위반 없음.
+   - 패턴이 prompt/text 블록에만 있고 Bash tool_use 가 아니면 → 위반 없음(false-positive 가드).
+2. GREEN: `validators/forbidden_actions.py` 구현 + `validate-run.py` hook.
+3. 회귀: `tests/test_validate_session_conformance.py`, `tests/test_validate_run_*.py` 통과.
+
+### Verification
+```bash
+node --test tests-js/cli-registry.test.mjs
+python3 -m pytest tests/test_validate_forbidden_actions.py -q
+npm run check
+```
+
+---
+
+## Execution notes — 2026-06-13
+
+Implemented P0 scope.
+
+Initial validation run:
+
+```bash
+python3 -m pytest tests/test_repo_contracts.py -q
+npm run build
+npm run test:js
+bash validators/validate-workflow.sh
+```
+
+Observed result: all commands above passed. `npm run check` was also started, but the local harness killed it after 600 seconds while the full pytest suite was still progressing; no test failure was observed before timeout.
+
+Follow-up validation run:
+
+```bash
+python3 -m pytest tests/test_okstra_ctl_show_open.py::test_open_prints_absolute_final_report_path -q
+npm run check
+```
+
+Observed result: both commands passed. The first full `npm run check` attempt exposed an ambient `EDITOR` leak in `tests/test_okstra_ctl_show_open.py`; the test helper now removes inherited `EDITOR` unless a test explicitly passes it.
+
+P1 follow-up:
+
+```bash
+python3 -m pytest tests/test_okstra_doctor_phase.py -q
+node --test tests-js/doctor-runtime.test.mjs
+```
+
+Observed result: both targeted checks passed after adding `okstra doctor --phase <phase>` readiness diagnostics.
+
+P1 completion:
+
+```bash
+python3 -m pytest tests/test_repo_contracts.py tests/test_final_report_contracts.py tests/test_schema_excerpt.py tests/test_final_report_stage_reports_render.py tests/test_validate_final_verification_consistency.py -q
+npm run check
+```
+
+Observed result: focused suite reported 51 passed; full `npm run check` completed build, JS tests, Python tests, and workflow validator successfully.
+
+P2 completion (P2-1 + P2-3; P2-2 보류):
+
+```bash
+node --test tests-js/cli-registry.test.mjs
+python3 -m pytest tests/test_validate_forbidden_actions.py -q
+npm run check
+```
+
+Observed result: registry 5 passed, forbidden-actions 8 passed; full `npm run check` = JS 59 passed, Python 1558 passed/2 skipped, workflow validator success. `okstra --help` byte-identical (registry는 단일 SSOT로 COMMANDS/USAGE 파생). Reviewer APPROVED after one CHANGES_REQUESTED round (force-push `-f` 단축 플래그 미탐 등 6건 반영).
+
+P2-2 completion (forbidden-actions JSON SSOT):
+
+```bash
+python3 -m pytest tests/test_phase_forbidden_ssot.py tests/test_profile_forbidden_placeholder.py tests/test_workflow_phase_sequence.py -q
+bash validators/validate-workflow.sh
+```
+
+Observed result: SSOT/placeholder/workflow 단위 30 passed; workflow validator success(렌더된 launch 경계 forbidden이 JSON에서 주입됨 확인); implementation/release-handoff profile placeholder 치환 검증(13/11 bullets, leftover 없음). Reviewer APPROVED (P3 docstring drift 1건 반영). 단, `npm run check`의 `tests/test_context_cost.py` 2건은 **환경성 실패**(codex/gemini-worker가 빌드 생성물이라 repo static 부재 + ~/.claude 미설치) — 이 diff와 무관하며 `okstra install`로 ~/.claude agents를 복구하면 해소된다.

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 |