okstra 0.38.1 → 0.40.0

package/runtime/prompts/profiles/_common-contract.md

@@ -29,12 +29,16 @@ profile document.
   - This rule does NOT relax any phase-specific Forbidden actions list; safety rules in the per-profile document remain in force regardless of the user's authority.
 - Anti-escalation rule (shared):
   - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start a *different* lifecycle phase is forbidden. The next phase begins only in a separate okstra run launched with the new `--task-type`. Per-profile documents may further restrict this within their own scope.
-- Phase wrap-up — worker trace pane disposition (shared, MUST be the *last* step before returning control to the user):
-  - Codex / Gemini worker wrappers spawn `tail -F` trace panes in the lead's tmux session, titled `<cli>-<role>-<pid>-trace` (e.g. `codex-worker-93421-trace`, `gemini-executor-93422-trace`) — the matching caller (worker) pane is titled `<cli>-<role>-<pid>` so worker ↔ trace pairs can be matched by the shared `<pid>` suffix. They survive every worker invocation by design so the operator can scroll back through the final output, but accumulate across phases and clutter the screen.
-  - When `$TMUX_PANE` is set, after the final-report file has been written and the routing recommendation has been issued, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list` exactly once. The output is a tab-separated `<pane_id>\t<pane_title>` list of every trace pane registered for this Claude session.
-  - If the list is empty, skip the question — there is nothing to ask about.
+- Phase-start pane reset (shared — runs BEFORE dispatching each new worker batch):
+  - okstra creates two kinds of tmux pane per run: (a) **worker-agent panes** the harness gives to dispatched subagents (titled `claude-worker` / `codex-worker` / `gemini-worker` / `report-writer-worker`), and (b) **trace panes** the codex/gemini wrappers spawn (`<cli>-<role>-<pid>-trace`). Both accumulate across internal phases because each new phase dispatches a fresh worker batch and the prior panes are never reclaimed.
+  - When `$TMUX_PANE` is set, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh` (no args) **immediately before** dispatching the next phase's workers — i.e. just before emitting each `PROGRESS: phase-5.5-convergence round=<N>` marker and just before `PROGRESS: phase-6-synthesis dispatching report-writer-worker`. This closes every prior-phase okstra pane (worker-agent + trace) for the lead session, while NEVER killing the lead's own pane.
+  - This is **automatic and silent** — NO user prompt. Report it in one short line (e.g. `이전 phase okstra pane 3개 정리`) and proceed. It is silent-skipped when `$TMUX_PANE` is unset; the lead MUST NOT fabricate a synthetic pane list in that case.
+- Phase wrap-up — okstra pane disposition (shared, MUST be the *last* step before returning control to the user):
+  - At run end the only residual okstra panes are the LAST phase's (e.g. the `report-writer-worker` agent pane and any codex/gemini trace pane). `okstra-trace-cleanup.sh --list` returns one tab-separated `<pane_id>\t<pane_title>` line per residual okstra pane (worker-agent + trace) for this lead session.
+  - When `$TMUX_PANE` is set, after the final-report file has been written and the routing recommendation has been issued, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list` exactly once. The output lists every residual okstra pane (worker-agent + trace) for this Claude session, never the lead's own pane.
+  - If the list is empty, skip the question — there is nothing to ask about (the phase-start resets above usually already cleared prior phases).
   - Otherwise the lead MUST present the user with a strict binary choice **before** declaring the phase complete. Use one prompt of this shape (Korean preferred, English acceptable if the rest of the run is in English):
-    > 현재 phase 종료 시점입니다. 다음 worker trace pane 이 열려 있습니다 — 닫을까요?
+    > 현재 phase 종료 시점입니다. 다음 okstra pane 이 열려 있습니다 — 닫을까요?
     > <인용된 `--list` 출력>
     > (예) 모두 닫기 / (아니오) 그대로 두기
   - On `예` / `y` / `close` → run `$HOME/.okstra/bin/okstra-trace-cleanup.sh` (no args) and report the kill count back in one sentence.

package/runtime/prompts/profiles/final-verification.md

@@ -8,31 +8,33 @@
 - Optional workers (opt-in via `--workers`):
   - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
-- Primary focus areas:
-  - requirement coverage
-  - whether delivered config files and deployment manifests satisfy the recorded expected values
-  - unresolved edge cases
-  - regression risk
-  - documentation or rollout gaps
-  - reasons the change may still fail in production
-- Expected output emphasis:
-  - acceptance blockers
-  - residual risk
-  - final release recommendations
+- Primary focus areas (each maps to a deliverable section below):
+  - Acceptance-gating — a failure here pushes the verdict toward `blocked` / `conditional-accept`:
+    - requirement & acceptance coverage — every must-pass point in the brief's `## Acceptance Criteria` (and the approved plan's requirements) is covered with a cited artifact or raised as an Acceptance Blocker; no silent omissions
+    - delivered artifacts match recorded expected values in `reference-expectations` (config files, deployment manifests, other recorded expected states); when reference-expectations are absent, record it as missing information rather than assuming a match
+    - test & validation suite pass status — independently re-run the read-only two-tier command set (Tier 1 = brief/approved-plan `validation`, Tier 2 = `project.json` `qaCommands`) and confirm each passes on the verified head, citing exact command + exit code
+    - test correctness — delivered tests actually assert the intended behaviour: no gutted/weakened assertions, no tautological or always-passing tests, no tests exercising only mocks; new behaviour has matching coverage
+    - no new defects introduced — the diff does not break previously-working behaviour and adds no new bug (logic/off-by-one, null/empty handling, resource leaks, broken error paths)
+    - scope conformance — the delivered diff stays within the approved plan's scope; flag out-of-scope edits, unrelated file changes, leftover debug/commented-out code, and unintended deletions
+  - Residual-tracked — note as Residual Risk unless severe enough to block:
+    - unresolved edge cases
+    - regression risk in adjacent code paths not directly changed
+    - documentation or rollout gaps
+    - production-specific failure modes not caught by tests (env/config drift across stages, secrets & permission/auth changes, migration ordering & rollback executability, observability gaps)
 - Pre-verification entry gate (mandatory — refuse to start if any item fails):
