okstra 0.74.0 → 0.75.0

package/docs/superpowers/specs/2026-06-12-stage-discipline-rule-design.md

@@ -0,0 +1,108 @@
+# Stage discipline 규칙 — 선행 stage 동작 동결 설계
+
+- 날짜: 2026-06-12
+- 상태: 설계 승인됨 (구현 전)
+- 대상: `implementation` · `implementation-planning` 프로파일
+
+## 1. 배경과 목표
+
+implementation 은 stage-isolated 다 — 한 run = 한 stage 이고, dependent stage 는 선행(`depends-on`) stage 의 done commit 을 base 로 시작한다(`prompts/profiles/implementation.md:27`). 선행 stage 는 이미 conformance 를 통과해 `done` 으로 닫힌 상태인데, 이후 stage 가 그 코드의 **동작을 바꾸면** "verified-stays-verified" 불변식이 깨진다 — 닫힌 stage 가 조용히 회귀한다.
+
+목표: "선행 stage 가 추가·수정한 코드의 기능(동작)은 이후 stage 에서 변경하지 않는다" 라는 규율을 `implementation` 과 `implementation-planning` 양쪽에 도입하고, 이런 stage 규율을 **별도 단일 파일**로 관리한다.
+
+## 2. 결정 사항 (brainstorming 합의)
+
+| 항목 | 결정 |
+|---|---|
+| 규칙 파일 소유권 | okstra 내장 공유 파일 (모든 프로젝트 적용, okstra 레포에서 편집·전파) |
+| 강제 수준 | 선언 + 보고서 증거 (validator/wrapper sentinel 없음) |
+| 규칙 언어 | English (기존 Forbidden actions·stage-scope 규칙과 일관) |
+| executor 전사 포인터 | 둔다 (CLI executor 가 규칙을 받도록) |
+
+YAGNI 로 제외: validator/wrapper 강제, data.json 스키마 필드, 프로젝트별 override.
+
+## 3. 아키텍처 근거
+
+- 프로파일은 `{{INCLUDE:<name>}}` 로 공유 계약을 합친다 — resolver 는 임의 파일을 지원한다(`scripts/okstra_ctl/run.py:973` `_expand_profile_includes`, 재귀 depth ≤4, 누락 시 `PrepareError` fail-fast). 추가 코드 변경 없이 새 사이드카를 INCLUDE 할 수 있다.
+- `implementation-planning` 의 행위자는 lead/planner 본인이라 INCLUDE 로 직접 바인딩된다.
+- `implementation` 의 실제 행위자인 **executor(codex/gemini CLI)는 lead 컨텍스트를 공유하지 않는다**. 기존 계약은 lead 가 규칙을 executor 프롬프트에 **verbatim 전사**하게 한다(`prompts/profiles/_implementation-executor.md:27` "CLI executor transcription"). 따라서 implementation 규칙이 CLI executor 에 닿으려면 전사 포인터가 필요하다.
+- executor 사이드카(`_implementation-executor.md`)는 lead 가 Phase 5 에 raw 로 lazy-load 하며 `{{INCLUDE}}` resolver 를 거치지 않는다(`_implementation-executor.md:3`). 그래서 사이드카에는 규칙 **텍스트를 복사하지 않고** 단일 출처를 가리키는 **전사 지시 한 줄**만 둔다(DRY).
+
+## 4. 설계
+
+### 4.1 신규 단일 파일 `prompts/profiles/_stage-discipline.md` (SSOT)
+
+규칙의 유일한 출처. 핵심 원칙 + phase 별 적용 + 보고서 증거 절을 담는다. 전체 본문:
+
+```markdown
+<!--
+Shared stage-discipline rule. INCLUDEd by implementation-planning.md (binds the
+planner) and implementation.md (binds the lead). The implementation executor
+sidecar instructs the lead to transcribe this rule into a CLI executor prompt,
+since codex/gemini executors do not share lead context.
+
+Do NOT write the literal include directive token in this file's body — the
+resolver matches it anywhere and would recurse on this file itself.
+-->
+
+## Stage discipline — preceding stages are behavior-frozen
+
+A stage that is already `done` (a `depends-on` predecessor whose work is merged
+into this run's base) is **behavior-frozen**: code it added or modified keeps its
+existing behavior. Later stages MAY call, extend, or compose with that code, but
+MUST NOT change what it already does. This preserves the verified-stays-verified
+invariant — a completed, conformance-passed stage must not silently regress when
+a later stage runs.
+
+- **implementation-planning** — decompose stages forward-only. No stage's scope
+  may require altering an earlier stage's behavior; each stage builds additively
+  on its predecessors' Stage Exit Contracts. If delivering an increment would
+  force changing an earlier stage's behavior, that earlier stage was mis-scoped —
+  fold the change into that stage or re-partition; do not plan a later stage that
+  rewrites it.
+- **implementation** — the executor MUST NOT alter the behavior of any file added
+  or modified by a preceding done stage. Touching such a file to *extend* it (a
+  new branch, a new caller, an additive field) is allowed; changing its existing
+  behavior is not. If a plan step appears to require a behavior change to
+  prior-stage code, treat it as a planning defect: record the finding and route
+  to a new `implementation-planning` run — never silently rewrite it.
+  - **Report evidence (declaration-level).** When this stage modifies a file that
+    a preceding stage added or modified, the final report MUST record — in the
+    deliverable's existing edits / validation evidence section — which file, why
+    it was touched, and how the prior stage's behavior was preserved. Absent that
+    note, a reviewer treats a prior-stage edit as an unverified regression risk.
+```
+
+### 4.2 INCLUDE 배선
+
+- `prompts/profiles/implementation.md`: 기존 `{{INCLUDE:_common-contract.md}}`(line 17) 바로 다음 줄에 `{{INCLUDE:_stage-discipline.md}}` 추가.
+- `prompts/profiles/implementation-planning.md`: 기존 `{{INCLUDE:_common-contract.md}}`(line 10) 바로 다음 줄에 `{{INCLUDE:_stage-discipline.md}}` 추가.
+
+### 4.3 executor 전사 포인터
+
+`prompts/profiles/_implementation-executor.md` 의 기존 전사 규칙(`:27` "CLI executor transcription") 근처에 형제 bullet 한 줄 추가 (규칙 텍스트 복사 없음):
+
+```markdown
+- **Stage discipline transcription (when a preceding stage is `done`):** the lead
+  MUST transcribe the `Stage discipline` rule (from this run's rendered profile)
+  verbatim into the dispatched CLI executor prompt, so a codex/gemini executor
+  honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.
+```
+
+### 4.4 전파
+
+`tools/build.mjs` 가 `prompts/` → `runtime/` 를 동기화하고 install 이 사용자 머신으로 복사한다. INCLUDE resolver 가 임의 파일을 이미 지원하므로 추가 코드 변경은 없다.
+
+## 5. 테스트
+
+`tests/test_okstra_profile_includes.py` 확장:
+- `implementation.md` 렌더 결과에 `Stage discipline — preceding stages are behavior-frozen` 헤딩과 `behavior-frozen` 본문이 INCLUDE 로 들어오는지 단언.
+- `implementation-planning.md` 렌더 결과에 같은 규칙 텍스트가 들어오는지 단언.
+- `_stage-discipline.md` 파일 존재 + `implementation` / `implementation-planning` 두 프로파일에 INCLUDE 디렉티브가 있는지 단언 (executor 사이드카에는 전사 포인터 문자열이 있는지 단언).
+
+(누락 INCLUDE 는 `_expand_profile_includes` 가 이미 `PrepareError` 로 fail-fast.)
+
+## 6. 영향받지 않는 것
+
+- 다른 phase(`requirements-discovery` / `error-analysis` / `final-verification` / `release-handoff` / `improvement-discovery`)는 무변경 — 규칙은 두 프로파일에만 INCLUDE 된다.
+- data.json 스키마, validator, CLI 플래그, wizard 무변경.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.74.0",
-  "builtAt": "2026-06-11T18:11:19.238Z",
+  "package": "0.75.0",
+  "builtAt": "2026-06-11T19:32:02.652Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/_implementation-executor.md

