okstra 0.101.1 → 0.102.1

package/docs/superpowers/plans/2026-06-24-okstra-container-build-rename.md

@@ -0,0 +1,525 @@
+# okstra-container-build Rename Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Rename the public okstra container skill from `okstra-container` to `okstra-container-build` without changing the `okstra container` CLI or container runtime trace names.
+
+**Architecture:** The public skill surface remains driven by `src/lib/skill-catalog.mjs` and `.claude-plugin/plugin.json`. Install copy/link mode reads skill directories by exact `USER_SKILL_NAMES`, so the source directory and frontmatter must move together. Upgrade cleanup uses an exact obsolete-name allowlist so old `/okstra-container` directories are pruned without wildcard deletion.
+
+**Tech Stack:** Node.js ES modules, Python pytest contract tests, Markdown skill/docs sources, `tools/build.mjs` runtime sync.
+
+## Global Constraints
+
+- Public skill name becomes exactly `okstra-container-build`.
+- Old public skill name `okstra-container` is removed from installed skill manifests and pruned from agent skill homes.
+- CLI command remains exactly `okstra container <up|status|logs|stop-watcher|down>`.
+- Runtime tmux/docker trace prefix remains exactly `okstra-container-<slug>`.
+- Do not wildcard-delete `okstra-*`; cleanup must use exact names only.
+- Do not hand-edit `runtime/`; run `npm run build` after source edits.
+- Preserve historical `CHANGES.md` / `CHANGELOG.md` entries except adding a new current entry.
+
+---
+
+## File Structure
+
+- `skills/okstra-container-build/SKILL.md`: renamed public skill source. Keeps `okstra container ...` command examples.
+- `src/lib/skill-catalog.mjs`: public/obsolete skill name SSOT.
+- `.claude-plugin/plugin.json`: secondary skills channel manifest.
+- `src/commands/lifecycle/install.mjs`: install copy/link exact-name prune path.
+- `src/commands/lifecycle/uninstall.mjs`: legacy fallback cleanup names.
+- `tests-js/skill-catalog.test.mjs`: catalog/plugin/obsolete-name contract.
+- `tests-js/install-runtime.test.mjs`: install target manifest plus old skill prune regression.
+- `tests-js/uninstall-runtime.test.mjs`: manifest-missing fallback cleanup regression.
+- `tests/contract/test_docs_runtime_contract.py`: plugin manifest contract mirror.
+- `README.md`, `README.kr.md`, `docs/kr/architecture.md`, `docs/project-structure-overview.md`, `docs/kr/container.md`: live user/internal docs.
+- `docs/for-ai/README.md`, `docs/for-ai/skills/okstra-container-build.md`, `docs/for-ai/skills/okstra-inspect.md`: AI routing manuals.
+- `prompts/profiles/_implementation-deliverable.md`, `prompts/profiles/final-verification.md`: live phase prompt references.
+- `docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md`, `docs/superpowers/plans/2026-06-24-manual-user-test-section.md`: active manual-test design/plan references.
+- `CHANGES.md`: current user-visible change entry.
+
+### Task 1: Public Skill Contract Rename
+
+**Files:**
+- Move: `skills/okstra-container` -> `skills/okstra-container-build`
+- Modify: `skills/okstra-container-build/SKILL.md`
+- Modify: `src/lib/skill-catalog.mjs`
+- Modify: `.claude-plugin/plugin.json`
+- Modify: `src/commands/lifecycle/install.mjs`
+- Modify: `tests-js/skill-catalog.test.mjs`
+- Modify: `tests/contract/test_docs_runtime_contract.py`
+
+**Interfaces:**
+- Produces: `USER_SKILL_NAMES` contains `okstra-container-build`, not `okstra-container`.
+- Produces: `OBSOLETE_SKILL_NAMES` contains old `okstra-container`.
+- Produces: plugin manifest entry `./skills/okstra-container-build`.
+
+- [ ] **Step 1: Write failing catalog contract tests**
+
+Update `tests-js/skill-catalog.test.mjs` import and tests to this shape:
+
+```js
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+  OBSOLETE_SKILL_NAMES,
+  USER_SKILL_NAMES,
+} from "../src/lib/skill-catalog.mjs";
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+test("public skill catalog matches Claude plugin manifest", () => {
+  const plugin = readJson(".claude-plugin/plugin.json");
+  const pluginNames = plugin.skills.map((entry) => entry.replace("./skills/", ""));
+  assert.deepEqual(pluginNames, [...USER_SKILL_NAMES]);
+});
+
+test("obsolete skill names do not overlap public skills", () => {
+  for (const name of OBSOLETE_SKILL_NAMES) {
+    assert.equal(USER_SKILL_NAMES.includes(name), false, name);
+  }
+});
+
+test("container skill rename keeps old public name prunable", () => {
+  assert.equal(USER_SKILL_NAMES.includes("okstra-container-build"), true);
+  assert.equal(USER_SKILL_NAMES.includes("okstra-container"), false);
+  assert.equal(OBSOLETE_SKILL_NAMES.includes("okstra-container"), true);
+});
+```
+
+Update `tests/contract/test_docs_runtime_contract.py` public skill list:
+
+```python
+USER_FACING_PLUGIN_SKILLS = [
+    "./skills/okstra-setup",
+    "./skills/okstra-brief",
+    "./skills/okstra-run",
+    "./skills/okstra-memory",
+    "./skills/okstra-inspect",
+    "./skills/okstra-schedule",
+    "./skills/okstra-container-build",
+]
+```
+
+- [ ] **Step 2: Run failing contract tests**
+
+Run:
+
+```bash
+node --test tests-js/skill-catalog.test.mjs
+python3 -m pytest tests/contract/test_docs_runtime_contract.py::test_plugin_manifest_exposes_only_user_facing_skills -q
+```
+
+Expected: FAIL because `OBSOLETE_SKILL_NAMES` is not exported yet and `.claude-plugin/plugin.json` still lists `./skills/okstra-container`.
+
+- [ ] **Step 3: Rename skill source and public catalog**
+
+Run:
+
+```bash
+git mv skills/okstra-container skills/okstra-container-build
+```
+
+Edit `skills/okstra-container-build/SKILL.md` frontmatter/title:
+
+```markdown
+---
+name: okstra-container-build
+description: |
+  Use to bring up, inspect, or tear down the okstra user-test container runtime for an implementation task — the docker-compose group okstra deploys from a task's worktree so a human can poke at the running build. Trigger words include "okstra container", "okstra container up", "okstra container down", "컨테이너 띄워", "컨테이너 올려", "컨테이너 내려", "컨테이너 상태", "컨테이너 로그", "유저 테스트 환경", "user test environment", "docker compose 띄워줘", "이 task 컨테이너로 띄워", "watcher 멈춰", "stop watcher", "감시 종료".
+---
+
+# OKSTRA Container Build
+```
+
+Edit `src/lib/skill-catalog.mjs` public and obsolete exports:
+
+```js
+export const USER_SKILL_NAMES = Object.freeze([
+  "okstra-setup",
+  "okstra-brief",
+  "okstra-run",
+  "okstra-memory",
+  "okstra-inspect",
+  "okstra-schedule",
+  "okstra-container-build",
+]);
+
+// Names okstra used to install as skills before they were renamed or moved
+// into the runtime resource tree. Install prunes these exact directories from
+// each target skill home so upgrades do not leave stale slash commands behind.
+// Exact-name only — never wildcard.
+export const OBSOLETE_SKILL_NAMES = Object.freeze([
+  "okstra",
+  "okstra-context-loader",
+  "okstra-team-contract",
+  "okstra-convergence",
+  "okstra-report-writer",
+  "okstra-coding-preflight",
+  "okstra-container",
+]);
+
+export function userSkillNames() {
+  return [...USER_SKILL_NAMES];
+}
+
+export function obsoleteSkillNames() {
+  return [...OBSOLETE_SKILL_NAMES];
+}
+```
+
+Edit `.claude-plugin/plugin.json`:
+
+```json
+{
+  "name": "okstra",
+  "description": "Multi-agent cross-verification orchestrator (Claude lead + Codex/Antigravity workers).",
+  "skills": [
+    "./skills/okstra-setup",
+    "./skills/okstra-brief",
+    "./skills/okstra-run",
+    "./skills/okstra-memory",
+    "./skills/okstra-inspect",
+    "./skills/okstra-schedule",
+    "./skills/okstra-container-build"
+  ]
+}
+```
+
+Edit `src/commands/lifecycle/install.mjs` import and prune helper names:
+
+```js
+import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
+```
+
+```js
+const pruned = await pruneObsoleteSkills(target, opts);
+```
+
+```js
+// Remove former skill directories left by older installs. Exact-name only
+// (OBSOLETE_SKILL_NAMES) — never wildcard-delete okstra-*.
+async function pruneObsoleteSkills(target, opts) {
+  let pruned = 0;
+  for (const name of OBSOLETE_SKILL_NAMES) {
+    const path = join(target.skillsDir, name);
+    if (!(await pathEntryExists(path))) continue;
+    pruned += 1;
+    if (opts.dryRun) {
+      process.stdout.write(`[dry-run] rm ${path}\n`);
+      continue;
+    }
+    await fs.rm(path, { recursive: true, force: true });
+  }
+  return pruned;
+}
+```
+
+Apply the helper call rename in both `installSkillsCopy()` and `installSkillsLink()`.
+
+- [ ] **Step 4: Run catalog tests to verify pass**
+
+Run:
+
+```bash
+node --test tests-js/skill-catalog.test.mjs
+python3 -m pytest tests/contract/test_docs_runtime_contract.py::test_plugin_manifest_exposes_only_user_facing_skills -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit Task 1**
+
+```bash
+git add skills/okstra-container-build src/lib/skill-catalog.mjs src/commands/lifecycle/install.mjs .claude-plugin/plugin.json tests-js/skill-catalog.test.mjs tests/contract/test_docs_runtime_contract.py
+git commit -m "fix(container): rename public container skill to build"
+```
+
+### Task 2: Install/Uninstall Upgrade Cleanup
+
+**Files:**
+- Modify: `tests-js/install-runtime.test.mjs`
+- Modify: `tests-js/uninstall-runtime.test.mjs`
+- Modify: `src/commands/lifecycle/uninstall.mjs`
+
+**Interfaces:**
+- Consumes: `OBSOLETE_SKILL_NAMES` includes `okstra-container`.
+- Produces: install removes old `okstra-container` skill dirs during upgrade.
+- Produces: uninstall fallback can remove both `okstra-container-build` and old `okstra-container`.
+
+- [ ] **Step 1: Write failing install prune regression**
+
+In `tests-js/install-runtime.test.mjs`, extend `install copies skills to existing Claude and Agent homes and records targets` after the `.claude` / `.agent` roots are created:
+
+```js
+  for (const providerRoot of [join(root, ".claude", "skills"), join(root, ".agent", "skills")]) {
+    mkdirSync(join(providerRoot, "okstra-container"), { recursive: true });
+    writeFileSync(join(providerRoot, "okstra-container", "SKILL.md"), "old container skill\n");
+  }
+```
+
+Extend the provider-root assertions:
+
+```js
+    assert.equal(existsSync(join(providerRoot, "okstra-container-build", "SKILL.md")), true);
+    assert.equal(existsSync(join(providerRoot, "okstra-container", "SKILL.md")), false);
+```
+
+- [ ] **Step 2: Write failing uninstall fallback regression**
+
+Add this test to `tests-js/uninstall-runtime.test.mjs`:
+
+```js
+test("uninstall fallback removes renamed and legacy container skills", () => {
+  const { root, env } = makeInstallEnv();
+  mkdirSync(join(root, ".okstra"), { recursive: true });
+  mkdirSync(join(root, ".claude", "skills", "okstra-container"), { recursive: true });
+  mkdirSync(join(root, ".claude", "skills", "okstra-container-build"), { recursive: true });
+
+  const uninstall = runCli(["uninstall", "-y"], env);
+  assert.equal(uninstall.code, 0, uninstall.stderr);
+
+  assert.equal(existsSync(join(root, ".claude", "skills", "okstra-container")), false);
+  assert.equal(existsSync(join(root, ".claude", "skills", "okstra-container-build")), false);
+});
+```
+
+- [ ] **Step 3: Run failing install/uninstall tests**
+
+Run:
+
+```bash
+node --test tests-js/install-runtime.test.mjs tests-js/uninstall-runtime.test.mjs
+```
+
+Expected: FAIL until `src/commands/lifecycle/uninstall.mjs` fallback names include both container skill names and install prune is wired to `OBSOLETE_SKILL_NAMES`.
+
+- [ ] **Step 4: Implement fallback cleanup names**
+
+Edit `src/commands/lifecycle/uninstall.mjs` `FALLBACK_SKILL_NAMES`:
+
+```js
+const FALLBACK_SKILL_NAMES = [
+  "okstra",
+  "okstra-setup",
+  "okstra-brief",
+  "okstra-run",
+  "okstra-memory",
+  "okstra-inspect",
+  "okstra-schedule",
+  "okstra-container-build",
+  "okstra-container",
+  "okstra-context-loader",
+  "okstra-team-contract",
+  "okstra-convergence",
+  "okstra-report-writer",
+  // Pre-merge names — kept so uninstall on an upgraded machine still cleans
+  // them out of ~/.claude/skills/ once the user runs `okstra uninstall`.
+  // Safe to drop after a few releases when nobody has them installed.
+  "okstra-status",
+  "okstra-history",
+  "okstra-logs",
+  "okstra-report-finder",
+  "okstra-time-summary",
+];
+```
+
+- [ ] **Step 5: Run install/uninstall tests to verify pass**
+
+Run:
+
+```bash
+node --test tests-js/install-runtime.test.mjs tests-js/uninstall-runtime.test.mjs
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit Task 2**
+
+```bash
+git add src/commands/lifecycle/uninstall.mjs tests-js/install-runtime.test.mjs tests-js/uninstall-runtime.test.mjs
+git commit -m "fix(install): prune legacy container skill on rename"
+```
+
+### Task 3: Docs, Prompts, and User-Visible Changelog
+
+**Files:**
+- Move: `docs/for-ai/skills/okstra-container.md` -> `docs/for-ai/skills/okstra-container-build.md`
+- Modify: `README.md`
+- Modify: `README.kr.md`
+- Modify: `docs/kr/architecture.md`
+- Modify: `docs/project-structure-overview.md`
+- Modify: `docs/kr/container.md`
+- Modify: `docs/for-ai/README.md`
+- Modify: `docs/for-ai/skills/okstra-container-build.md`
+- Modify: `docs/for-ai/skills/okstra-inspect.md`
+- Modify: `prompts/profiles/_implementation-deliverable.md`
+- Modify: `prompts/profiles/final-verification.md`
+- Modify: `docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md`
+- Modify: `docs/superpowers/plans/2026-06-24-manual-user-test-section.md`
+- Modify: `CHANGES.md`
+- Test: `tests/contract/test_docs_runtime_contract.py`
+
+**Interfaces:**
+- Consumes: public skill name `okstra-container-build`.
+- Produces: user-facing slash command docs use `/okstra-container-build`.
+- Produces: prompt guidance uses `/okstra-container-build` for skill invocation and `okstra container up ...` for CLI execution.
+
+- [ ] **Step 1: Write failing docs scan command**
+
+Run:
+
+```bash
+rg -n -P '/okstra-container(?!-build)\\b|okstra-container up|okstra-container-build[[:alpha:]]' README.md README.kr.md docs/kr/architecture.md docs/project-structure-overview.md docs/kr/container.md docs/for-ai prompts/profiles/_implementation-deliverable.md prompts/profiles/final-verification.md docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md docs/superpowers/plans/2026-06-24-manual-user-test-section.md
+```
+
+Expected before edits: matches showing old slash-command/prompt references and zero `builder` references after the corrected spec.
+
+- [ ] **Step 2: Rename AI manual file and update live references**
+
+Run:
+
+```bash
+git mv docs/for-ai/skills/okstra-container.md docs/for-ai/skills/okstra-container-build.md
+```
+
+Apply these text rules:
+
+```text
+/okstra-container -> /okstra-container-build
+`okstra-container` as public skill name -> `okstra-container-build`
+skills/okstra-container.md -> skills/okstra-container-build.md
+skills/okstra-container/SKILL.md -> skills/okstra-container-build/SKILL.md
+```
+
+Do not change these runtime strings:
+
+```text
+okstra container
+okstra-container-<slug>
+@okstra_container_run
+```
+
+In `prompts/profiles/_implementation-deliverable.md`, replace the environment line with:
+
+```markdown
+- **Manual user test draft**: when this run produces a user-observable change (UI / API / CLI / artifact), write `target / environment / steps / expected result` per change into §5.7.9 (data field `implementation.manualUserTest`, `applicable=true` with `items`). Environment line: if the project has a `docker-compose.yml`, use `/okstra-container-build` (which runs `okstra container up <task-id>`) then connect to the published port; otherwise the project's run command (e.g. `npm start`). When there is no user-observable change, set `applicable=false` and give a one-line `exemptionReason` instead of items. Base the steps on the approved plan's `Acceptance:` and this run's actual diff — these are the steps a human (or `final-verification`) re-runs by hand, NOT the automated validation commands in `Validation evidence`.
+```
+
+In `prompts/profiles/final-verification.md`, replace the manual test example with:
+
+```markdown
+  - **Manual user test results**: take each item from the source implementation report's §5.7.9 Manual User Test (Draft), execute the ones reproducible in this environment (e.g. `/okstra-container-build`, which runs `okstra container up`, then the documented steps), and record `result` (`pass` / `fail` / `blocked`) + observed value in §5.8.7 (data field `finalVerification.manualUserTest`). Steps that need human-only interaction this run cannot perform are recorded as `blocked` with the reason (handed to the user), never silently skipped. A failed manual test is an Acceptance Blocker. If the draft was an exemption (`applicable=false`), reaffirm the reason in one line (`applicable=false` + `exemptionReaffirm`).
+```
+
+- [ ] **Step 3: Add current CHANGES entry**
+
+Under `## 2026-06-24`, add this entry above the existing entries:
+
+```markdown
+### fix(container): 공개 컨테이너 스킬명을 okstra-container-build 로 변경
+
+- **배경**: 컨테이너 유저 테스트 기능의 공개 slash command 이름을 `okstra-container` 에서 `okstra-container-build` 로 바꾸기로 결정했다. CLI 명령 `okstra container ...` 와 런타임 tmux/docker trace prefix `okstra-container-<slug>` 는 컨테이너 런타임 계약이므로 유지한다.
+- **해결**: 공개 skill catalog, 플러그인 manifest, 설치/업그레이드 cleanup, README/architecture/AI manual/phase prompt 의 사용자-facing 표기를 `okstra-container-build` 로 동기화한다. 옛 `okstra-container` skill directory 는 exact-name obsolete cleanup 으로 재설치 시 제거한다.
+- 사용자 영향: 재설치 후 slash command 는 `/okstra-container-build` 로 노출된다. 기존 `okstra container up/status/logs/stop-watcher/down` CLI 와 실행 중 container watcher trace 이름은 그대로 유지된다. (설치 환경은 `okstra install` 로 런타임 갱신 후 적용.)
+```
+
+- [ ] **Step 4: Run docs scans and contract test**
+
+Run:
+
+```bash
+rg -n -P '/okstra-container(?!-build)\\b|okstra-container up|okstra-container-build[[:alpha:]]' README.md README.kr.md docs/kr/architecture.md docs/project-structure-overview.md docs/kr/container.md docs/for-ai prompts/profiles/_implementation-deliverable.md prompts/profiles/final-verification.md docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md docs/superpowers/plans/2026-06-24-manual-user-test-section.md
+python3 -m pytest tests/contract/test_docs_runtime_contract.py -q
+```
+
+Expected: `rg` exits 1 with no matches; pytest PASS.
+
+- [ ] **Step 5: Commit Task 3**
+
+```bash
+git add README.md README.kr.md docs/kr/architecture.md docs/project-structure-overview.md docs/kr/container.md docs/for-ai/README.md docs/for-ai/skills/okstra-container-build.md docs/for-ai/skills/okstra-inspect.md prompts/profiles/_implementation-deliverable.md prompts/profiles/final-verification.md docs/superpowers/specs/2026-06-24-manual-user-test-section-design.md docs/superpowers/plans/2026-06-24-manual-user-test-section.md CHANGES.md
+git commit -m "docs(container): rename container skill docs to build"
+```
+
+### Task 4: Runtime Build and Full Verification
+
+**Files:**
+- Generated: `runtime/` via `npm run build` (gitignored, do not hand-edit)
+- Test: `tests-js/*.test.mjs`
+- Test: `tests/`
+- Test: `validators/validate-workflow.sh`
+
+**Interfaces:**
+- Consumes: source skill directory `skills/okstra-container-build`.
+- Produces: generated `runtime/skills/okstra-container-build/SKILL.md`.
+- Produces: no generated `runtime/skills/okstra-container/SKILL.md`.
+
+- [ ] **Step 1: Run build**
+
+Run:
+
+```bash
+npm run build
+```
+
+Expected: exit 0. Output includes `skills -> runtime/skills` sync. `runtime/` remains untracked/ignored.
+
+- [ ] **Step 2: Verify runtime skill sync**
+
+Run:
+
+```bash
+test -f runtime/skills/okstra-container-build/SKILL.md
+test ! -e runtime/skills/okstra-container/SKILL.md
+rg -n "name: okstra-container-build" runtime/skills/okstra-container-build/SKILL.md
+```
+
+Expected: all commands exit 0.
+
+- [ ] **Step 3: Run targeted test suite**
+
+Run:
+
+```bash
+node --test tests-js/skill-catalog.test.mjs tests-js/install-runtime.test.mjs tests-js/uninstall-runtime.test.mjs tests-js/doctor-runtime.test.mjs
+python3 -m pytest tests/contract/test_docs_runtime_contract.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Run project check**
+
+Run:
+
+```bash
+npm run check
+```
+
+Expected: exit 0.
+
+- [ ] **Step 5: Run final identifier audit**
+
+Run:
+
+```bash
+rg -n "okstra-container-build[[:alpha:]]|container-build[[:alpha:]]" .
+rg -n "okstra-container" .
+```
+
+Expected:
+- First command exits 1 with no matches.
+- Second command still reports historical changelog/old design-plan references and runtime prefix tests such as `okstra-container-<slug>`, but not live public skill catalog, plugin manifest, README slash-command rows, AI routing manuals, or live phase prompt instructions.
+
+- [ ] **Step 6: Record verification-only status**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected: no new tracked source changes from Task 4. `runtime/` may have been regenerated by `npm run build` but remains ignored. Do not create a commit for this task unless a tracked verification fixture changed.

package/docs/superpowers/specs/2026-06-24-cross-project-precondition-design.md

@@ -0,0 +1,129 @@
+# Cross-Project Dependencies — implementation-planning 선행 필수 격상 설계
+
+- 작성일: 2026-06-24
+- 대상 phase: `implementation-planning`
+- 상태: 설계 승인 완료 (구현 계획 작성 대기)
+
+## 1. 배경과 문제
+
+`implementation-planning` 보고서는 `data.json`(SSOT) → Jinja 템플릿(`templates/reports/final-report.template.md`)으로 **결정론적 렌더**된다. report-writer 는 마크다운을 직접 쓰지 못한다([report-writer-worker.md:27](../../../agents/workers/report-writer-worker.md:27)).
+
+이 run 이 **다른 프로젝트(다른 repo·published 패키지)** 의 작업에 의존할 때, 그 의존을 표현할 수 있는 채널이 현재 3개뿐이고 모두 부족하다:
+
+1. **`§3 Recommended Next Steps`** (`recommendedNextSteps[]`, 자유 텍스트) — "추천"이라 강제력이 없다. 실제 사례(`dev-9795`)에서 "helpers·common-api cross-repo carry 를 별도 okstra run 으로 먼저 진행하라"가 여기에 soft 하게 들어가, 선행 필수임이 드러나지 않았다.
+2. **`Dependency / Migration Risk`** DM 행 — `kind` enum 에 `flag-precondition`/`repo-sequencing` 이 있으나([schema:1369](../../../schemas/final-report-v1.0.schema.json)) "위험 서술"일 뿐 "선행 필수 + 구체 작업"을 강제하지 않는다. `repo-sequencing` 은 프로파일상 **repo-내부 순서**를 뜻한다([implementation-planning.md:100](../../../prompts/profiles/implementation-planning.md:100)) — cross-repo 마커가 아니다.
+3. **프로파일이 요구하는 `## Cross-Repo Carry — <repo>` 부록**([implementation-planning.md:94](../../../prompts/profiles/implementation-planning.md:94)) — **스키마·템플릿에 렌더 슬롯이 없어 보고서에 출력되지 못하는 잠복 버그**. 게다가 방향이 "이 run 이 상위(upstream)이고 다른 repo 가 하위"로, 사용자 사례(이 run 이 **하위**, 외부 패키지가 **선행 상위**)와 반대다.
+
+결과적으로 **"이 run 이 다른 프로젝트의 선행 작업에 의존한다"** 는 1급 개념이 없어 soft recommendation 으로 새어나가고, 거기서 필요한 **구체 작업**도 강제되지 않는다.
+
+## 2. 목표 / 비목표
+
+### 목표
+- cross-project 의존을 **1급·렌더되는 구조 필드**로 승격한다.
+- upstream(이 run 이 기다림 = 선행 필수)과 downstream(이 run 이 만들어 줌 = 기존 carry) **두 방향을 한 개념으로 통합**한다.
+- 각 의존에 **구체적으로 필요한 작업**(`requiredWork`)을 빈말 못 하도록 스키마 레벨에서 강제한다.
+- cross-project 의존이 선언되면 이 섹션이 비어있지 못하도록 **검증기 게이트**를 둔다.
+- 기존 `## Cross-Repo Carry` 잠복 렌더 버그를 통합 과정에서 해소한다.
+
+### 비목표
+- **런타임 게이트 없음.** `implementation` run 진입 시 선행 신호를 자동 확인하거나 워커 fan-out 을 차단하지 않는다.
+- **승인 차단 없음.** 계획 frontmatter `approved` 를 막지 않는다 — 선행 작업은 병렬 진행 가능하므로 계획 승인 자체는 막지 않는다.
+- 다른 repo 의 트리·`.okstra/` 에 쓰지 않는다(기존 cross-repo 구조 한계 유지).
+
+## 3. 설계
+
+### 3.1 데이터 모델 (schema)
+
+`schemas/final-report-v1.0.schema.json` 의 `implementationPlanning` 객체에 새 배열 `crossProjectDependencies` 를 추가한다(기본 `[]` 허용 — 단일 프로젝트 계획은 빈 배열).
+
+새 `$defs/CrossProjectDependency`:
+
+| 필드 | 타입/제약 | 의미 |
+|---|---|---|
+| `id` | `^XP-\d{3,}$` | cross-project 식별자 |
+| `direction` | enum: `upstream-precondition` \| `downstream-carry` | upstream = 이 run 이 **기다림**(선행 필수); downstream = 이 run 이 **만들어 줌**(기존 carry) |
+| `project` | string, minLength 1 | 상대 프로젝트/repo/패키지명 (예: `@fonts-ninja-org/common-api`) |
+| `requiredWork` | string, minLength 1 | **구체적으로 필요한 작업**. upstream: 상대 프로젝트가 만들어야 할 것; downstream: 상대가 후속으로 구현할 B-portion |
+| `verificationSignal` | string, minLength 1 | 충족을 증명하는 관측 신호 (예: "npm common-api ≥ 1.27.46 + Font.d.ts 에 isSlanted 존재") |
+| `linkedWork` | string, minLength 1 | upstream: 신호 충족 전 **막히는 이 계획의 stage/step**; downstream: 이 run 산출물을 소비하는 상대 작업 |
+| `howToStart` | string, minLength 1 | 정확한 핸드오프 (`okstra-brief …(이 보고서 절대경로 Source Material)` → `okstra-run`) |
+
+- `additionalProperties: false`, 위 7개 전부 `required`.
+- `direction` 으로 양방향을 한 구조에 담는다. 기존 Cross-Repo Carry 의 세 서브섹션은 `downstream-carry` 행으로 흡수: `Preconditions already covered by this run` → `verificationSignal`(상대가 확인할 신호), `Work for <repo> to implement` → `requiredWork`, `How to start <repo>'s run` → `howToStart`.
+
+### 3.2 렌더 (template + i18n)
+
+`templates/reports/final-report.template.md` 의 §5.4 블록에서 `### Dependency / Migration Risk`([template:208](../../../templates/reports/final-report.template.md:208)) **바로 뒤**에 새 서브섹션 `### Cross-Project Dependencies` 를 추가한다.
+
+- **엔트리별 블록** 렌더(Option Candidates 방식). 7열 표는 가독성이 떨어지므로 표를 쓰지 않는다:
+  ```
+  **XP-001 — [upstream-precondition] @fonts-ninja-org/common-api**
+  - Required work: Font.d.ts 에 isSlanted 컬럼 추가 후 publish (≥ 1.27.46)
+  - Verification signal: npm view … → ≥ 1.27.46 AND isSlanted present
+  - Gated work in this plan: Stage 2 yarn install / Stage 3 compile — 신호 충족 전 진행 불가
+  - How to start: common-api repo 에서 okstra-brief … → okstra-run
+  ```
+- `crossProjectDependencies` 가 비면 단일 empty-state 라인(`- 해당 없음.` / 영어 i18n) 을 렌더한다 — 단일 프로젝트 계획은 항상 이 줄이 보인다.
+- i18n: `templates/reports/i18n/{ko,en}.json` 에 섹션 헤딩 aside, 라벨(Required work / Verification signal / Linked work / How to start), empty-state 문자열 추가.
+- 방향 라벨(`[upstream-precondition]` / `[downstream-carry]`)은 reader 가 선행/후속을 한눈에 구분하도록 블록 제목에 박는다.
+
+### 3.3 강제 (validator) — 두 겹
+
+**(a) 모양 규칙 — watertight, JSON 스키마가 강제**
+`crossProjectDependencies` 가 비어있지 않으면 모든 행의 7개 필드가 minLength 1 을 만족해야 한다. `requiredWork`/`verificationSignal`/`howToStart` 가 비면 스키마 검증 실패 → **"구체 작업 명시"가 빈말이 될 수 없다.** `validate-run.py` 의 data.json 스키마 검증 경로([validate-run.py:1440](../../../validators/validate-run.py:1440))에서 자동 적용.
+
+**(b) 존재 규칙 — trigger, `validate-run.py` 교차 필드 검사**
+- DM `kind` enum 에 새 값 **`cross-project`** 추가(pre-1.0, enum 확장 자유). 의미: 다른 프로젝트/repo/패키지에 대한 의존. 기존 `repo-sequencing`(repo-내부)·`flag-precondition`(repo-내 플래그)과 명확히 구분.
+- `validate-run.py` 에 교차 필드 규칙 신설: **data.json 에 `dependencyMigrationRisk` 행 중 `kind == cross-project` 가 하나라도 있으면 `crossProjectDependencies` 는 비어있으면 안 되고, `direction == upstream-precondition` 행이 ≥ 1 이어야 한다.** 위반 시 `contract-violated`.
+- 이 규칙이 **"추천 → 선행 필수" 격상의 강제 지점**이다. 프로파일이 "타 repo/패키지 의존은 반드시 DM `cross-project` 행 + 매칭 XP 행으로 기록"을 지시하고, 검증기가 1:1 을 강제한다(allowlist 방식).
+
+**(c) 섹션 헤딩 contract**
+`implementation-planning.md` 섹션 헤딩 contract([implementation-planning.md:57](../../../prompts/profiles/implementation-planning.md:57))의 필수 substring 목록에 `Cross-Project Dependencies` 를 추가. 템플릿이 이 헤딩을 무조건 렌더하므로(empty-state 포함) substring 검사를 통과한다.
+
+### 3.4 프로파일 prose (`prompts/profiles/implementation-planning.md`)
+
+- 기존 Cross-Repo Carry 부록 블록(94–98)을 **새 구조 필드 참조로 재작성**하고 **양방향**(upstream-precondition / downstream-carry)을 커버하도록 바꾼다. "Recognition caveat"(상대 run 의 독립성) 문구는 섹션 하단 고정 노트(i18n)로 유지.
+- "Required deliverable shape" 에 `crossProjectDependencies` 항목 추가: 타 프로젝트 의존은 DM `cross-project` 행 + 매칭 XP 행(구체 `requiredWork`·`verificationSignal`·`howToStart`) 으로 기록할 것.
+- self-review 패스([implementation-planning.md:122](../../../prompts/profiles/implementation-planning.md:122))에 점검 추가: "타 repo/패키지 의존을 빠뜨리지 않았는가; DM `cross-project` ↔ XP 행 1:1 이 맞는가; `requiredWork` 가 구체적인가".
+- §5.5.9 Plan Body Verification 의 adversarial 라운드 대상에 cross-project precondition 누락 점검을 포함.
+- `recommendedNextSteps` 의 cross-project 항목 정책: **substance 는 새 섹션에, §3 는 포인터만**(이중 기록 방지). report-writer 가이드(`prompts/lead/report-writer.md:284` 인근)도 동기화.
+
+### 3.5 스키마 excerpt / 빌드 흐름
+
+- per-task-type 스키마 excerpt 빌더(`scripts/okstra_ctl/schema_excerpt.py`, `final_report_schema.py`)가 `implementationPlanning` 블록과 그 `$defs` 를 자동 포함하는지 확인한다. 새 `$defs/CrossProjectDependency` 가 implementation-planning excerpt 에 반드시 들어가야 report-writer 가 올바른 shape 로 authoring 한다.
+- `runtime/` 은 빌드 출력이므로 직접 수정 금지 — 소스(`schemas/`, `templates/`, `prompts/`, `validators/`, `agents/`) 수정 후 `npm run build` 로 동기화.
+
+## 4. 변경 파일 목록
+
+| 파일 | 변경 |
+|---|---|
+| `schemas/final-report-v1.0.schema.json` | `$defs/CrossProjectDependency` 신설; `implementationPlanning.crossProjectDependencies` 추가; DM `kind` enum 에 `cross-project` 추가 |
+| `templates/reports/final-report.template.md` | §5.4 에 `### Cross-Project Dependencies` 엔트리별 블록 + empty-state |
+| `templates/reports/i18n/ko.json`, `en.json` | 섹션 헤딩 aside·필드 라벨·empty-state·recognition-caveat 문자열 |
+| `prompts/profiles/implementation-planning.md` | Cross-Repo Carry 재작성(양방향), deliverable shape·self-review·heading contract·recommendedNextSteps 정책 갱신 |
+| `prompts/lead/report-writer.md` | recommendedNextSteps cross-project 포인터 정책 동기화 |
+| `validators/validate-run.py` | DM `cross-project` ↔ `crossProjectDependencies` 교차 필드 규칙 |
+| `agents/workers/report-writer-worker.md` | 필요 시 새 섹션 authoring 안내(스키마 excerpt 가 주도하므로 최소) |
+| `tests/` | 아래 §6 검증 계획 |
+
+## 5. 강제 지점 매핑 (MUST → 어디서 강제되나)
+
+| 규칙 | 강제 지점 |
+|---|---|
+| XP 행의 7필드 비-빈 (구체 작업 명시) | JSON 스키마 `required` + minLength → `validate-run.py` 스키마 검증 |
+| DM `cross-project` 있으면 XP `upstream-precondition` ≥ 1 | `validate-run.py` 신설 교차 필드 검사 |
+| 섹션 헤딩 `Cross-Project Dependencies` 존재 | `validate-run.py` substring 검사 + 템플릿 무조건 렌더 |
+| report-writer 가 올바른 shape authoring | implementation-planning 스키마 excerpt 에 포함 |
+
+## 6. 검증 계획 (추가할 테스트)
+
+- `tests/report/test_render_final_report.py`: `implementation-planning` 픽스처에 `crossProjectDependencies`(upstream·downstream 각 1행) 추가 → 렌더 결과에 블록·라벨·방향 태그가 나오는지; 빈 배열 → empty-state 라인이 나오는지.
+- `tests/contract/` (또는 validate-run 테스트): DM `cross-project` 행이 있는데 `crossProjectDependencies` 가 비면 `contract-violated` 인지; XP 행에 `requiredWork` 빈 값이면 스키마 검증 실패인지.
+- `tests/fixtures/final-report-data/implementation-planning-001.data.json`: 새 필드 반영(빈 배열로 최소 변경하거나 샘플 1행 추가).
+- 완료 게이트: `npm run check` 가 그대로 exit 0.
+
+## 7. 한계 / 미해결
+
+- **존재 규칙의 trigger 는 planner 가 DM `cross-project` 를 찍어야 발동**한다. cross-project 의존을 DM 에 전혀 기록하지 않으면 검증기가 잡지 못한다(완전 watertight 불가). 이를 줄이기 위해 프로파일 self-review + §5.5.9 adversarial verification 이 누락을 잡도록 prose 로 보강한다(휴리스틱, 강제 아님 — 이 한계를 spec 에 명시).
+- 자유 텍스트(`recommendedNextSteps`)에서 cross-project 신호를 토큰 매칭으로 자동 검출하지 않는다(오탐 위험). 구조 신호(DM `cross-project`)만을 강제 앵커로 쓴다.
+- 런타임 자동 신호 확인(예: npm 버전 publish 여부)은 본 설계 범위 밖(비목표).