-  - the task brief MUST cite the originating `implementation` final-report path under `## Source Implementation Report`. The lead opens that file and confirms it includes `Plan link & approval evidence`, `Commit list`, `Diff summary`, `Validation evidence`, and `Routing recommendation for final-verification`.
+  - the task brief MUST cite the originating `implementation` final-report path under `## Source Implementation Report`. The lead opens that file and confirms it includes the approved-plan reference (heading `Approved Plan Reference` or `Plan link & approval evidence`), `Commit list`, `Diff summary`, `Validation evidence`, and `Routing recommendation for final-verification`.
   - the task brief MUST identify the worktree / checkout under verification and the implementation base ref. If the implementation report names a task worktree, final-verification MUST inspect that same worktree rather than the caller's original checkout.
   - the lead MUST capture `git rev-parse HEAD`, `git status --short`, and `git diff --stat <implementation-base>..HEAD` from the verification worktree before dispatching workers. These values are the verification target and must be cited in the final report.
   - if the cited implementation report is missing, lacks commits for delivered code changes, or the current checkout does not match the implementation report's commit list / diff summary, the run MUST end with status `blocked` and route back to `implementation` or `implementation-planning` rather than verifying an ambiguous target.
 - Required deliverable shape (final report, in addition to the standard sections):
-  - **Source Implementation Report**: relative path of the originating `implementation` final-report file, the quoted commit list / diff summary used as the verification target, the worktree path inspected, and the base/head SHAs captured at run start.
-  - **Verdict vocabulary**: Section 2 (`Final Verdict`) MUST include a `Verdict Token` field whose value is exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed.
+  - **Source Implementation Report**: relative path of the originating `implementation` final-report file, the quoted commit list / diff summary used as the verification target, the worktree path inspected, and the base/head SHAs captured at run start. The lead injects this same target snapshot into every analyser prompt (`**Worktree:** / **Verification base ref:** / **Verification head SHA:** / **Verification diff stat:**`); a worker that cannot confirm its analysis ran against that exact head MUST record a `tool-failure` rather than verify an ambiguous target.
+  - **Verdict vocabulary**: Section 2 (`Final Verdict`) MUST include a `Verdict Token` field whose value is exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed. Each condition MUST be recorded as a row in the **Conditional Acceptance Conditions** deliverable (`id` `CA-NNN`, `condition`, `evidenceRequired`, `blocksReleaseHandoff`). The validator enforces verdict↔deliverable consistency: `accepted` ⇒ zero acceptance blockers, `blocked` ⇒ at least one, `conditional-accept` ⇒ at least one condition, and a `release-handoff` routing recommendation is allowed only when the verdict is `accepted`.
   - **Acceptance Blockers block** (under section 4): one row per blocker with `id`, `severity` (`critical` / `major` / `minor`), evidence (file path, log excerpt, or test output), and the recommended follow-up phase (`error-analysis` or `implementation-planning`). Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
   - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
   - **Two-tier command lookup (shared with `implementation`):** when this phase performs its own independent re-validation, the command source is exactly the same two tiers `implementation` verifiers use — Tier 1 is the originating task brief / approved plan's `validation` set, Tier 2 is `<PROJECT_ROOT>/.okstra/project.json` under `qaCommands`. Auto-detecting tools from manifest files is forbidden; missing tiers are recorded as `qa-command not configured: <category>` and do NOT trigger a guess. The `cmd` deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci`, etc.) is enforced identically. NOTE: runtime fail-fast validation (`okstra_ctl.qa_commands.validate_qa_commands`) only fires at `--task-type implementation` run-prep, so this phase MUST self-check each `qaCommands` entry against the deny-list before executing it — if a denied token is present, skip the command and record it as a `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`.
