okstra 0.102.2 → 0.102.3

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

@@ -1,493 +0,0 @@
-# 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를 복구하면 해소된다.