@@ -25,6 +25,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
   - **Language-agnostic principles that ALWAYS bind (the TDD loop below MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability.
   - **Graceful degradation (codex / gemini executor runtimes, or any runtime where the `~/.claude/skills/okstra-coding-preflight/` files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: skill-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a skill read that did not happen.
   - **CLI executor transcription (BLOCKING when the executor provider is `codex` or `gemini`):** the executor CLI process does NOT share the lead's context — a gate that stays in lead memory never reaches it. The lead MUST copy this entire "Coding-conventions preflight" bullet tree (file-read instructions, project review rule packs, agnostic principles, graceful degradation) verbatim into the dispatched executor prompt body. Enforcement: the CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
+- **Stage discipline transcription (when a preceding stage is `done`):** the lead MUST transcribe the `Stage discipline` rule (from this run's rendered profile — the INCLUDEd `_stage-discipline.md` body) verbatim into the dispatched CLI executor prompt, so a codex/gemini executor honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.
 - **Non-interactive auto-execution (BLOCKING when the executor provider is `codex` or `gemini`).** A CLI executor runs head-less (`codex exec` / gemini equivalent) — there is no human at the keyboard. Skills loaded during the run (tdd, coding-preflight, and others) contain "get user approval", "state your plan to the user and wait", or "ask before proceeding" gates written for interactive sessions; in this run those gates are **already satisfied** by the upstream `implementation-planning` approval (the plan this stage executes was human-approved). The executor MUST NOT stop to request approval, MUST NOT end its turn after only producing a plan, and MUST carry the stage through end-to-end — RED → GREEN → refactor → per-step commits → `### Stage Carry Evidence`. The ONLY skill step to skip is the interactive user-approval prompt itself; every other skill rule (TDD discipline, conventions, real-IO isolation) still binds. The lead MUST transcribe this bullet verbatim into the dispatched CLI executor prompt (same reason as the preflight transcription rule above — the CLI process does not share lead context). Stopping early for approval in a head-less run is the observed empty-exit failure (exit 0, no diff): treat it as `contract-violated`.
 - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
   - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.

package/runtime/prompts/profiles/_stage-discipline.md

@@ -0,0 +1,36 @@
+<!--
+Shared stage-discipline rule. INCLUDEd by implementation-planning.md (binds the
+planner) and implementation.md (binds the lead). The implementation executor
+sidecar instructs the lead to transcribe this rule into a CLI executor prompt,
+since codex/gemini executors do not share lead context.
+
+Do NOT write the literal include directive token in this file's body — the
+resolver matches it anywhere and would recurse on this file itself.
+-->
+
+## Stage discipline — preceding stages are behavior-frozen
+
+A stage that is already `done` (a `depends-on` predecessor whose work is merged
+into this run's base) is **behavior-frozen**: code it added or modified keeps its
+existing behavior. Later stages MAY call, extend, or compose with that code, but
+MUST NOT change what it already does. This preserves the verified-stays-verified
+invariant — a completed, conformance-passed stage must not silently regress when
+a later stage runs.
+
+- **implementation-planning** — decompose stages forward-only. No stage's scope
+  may require altering an earlier stage's behavior; each stage builds additively
+  on its predecessors' Stage Exit Contracts. If delivering an increment would
+  force changing an earlier stage's behavior, that earlier stage was mis-scoped —
+  fold the change into that stage or re-partition; do not plan a later stage that
+  rewrites it.
+- **implementation** — the executor MUST NOT alter the behavior of any file added
+  or modified by a preceding done stage. Touching such a file to *extend* it (a
+  new branch, a new caller, an additive field) is allowed; changing its existing
+  behavior is not. If a plan step appears to require a behavior change to
+  prior-stage code, treat it as a planning defect: record the finding and route
+  to a new `implementation-planning` run — never silently rewrite it.
+  - **Report evidence (declaration-level).** When this stage modifies a file that
+    a preceding stage added or modified, the final report MUST record — in the
+    deliverable's existing edits / validation evidence section — which file, why
+    it was touched, and how the prior stage's behavior was preserved. Absent that
+    note, a reviewer treats a prior-stage edit as an unverified regression risk.

package/runtime/prompts/profiles/implementation-planning.md

@@ -8,6 +8,7 @@
 - Optional workers (opt-in via `--workers`):
   - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
+{{INCLUDE:_stage-discipline.md}}
 - Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
   - Apply the shared reporter-confirmation precondition exactly as written. In this phase, unresolved `intent-check:` / `conversion-block:` rows use `Blocks=approval`; the operator cannot flip the approval frontmatter to `approved: true` until those rows are resolved.
   - never plan around an unconfirmed `intent-inference` augmentation as if it were a settled requirement. After the precondition runs, a `[CONFIRMED …]` marker on the matching `intent-check:` row is the signal that the inference can be treated as settled; otherwise it remains a `Blocks=approval` clarification item per the precondition's `skipped` branch.

package/runtime/prompts/profiles/implementation.md

@@ -15,6 +15,7 @@
   - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
   - Wherever this profile mentions the `Executor`, it refers to the role bound above. The other two providers in the roster (`claude` / `codex` / `gemini` minus the executor) are dispatched as **verifiers only** for this run and remain strictly read-only.
 {{INCLUDE:_common-contract.md}}
+{{INCLUDE:_stage-discipline.md}}
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
   - that file's YAML frontmatter MUST carry `approved: true`. report-writer emits `approved: false` by default; the user flips it to `true` to authorise this run. Free-form approvals such as "lgtm" / "go ahead" / paraphrased confirmations are NOT accepted; re-edit the plan file's frontmatter to `approved: true` before invoking implementation, or pass `--approve` so the CLI flips it on the user's behalf (`okstra_ctl.run._apply_cli_approval`).

package/src/install.mjs

@@ -167,6 +167,34 @@ async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
   return { copied, skipped, missingSource };
 }
 
+// Single-file variant of copyTreeIfChanged, used for the lead `okstra` skill
+// whose source is one file (agents/SKILL.md) rather than a skill directory.
+async function copyFileIfChanged(src, dst, opts) {
+  const { refresh = false, dryRun = false, mode } = opts ?? {};
+  let srcBuf;
+  try {
+    srcBuf = await fs.readFile(src);
+  } catch {
+    return { copied: 0, skipped: 0, missingSource: true };
+  }
+  let needsCopy = refresh;
+  if (!needsCopy) {
+    try {
+      const [srcHash, dstHash] = await Promise.all([hashFile(src), hashFile(dst)]);
+      needsCopy = srcHash !== dstHash;
+    } catch {
+      needsCopy = true;
+    }
+  }
+  if (!needsCopy) return { copied: 0, skipped: 1, missingSource: false };
+  if (dryRun) {
+    process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
+    return { copied: 1, skipped: 0, missingSource: false };
+  }
+  await writeFileAtomic(dst, srcBuf, mode);
+  return { copied: 1, skipped: 0, missingSource: false };
+}
+
 async function ensureSymlink(target, linkPath, opts) {
   const { dryRun = false } = opts ?? {};
   try {
@@ -244,7 +272,8 @@ async function installLinkMode(repoPath, paths, opts) {
   }
 
   const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
-  await writeSkillsManifest(paths.home, skillResult.installed, { dryRun });
+  const leadSkillResult = await installLeadSkillLink(repoAbs, { dryRun, quiet });
+  await writeSkillsManifest(paths.home, [...skillResult.installed, ...leadSkillResult], { dryRun });
 
   const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
@@ -487,6 +516,43 @@ async function installSkillsLink(repoAbs, opts) {
   return { installed: names };
 }
 
+// The lead `okstra` skill source is agents/SKILL.md (frontmatter `name: okstra`);
+// it doubles as the lead agent contract, so it lives under agents/ rather than
+// skills/. Claude Code only discovers skills at ~/.claude/skills/<name>/SKILL.md,
+// so it must be installed there as its own skill dir — otherwise install ships
+// every okstra-* helper skill but not the lead skill, and edits to agents/SKILL.md
+// never reach the running lead.
+const LEAD_SKILL_NAME = "okstra";
+
+async function installLeadSkillCopy(runtimeRoot, opts) {
+  const { refresh, dryRun, quiet } = opts;
+  const src = join(runtimeRoot, "agents", "SKILL.md");
+  const dst = join(CLAUDE_SKILLS_DIR, LEAD_SKILL_NAME, "SKILL.md");
+  const r = await copyFileIfChanged(src, dst, { refresh, dryRun, mode: 0o644 });
+  if (r.missingSource) {
+    if (!quiet) process.stdout.write("  skills/okstra: runtime/agents/SKILL.md missing — skipped\n");
+    return [];
+  }
+  if (!quiet) {
+    process.stdout.write(`  skills/okstra: ${r.copied ? "copied" : "unchanged"} -> ${dst}\n`);
+  }
+  return [LEAD_SKILL_NAME];
+}
+
+async function installLeadSkillLink(repoAbs, opts) {
+  const { dryRun, quiet } = opts;
+  const src = join(repoAbs, "agents", "SKILL.md");
+  if (!(await fileExists(src))) {
+    if (!quiet) process.stdout.write("  skills/okstra: <repo>/agents/SKILL.md missing — skipped\n");
+    return [];
+  }
+  const dst = join(CLAUDE_SKILLS_DIR, LEAD_SKILL_NAME, "SKILL.md");
+  if (!dryRun) await fs.mkdir(join(CLAUDE_SKILLS_DIR, LEAD_SKILL_NAME), { recursive: true });
+  const action = await ensureSymlink(src, dst, { dryRun });
+  if (!quiet) process.stdout.write(`  skills/okstra/SKILL.md: ${action}\n`);
+  return [LEAD_SKILL_NAME];
+}
+
 function parseInstallArgs(args) {
   const result = {
     dryRun: false,
@@ -623,7 +689,12 @@ export async function runInstall(args) {
   }
 
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
-  await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
+  const leadSkillResult = await installLeadSkillCopy(runtimeRoot, opts);
+  await writeSkillsManifest(
+    paths.home,
+    [...skillResult.installed, ...leadSkillResult],
+    { dryRun: opts.dryRun },
+  );
 
   const agentResult = await installAgentsCopy(runtimeRoot, opts);
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });

package/src/uninstall.mjs

@@ -18,6 +18,7 @@ const BIN_ENTRYPOINTS = [
 ];
 
 const FALLBACK_SKILL_NAMES = [
+  "okstra",
   "okstra-setup",
   "okstra-brief",
   "okstra-run",