-  - **Routing recommendation**: brief note on the next safe phase (`done`, `error-analysis`, `implementation-planning`) tied to the verdict and blocker list.
+  - **Routing recommendation**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 5. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
@@ -40,7 +42,7 @@
   2. **Blocker traceability** — every blocker cites a concrete artifact (file:line, log excerpt, test exit code, MCP SELECT). Blockers without evidence are demoted to residual risk or removed.
   3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. No silent omissions.
   4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
-  5. **No-mutation audit** — scan the run's session transcripts for any Edit / Write / mutating Bash command. Any occurrence means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
+  5. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
 - Non-goals:
   - proposing unrelated refactors beyond the delivered scope
   - **source code edits, follow-up bug fixes, or scope expansion** — this run renders a verdict only; defects detected here become inputs to a new `error-analysis` or `implementation-planning` run

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

@@ -51,6 +51,7 @@
   - The final report MUST include section headings containing each of the following exact strings: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stage Map`, `Stage Exit Contract`, `Stage Validation`, `Dependency`, `Validation Checklist`, `Rollback`. (Approval is no longer a body section — it is the YAML frontmatter `approved` field.)
   - Korean translations are allowed in parentheses (e.g. `### Recommended Option (권장 옵션)`), but the English keyword must be present verbatim in the heading line.
   - The shape and ordering follow `final-report-template.md` section 4.5 (`Implementation Plan Deliverables`). Do NOT translate the heading keywords — `validators/validate-run.py` does substring matching on the raw report text and 7-of-8 missing strings is a real, repeatedly observed failure mode (root cause: writer translated the headings to Korean).
+  - Beyond substring matching, when the Plan Body Verification gate result is `passed` / `passed-with-dissent`, `validators/validate-run.py` runs the **structural** Stage Map validator (`validators/validate-implementation-plan-stages.py`) at the planning boundary — the exact `## 4.5 Stage Map` heading, each `## 4.5.<i> Stage <i>:` section with its four required subsections, the per-stage effective step count (≤6), and the `depends-on` DAG are all enforced here, not deferred to the `implementation` entry gate.
 - Required deliverable shape (final report, in addition to the standard sections):
   - at least two implementation options. **Each option must include**:
     - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`.

package/runtime/prompts/profiles/requirements-discovery.md

@@ -14,12 +14,27 @@
   - `intent-inference` augmentations whose paired `intent-check:` row carries `[CONFIRMED …]` are treated as **confirmed**; trust the confirmation text in `## Reporter Confirmations` over the original inference if they differ. Unconfirmed `intent-inference` rows under `reporter-confirmations: skipped` follow the precondition's `skipped` branch above.
   - `conversion-block:` rows are explicit "translation failed" signals — never attempt to resolve them by inference here; the precondition above already handled them.
 - Primary focus areas:
-  - classify the work as bugfix, feature, improvement, refactor, or ops-change
+  - classify the work as bugfix, feature, improvement, refactor, or ops
   - determine whether `error-analysis` or `implementation-planning` is the next safe step; direct `implementation` handoff is not a valid routing target because implementation requires an approved `implementation-planning` report
   - identify missing materials that block reliable routing
   - define task continuity expectations for long-running work under the same task key
   - capture approval or confirmation points before the next phase starts
   - **domain alignment check**: read `<PROJECT_ROOT>/.okstra/glossary.md` and `<PROJECT_ROOT>/.okstra/decisions/` titles if present. Absent okstra memory files are normal — do not error. Validate that every `terminology:*` entry under the brief's `Open Questions` has a canonical resolution before routing. Fuzzy or overloaded terms in the brief MUST be resolved to a single canonical term in this phase.
+- Fan-out (multi-item / multi-domain requests only):
+  - 단일 항목/단일 도메인 요청은 fan-out 하지 않는다(현행 단일 라우팅 보존).
+  - 요청이 2개 이상 도메인에 걸치거나 독립 착수 가능한 작업 항목이 2개 이상이면,
+    각 항목을 `runs/requirements-discovery/fan-out/unit-<NNN>.md` packet 으로 발행한다.
+    packet 은 `templates/reports/fan-out-unit.template.md` 형식을 따르며 frontmatter
+    `domain`(work-category 5-enum: bugfix / feature / refactor / ops / improvement),
+    `depends-on`(같은 fan-out 내 unit-id 의 inline 리스트 `[unit-001]`, 없으면 `[]`),
+    `recommended-next-phase`(error-analysis | implementation-planning)를 채운다.
+  - `runs/requirements-discovery/fan-out/index.md` 에 packet 을 depends-on 위상순서로
+    번호목록(`1. unit-001`)으로 나열한다(생성 뷰; 직접 편집 금지 명시). depends-on 그래프는
+    DAG 여야 한다 — `validate_fanout` 가 순환을 검증 실패로 거부하므로, 순환이 생기면
+    packet 을 finalize 하기 전에 문제 의존을 끊어 DAG 로 만든다.
+  - 최종 리포트에는 분해 결과를 중복하지 말고 "fan-out: N packets → fan-out/index.md" 한 줄
+    포인터만 둔다. packet 실행은 별도다: 사용자가 `okstra-run --task-brief <packet 경로>` 로
+    각 단위를 새 task-key 로 시작한다(이 phase 는 다운스트림 run 을 직접 시작하지 않는다).
 - Decision-tree walk (bounded):
   - When the brief's `Desired Outcome`, classification, or routing target depends on a chain of decisions, walk that chain one branch at a time. Each branch is one `Clarification Items` row, not a free-form interview.
   - For every clarification row, put the single best answer and one-line rationale in `Expected form` as `Recommended: ...`. Put other options and one-sentence consequences in the same cell as `Alternatives: ...`.
@@ -40,3 +55,5 @@
   - full implementation design unless it is required to decide the next phase
   - **source code edits, plan authoring, builds, or deployments** — this run only classifies the work and routes it; deeper analysis and planning belong to subsequent phases
   - **writes outside `<PROJECT_ROOT>/.okstra/`** — this phase only uses okstra's artifact root. Glossary additions land in `<PROJECT_ROOT>/.okstra/glossary.md` (via `okstra-brief` Step 4.5); decision drafts land in `<PROJECT_ROOT>/.okstra/decisions/` (via `implementation-planning`).
+  - 작업 단위 분해(fan-out)는 이 phase 의 in-scope 다 — 단, 각 단위의 *해법 설계*·소스
+    편집·plan 작성은 여전히 non-goal 이며 다운스트림 phase 가 담당한다

package/runtime/prompts/wizard/prompts.ko.json

@@ -118,6 +118,17 @@
         "__free_input__": "직접 입력"
       }
     },
+    "branch_confirm": {
+      "label": "{summary}",
+      "labels": {
+        "new": "새 브랜치 `{branch}` 를 base-ref `{base_ref}` 에서 새 worktree(`{path}`)에 생성합니다 — 진행할까요?",
+        "reuse": "현재 worktree(`{path}`, 브랜치 `{branch}`)를 재사용합니다 — 진행할까요?",
+        "in_worktree": "현재 worktree(`{path}`)에서 그대로 진행합니다(이미 non-main worktree) — 진행할까요?",
+        "not_git": "git 저장소가 아니므로 `{path}` 에서 직접 진행합니다 — 진행할까요?"
+      },
+      "options": { "proceed": "진행", "edit": "base-ref 다시 고르기" },
+      "echo_template": "branch-confirm: {value}"
+    },
     "base_ref_text": {
       "label": "base ref 를 입력해주세요 (branch, tag, 또는 short/full SHA)",
       "echo_template": "base-ref: {value}"

package/runtime/python/okstra_ctl/consumers.py

@@ -36,7 +36,7 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
                     status: str, **fields: Any) -> None:
     if status not in ("started", "done"):
         raise ValueError(f"status must be 'started' or 'done', got: {status!r}")
-    with consumers_mutex(plan_run_root.name):
+    with consumers_mutex(plan_run_root):
         existing = read_consumers(plan_run_root)
         for row in existing:
             if (row.get("impl_task_key") == impl_task_key

package/runtime/python/okstra_ctl/fanout.py

@@ -0,0 +1,35 @@
+"""fan-out unit 의존 그래프: 위상정렬 + 순환검출 (Kahn, id 사전순 결정적)."""
+from __future__ import annotations
+
+
+class CycleError(ValueError):
+    """depends-on 그래프에 순환이 있을 때."""
+
+
+def topological_order(units: dict[str, list[str]]) -> list[str]:
+    """unit-id 를 착수 가능한 순서(의존 먼저)로 반환.
+
+    units: unit-id -> 그 unit 이 의존하는 unit-id 목록.
+    순환이면 CycleError, 알 수 없는 의존이면 ValueError.
+    """
+    indeg = {u: 0 for u in units}
+    for u, deps in units.items():
+        for d in deps:
+            if d not in units:
+                raise ValueError(f"unit {u!r} depends on unknown unit {d!r}")
+            indeg[u] += 1
+    queue = sorted(u for u, n in indeg.items() if n == 0)
+    order: list[str] = []
+    while queue:
+        u = queue.pop(0)
+        order.append(u)
+        for v, deps in units.items():
+            if u in deps:
+                indeg[v] -= 1
+                if indeg[v] == 0:
+                    queue.append(v)
+        queue.sort()
+    if len(order) != len(units):
+        remaining = sorted(set(units) - set(order))
+        raise CycleError(f"dependency cycle among units: {remaining}")
+    return order

package/runtime/python/okstra_ctl/migrate.py

@@ -6,13 +6,11 @@
 - `prepare_migration_plan(project_root)` 는 부수효과 없이 변경 항목만 수집.
 - `apply_migration_plan(plan, *, dry_run=True)` 가 실제 실행. dry-run 이 default.
 - 가드: `.okstra/` 이미 존재 / `.project-docs/okstra/` 없음 / git 미사용 fallback.
-- 다음 다섯 가지 변경만 수행 (그 외 파일은 절대 건드리지 않음):
+- 다음 네 가지 변경만 수행 (그 외 파일은 절대 건드리지 않음):
     1. `git mv .project-docs/okstra .okstra` (git 없으면 일반 `mv`).
     2. `.project-docs/` 가 비면 `rmdir .project-docs`.
-    3. `<PROJECT_ROOT>/CLAUDE.md` 의 `@.project-docs/okstra/CLAUDE.md` import
-       라인을 `@.okstra/CLAUDE.md` 로 교체.
-    4. `.gitignore` 의 `.project-docs/okstra/` 항목을 `.okstra/` 로 교체.
-    5. `~/.okstra/{recent,active}.jsonl` 와 `~/.okstra/worktrees/registry.json`
+    3. `.gitignore` 의 `.project-docs/okstra/` 항목을 `.okstra/` 로 교체.
+    4. `~/.okstra/{recent,active}.jsonl` 와 `~/.okstra/worktrees/registry.json`
        의 해당 프로젝트 path 항목 갱신 (project_root 가 정확히 일치하는 row 만).
 """
 from __future__ import annotations
@@ -26,8 +24,6 @@ from pathlib import Path
 from typing import Optional
 
 from okstra_project.dirs import (
-    CLAUDE_MD_IMPORT_LINE,
-    LEGACY_CLAUDE_MD_IMPORT_LINE,
     LEGACY_OKSTRA_DIR_NAME,
     LEGACY_OKSTRA_RELATIVE,
     OKSTRA_DIR_NAME,
@@ -51,7 +47,6 @@ class MigrationPlan:
     target_dir: Path  # <project>/.okstra
     use_git: bool
     remove_empty_parent: bool  # True if .project-docs would be empty after move
-    claude_md_path: Optional[Path]  # <project>/CLAUDE.md if import-line update needed
     gitignore_path: Optional[Path]  # <project>/.gitignore if entry update needed
     registry_updates: list[dict] = field(default_factory=list)
     # Each registry entry: {"file": "<abs path>", "row_count": N, "scope": "..."}
@@ -63,7 +58,6 @@ class MigrationPlan:
             "targetDir": str(self.target_dir),
             "useGit": self.use_git,
             "removeEmptyParent": self.remove_empty_parent,
-            "claudeMdPath": str(self.claude_md_path) if self.claude_md_path else None,
             "gitignorePath": str(self.gitignore_path) if self.gitignore_path else None,
             "registryUpdates": self.registry_updates,
         }
@@ -78,7 +72,6 @@ class MigrationResult:
     dry_run: bool
     moved: bool
     parent_removed: bool
-    claude_md_updated: bool
     gitignore_updated: bool
     registry_rows_updated: int
 
@@ -87,7 +80,6 @@ class MigrationResult:
             "dryRun": self.dry_run,
             "moved": self.moved,
             "parentRemoved": self.parent_removed,
-            "claudeMdUpdated": self.claude_md_updated,
             "gitignoreUpdated": self.gitignore_updated,
             "registryRowsUpdated": self.registry_rows_updated,
         }
@@ -124,16 +116,6 @@ def prepare_migration_plan(
     parent = source.parent  # <project>/.project-docs
     remove_empty_parent = _would_be_empty_after_remove(parent, source)
 
-    claude_md = project_root / "CLAUDE.md"
-    claude_md_path: Optional[Path] = None
-    if claude_md.is_file():
-        try:
-            text = claude_md.read_text(encoding="utf-8")
-        except OSError:
-            text = ""
-        if LEGACY_CLAUDE_MD_IMPORT_LINE in text:
-            claude_md_path = claude_md
-
     gitignore = project_root / ".gitignore"
     gitignore_path: Optional[Path] = None
     if gitignore.is_file():
@@ -154,7 +136,6 @@ def prepare_migration_plan(
         target_dir=target,
         use_git=use_git,
         remove_empty_parent=remove_empty_parent,
-        claude_md_path=claude_md_path,
         gitignore_path=gitignore_path,
         registry_updates=registry_updates,
     )
@@ -179,14 +160,12 @@ def apply_migration_plan(
             dry_run=True,
             moved=False,
             parent_removed=False,
-            claude_md_updated=False,
             gitignore_updated=False,
             registry_rows_updated=0,
         )
 
     _do_move(plan)
     parent_removed = _maybe_remove_empty_parent(plan)
-    claude_md_updated = _update_claude_md(plan)
     gitignore_updated = _update_gitignore(plan)
     registry_rows_updated = _apply_registry_updates(
         plan, okstra_home=_resolve_okstra_home(okstra_home)
@@ -196,7 +175,6 @@ def apply_migration_plan(
         dry_run=False,
         moved=True,
         parent_removed=parent_removed,
-        claude_md_updated=claude_md_updated,
         gitignore_updated=gitignore_updated,
         registry_rows_updated=registry_rows_updated,
     )
@@ -272,17 +250,6 @@ def _maybe_remove_empty_parent(plan: MigrationPlan) -> bool:
     return False
 
 
-def _update_claude_md(plan: MigrationPlan) -> bool:
-    if plan.claude_md_path is None:
-        return False
-    text = plan.claude_md_path.read_text(encoding="utf-8")
-    new_text = text.replace(LEGACY_CLAUDE_MD_IMPORT_LINE, CLAUDE_MD_IMPORT_LINE)
-    if new_text == text:
-        return False
-    plan.claude_md_path.write_text(new_text, encoding="utf-8")
-    return True
-
-
 def _update_gitignore(plan: MigrationPlan) -> bool:
     if plan.gitignore_path is None:
         return False
@@ -307,6 +274,16 @@ def _update_gitignore(plan: MigrationPlan) -> bool:
     return True
 
 
+def _mentions_project_path(haystack: str, project_str: str) -> bool:
+    """haystack 이 project_root 를 '경로로서' 언급하는지.
+
+    `project_str in haystack` 단순 substring 은 `/x/app` 가 `/x/app-v2/...` 에도
+    매칭되어 형제 prefix 프로젝트의 행을 잘못 잡는다. 경로 구분자(`/`)나 JSON
+    닫는 따옴표(`"`) 같은 경계가 뒤따를 때만 매칭해 prefix 오인을 막는다.
+    """
+    return f"{project_str}/" in haystack or f'{project_str}"' in haystack
+
+
 def _scan_registries(project_root: Path, *, okstra_home: Path) -> list[dict]:
     """Find okstra-home registry files that reference this project's old path."""
     project_str = str(project_root)
@@ -321,7 +298,9 @@ def _scan_registries(project_root: Path, *, okstra_home: Path) -> list[dict]:
         except OSError:
             continue
         count = sum(
-            1 for ln in lines if legacy_marker in ln or project_str in ln and ".project-docs/okstra" in ln
+            1 for ln in lines
+            if legacy_marker in ln
+            or (_mentions_project_path(ln, project_str) and LEGACY_OKSTRA_DIR_NAME in ln)
         )
         if count > 0:
             updates.append({"file": str(path), "rowCount": count, "scope": name})
@@ -331,8 +310,8 @@ def _scan_registries(project_root: Path, *, okstra_home: Path) -> list[dict]:
             text = registry.read_text(encoding="utf-8")
         except OSError:
             text = ""
-        if ".project-docs/okstra" in text and project_str in text:
-            updates.append({"file": str(registry), "rowCount": text.count(".project-docs/okstra"), "scope": "worktrees-registry"})
+        if LEGACY_OKSTRA_DIR_NAME in text and _mentions_project_path(text, project_str):
+            updates.append({"file": str(registry), "rowCount": text.count(LEGACY_OKSTRA_DIR_NAME), "scope": "worktrees-registry"})
     return updates
 
 
@@ -354,7 +333,7 @@ def _apply_registry_updates(plan: MigrationPlan, *, okstra_home: Path) -> int:
         new_lines: list[str] = []
         changed = 0
         for line in text.splitlines(keepends=True):
-            if project_str in line and LEGACY_OKSTRA_DIR_NAME in line:
+            if _mentions_project_path(line, project_str) and LEGACY_OKSTRA_DIR_NAME in line:
                 new_lines.append(line.replace(LEGACY_OKSTRA_DIR_NAME, OKSTRA_DIR_NAME))
                 changed += 1
             else:
@@ -372,7 +351,7 @@ def _apply_registry_updates(plan: MigrationPlan, *, okstra_home: Path) -> int:
         # otherwise leave it alone (covers the case where registry.json
         # contains an unrelated `.project-docs/okstra` literal in someone
         # else's row).
-        if project_str in text and LEGACY_OKSTRA_DIR_NAME in text:
+        if _mentions_project_path(text, project_str) and LEGACY_OKSTRA_DIR_NAME in text:
             new_text = _replace_in_project_rows(text, project_str)
             if new_text != text:
                 registry.write_text(new_text, encoding="utf-8")
@@ -397,7 +376,7 @@ def _replace_in_project_rows(text: str, project_str: str) -> str:
     changed = False
     for key, row in data.items():
         row_text = json.dumps(row)
-        if project_str not in row_text or LEGACY_OKSTRA_DIR_NAME not in row_text:
+        if not _mentions_project_path(row_text, project_str) or LEGACY_OKSTRA_DIR_NAME not in row_text:
             continue
         new_row_text = row_text.replace(LEGACY_OKSTRA_DIR_NAME, OKSTRA_DIR_NAME)
         if new_row_text != row_text:

package/runtime/python/okstra_ctl/reconcile.py

@@ -93,7 +93,7 @@ def _reconcile_active_locked(home: Path, *,
                              abort_after_seconds: int,
                              project: Optional[str] = None) -> dict:
     active = home / "active.jsonl"
-    summary = {"completed": 0, "aborted": 0, "running": 0}
+    summary = {"completed": 0, "failed": 0, "aborted": 0, "running": 0}
     rows = read_jsonl(active)
     if not rows:
         return summary
@@ -128,7 +128,7 @@ def _reconcile_active_locked(home: Path, *,
                 if row["status"] == "completed":
                     summary["completed"] += 1
                 else:
-                    summary["completed"] += 0  # 실패도 종결로 분류하지만 카운터는 분리
+                    summary["failed"] += 1
                 continue
         started = _parse_iso(row.get("startedAt", ""))
         if started and (now - started).total_seconds() > abort_after_seconds:

package/runtime/python/okstra_ctl/render_final_report.py

@@ -33,7 +33,6 @@ from typing import Any
 # downstream ``from jinja2 import ...`` resolves to the vendored copy.
 import okstra_vendor  # noqa: F401 — side effect: sys.modules aliases
 from jinja2 import ChainableUndefined, Environment, FileSystemLoader
-from jinja2 import select_autoescape  # noqa: F401 — kept for future HTML use
 
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 

package/runtime/python/okstra_ctl/run.py

@@ -54,12 +54,8 @@ from .render import (
 )
 from .run_context import compute_and_write_run_context, write_run_inputs
 from .seeding import (
-    AgentsMdLinkError,
-    ClaudeMdLinkError,
     SettingsLinkError,
     cleanup_obsolete_generated_docs,
-    ensure_project_agents_md,
-    ensure_project_claude_md,
     ensure_project_settings_symlink,
     installed_version,
     verify_installation,
@@ -1046,31 +1042,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
                     file=__import__("sys").stderr,
                 )
 
-        try:
-            claude_md_link = ensure_project_claude_md(project_root=Path(inp.project_root))
-        except ClaudeMdLinkError as exc:
-            print(
-                f"okstra-claude-md: failed to provision project CLAUDE.md import — "
-                f"Claude Code sessions in this project will not auto-load okstra guidance. ({exc})",
-                file=__import__("sys").stderr,
-            )
-        else:
-            if claude_md_link is None:
-                print(
-                    "okstra-claude-md: ~/.okstra/templates/okstra.CLAUDE.md missing — "
-                    "re-run 'npx okstra@latest install' to provision the symlink target.",
-                    file=__import__("sys").stderr,
-                )
-
-        try:
-            ensure_project_agents_md(project_root=Path(inp.project_root))
-        except AgentsMdLinkError as exc:
-            print(
-                f"okstra-agents-md: failed to provision <PROJECT>/AGENTS.md symlink — "
-                f"codex / aider sessions in this project will not auto-load okstra guidance. ({exc})",
-                file=__import__("sys").stderr,
-            )
-
     return PrepareOutputs(
         ctx=ctx,
         prompt_text=prompt_text,

package/runtime/python/okstra_ctl/run_context.py

@@ -50,15 +50,6 @@ def _task_lock_path(task_key: str) -> Path:
     return locks / f"{safe}.lock"
 
 
-def _consumers_lock_path(plan_task_key: str) -> Path:
-    """plan-task-key 별 consumers.jsonl append mutex."""
-    home = _okstra_home()
-    locks = home / ".locks"
-    locks.mkdir(parents=True, exist_ok=True)
-    safe = plan_task_key.replace("/", "_").replace(":", "_")
-    return locks / f"{safe}.consumers.lock"
-
-
 @contextmanager
 def task_mutex(task_key: str) -> Iterator[None]:
     """task-key per-process mutex. 동시 호출은 락 안에서 직렬화된다."""
@@ -73,9 +64,15 @@ def task_mutex(task_key: str) -> Iterator[None]:
 
 
 @contextmanager
-def consumers_mutex(plan_task_key: str) -> Iterator[None]:
-    """plan-task-key 별 consumers.jsonl append mutex."""
-    path = _consumers_lock_path(plan_task_key)
+def consumers_mutex(plan_run_root: Path) -> Iterator[None]:
+    """plan run-root 별 consumers.jsonl append mutex.
+
+    lock 은 consumers.jsonl 과 같은 디렉토리에 두어 run-root 마다 1:1 로
+    격리한다. 마지막 경로 세그먼트(예: seq ``001``)만 키로 쓰면 서로 다른
+    task/project 의 동일 seq run 이 같은 lock 을 공유하므로 금지.
+    """
+    plan_run_root.mkdir(parents=True, exist_ok=True)
+    path = plan_run_root / ".consumers.lock"
     path.touch(exist_ok=True)
     with path.open("r+") as f:
         fcntl.flock(f.fileno(), fcntl.LOCK_EX)