okstra 0.206.0 → 0.206.1

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

@@ -91,7 +91,7 @@ profile document.
   - if a schema-v1 table or an analysis-worker result table requires a recommended answer, alternatives, or an evidence-check note, encode it inside the existing 4-column schema: put evidence notes in `Statement` as `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>`, and put recommendations/options in `Expected form` as `Recommended: (a) <answer> — <rationale>; Alternatives: (b) <option> (c) <option>`. The recommended answer is always the first option and MUST carry the `(a)` label; alternatives continue the same letter sequence from `(b)` (a lone alternative is `(b) <option>`, never restart at `(a)`), so the full option set reads `(a) (b) (c) …` in order and renders each as its own selectable option. Do **not** append a pick-one answer-space summary such as `(pick 1 of A / B)` or `(pick N of …)` to `<options>` — the rendered `<select>` already enforces single choice, and that annotation leaks verbatim into an option label. Do not add `Recommended`, `Evidence`, `Alternatives`, or `evidence-checked` columns, and do not break the merged record-meta cell back into separate columns.
   - For schema v2, data.json is canonical and the HTML exports answers to a user-response sidecar; the source report is never edited. `--resume-clarification` carries those answers into the next run. The lower-level `--clarification-response <path>` remains available for scripted runs.
   - When a response is carried in, reconcile every prior `clarificationItems[]` row against new evidence and update its status to `resolved` or `obsolete` before issuing the next verdict. Schema-v1 compatibility Markdown may additionally render its conditional Section 0; the schema-v2 full reading copy records decisions under `## Clarification and User Decisions`.
-  - **Supersession (BLOCKING).** Reconciling the `C-*` row is only half of incorporating an answer. An answer does not merely *add* a decision — it *invalidates* whatever the previous run wrote under the opposite assumption. Before issuing the next decision, walk the prior deliverable prose for every statement the answer makes false and **delete or rewrite it**, then record the retirement. Adding the new decision while leaving the contradicting sentence in place puts two opposite instructions for the same symbol in one document; the implementer must then guess which is live, and the next verification round correctly blocks on it. In `implementation-planning` this record is `implementationPlanning.supersessionLedger[]` — one entry per answered clarification, either `disposition: superseded` (with the retired statement, its replacement, and the sections revised) or `disposition: no-dependent-statement` (with a rationale). A plan built from a selected direction inherits the answers the option-selection record carried before it has any statement to retire, so those carried rows need no entry; the rows this plan itself raised and settled still do. **Enforced:** `validators/validate-run.py` `_validate_supersession_ledger` requires an entry per answered clarification, exempting the ledger's `carriedDecisions[]` ids on a selected-direction plan; whether the claim is *true* is what the §5.5.9 adversarial round tests.
+  - **Supersession (BLOCKING).** Reconciling the `C-*` row is only half of incorporating an answer. An answer does not merely *add* a decision — it *invalidates* whatever the previous run wrote under the opposite assumption. Before issuing the next decision, walk the prior deliverable prose for every statement the answer makes false and **delete or rewrite it**, then record the retirement. Adding the new decision while leaving the contradicting sentence in place puts two opposite instructions for the same symbol in one document; the implementer must then guess which is live, and the next verification round correctly blocks on it. In `implementation-planning` this record is `implementationPlanning.supersessionLedger[]` — one entry per answered clarification, either `disposition: superseded` (with the retired statement, its replacement, and the sections revised) or `disposition: no-dependent-statement` (with a rationale). A plan built from a selected direction inherits the answers the option-selection record carried before it has any statement to retire, so those carried rows need no entry; the rows this plan itself raised and settled still do. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_supersession_ledger` requires an entry per answered clarification, exempting the ledger's `carriedDecisions[]` ids on a selected-direction plan; whether the claim is *true* is what the §5.5.9 adversarial round tests.
 - Verdict Card data consistency (shared; schema-v1 Markdown keeps the legacy visible card):
   - The Card carries no verdict token — the token lives once, in `finalVerdict.verdictToken`, and every gate reads it there. `verdictCard.direction` byte-matches `finalVerdict.direction`; next-step routing agrees with `recommendedNextSteps[0]`. The full reading copy and human summary are derived from the data fields without repeating both visible sections. **Enforced in part:** the v3.0 schema's `verdictCard` is `additionalProperties: false` with no verdict-token property, so the token cannot be duplicated onto the Card, and `scripts/okstra_ctl/report_narrative.py` `writer_owned_schema` applies the finished report's `$defs.Direction` enum to the narrative, rejecting an off-enum `direction` while the writer can still be re-run. The byte-match between the two `direction` fields is not compared by anything — assembly overwrites `nextStep` on both when the plan-body gate passes (`scripts/okstra_ctl/report_assembly.py:590-604`) but leaves `direction` as the writer wrote it.
 - Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 6.` / `## 2.` tables in the final-report):

package/runtime/prompts/profiles/_coverage-critic.md

@@ -14,4 +14,4 @@ mode:" when the include directive (placed at column 0) is resolved in-place.
 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.
 -->
-  - **Coverage critic (opt-in, one slot)**: critic `min` is 0 and `recommended`/`max` are 1 — the wizard asks whether to add the slot with 1 recommended, and the user picks the model when they add it (`--role-model critic=<provider>/<model>` or the wizard role-model step). `--critic off` and a 0-count selection are both accepted; the run then dispatches no critic pass, and an analyser 1-1 tie stays `needs-reverify` with no slot to settle it — `okstra plan-items next-dispatch` answers `user-decision` for those items and the lead opens an approval decision instead of another round. A reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface **both** findings nobody covered and work the findings propose that no requirement asked for (`category: "unrequested-scope"`); its candidates are judged only after a 1-round adversarial reverify that follows convergence. The two halves are disposed of differently — a contested coverage gap is dropped as a hallucination, while a contested over-scope candidate is recorded as a `## 5. Missing Information and Risks` row instead of vanishing. In `implementation-planning`, the same critic slot also settles plan-body 1-1 splits (`critic-worker` on `--tie-vote` items only). See `prompts/lead/convergence.md` "Coverage critic pass" and `prompts/lead/plan-body-verification.md` even-split rule.
+  - **Coverage critic (opt-in, one slot)**: critic `min` is 0 and `recommended`/`max` are 1 — the wizard asks whether to add the slot with 1 recommended, and the user picks the model when they add it (`--role-model critic=<provider>/<model>` or the wizard role-model step). `--critic off` and a 0-count selection are both accepted; the run then dispatches no critic pass, and an analyser 1-1 tie stays `needs-reverify` with no slot to settle it — `okstra plan-items next-dispatch` answers `user-decision` for those items and the lead opens an approval decision instead of another round. A reused-worker critic pass is dispatched concurrently with the first convergence reverify round to surface **both** findings nobody covered and work the findings propose that no requirement asked for (`category: "unrequested-scope"`); its candidates are judged only after a 1-round adversarial reverify that follows convergence. The two halves are disposed of differently — a contested coverage gap is dropped as a hallucination, while a contested over-scope candidate is recorded as a `## 5. Missing Information and Risks` row instead of vanishing. In `implementation-planning`, the same critic slot also settles plan-body 1-1 splits (`critic-worker` on `--tie-vote` items only). See `prompts/lead/convergence.md` "Coverage critic pass" and `scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` even-split rule.

package/runtime/prompts/profiles/forbidden-actions.json

@@ -1,100 +1,6 @@
 {
-  "requirements-discovery": [
-    "source code edits of any kind",
-    "implementation planning or detailed design beyond what is required to choose the next phase",
-    "executing builds, migrations, deployments, or any state-mutating command",
-    "starting `error-analysis`, `implementation-planning`, or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
-  ],
-  "improvement-discovery": [
-    "source code edits of any kind",
-    "implementation planning, root-cause analysis, builds, migrations, or deployments",
-    "starting `implementation-planning`, `implementation`, `error-analysis`, or any other lifecycle phase inside this run",
-    "generating candidates outside the lens whitelist (Lens enum violation rejects the report)",
-    "exceeding the candidate cap (absolute cap 12)",
-    "free external data fetch beyond the brief's Source Material or Phase 1.5 resolved scope",
-    "interpreting user phrases like `다음 단계 진행해` as authorisation to enter another phase"
-  ],
-  "project-analysis": [
-    "source or configuration edits",
-    "tests, builds, migrations, or deployments",
-    "starting any other lifecycle phase inside this run"
-  ],
-  "feature-analysis": [
-    "source or configuration edits",
-    "tests, builds, migrations, or deployments",
-    "starting any other lifecycle phase inside this run"
-  ],
-  "change-impact-analysis": [
-    "source or configuration edits",
-    "tests, builds, migrations, or deployments",
-    "starting any other lifecycle phase inside this run",
-    "implementation alternatives",
-    "file change specifications",
-    "stepwise execution plans"
-  ],
-  "error-analysis": [
-    "source code edits, refactors, or fix attempts",
-    "implementation design or planning artifacts",
-    "executing builds, migrations, deployments, or any state-mutating command",
-    "starting `implementation-planning` or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
-  ],
-  "implementation-option-selection": [
-    "source or configuration edits, refactors, or fix attempts",
-    "tests, builds, migrations, deployments, or any state-mutating command",
-    "detailed file lists, stage maps, execution commands, or plan approval",
-    "starting `implementation-planning` or `implementation` inside this run",
-    "displaying more than three merged candidates or omitting rejected-candidate audit records"
-  ],
-  "implementation-planning": [
-    "source code edits of any kind (Edit/Write on project source files is forbidden)",
-    "file writes outside the run`s artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`), including task-root QA scripts, manifest, and tsconfig (planning declares conformance commands and required dependencies; implementation writes these files); in particular, do not write to `docs/superpowers/specs/` or `docs/superpowers/plans/`",
-    "executing builds, migrations, deployments, or any state-mutating command",
-    "starting `implementation` inside this run (must be a separate run authorised by an approved deliverable from this phase), even if the user says \"다음 단계 진행해\"",
-    "dispatching parallel sub-agents beyond the required worker roster (okstra owns worker fan-out)",
-    "leaving placeholders such as TBD / TODO / \"handle edge cases\" / \"similar to Option N\" in the report",
-    "delegating the self-review pass — the Okstra lead must run it"
-  ],
-  "implementation": [
-    "any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md whose frontmatter has `approved: true`)",
-    "`git push` of any kind (including `--dry-run` against a real remote that produces side-effects), `npm publish` / `cargo publish` / `pip publish`, `gh release`, `docker push`",
-    "real database migrations, schema changes against shared environments, or writes to non-local datastores",
-    "production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)",
-    "external API write calls (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures",
-    "source edits or Bash mutations performed by any verifier role (`Antigravity verifier`, `Codex verifier`, `Claude verifier` are read-only — recommend, do not apply)",
-    "dispatching parallel sub-agents beyond the required worker roster",
-    "silent scope expansion: every file edited outside the approved plan list MUST appear in the `Out-of-plan edits` block with rationale",
-    "leaving placeholders such as TBD / TODO / \"implement later\" / \"handle edge cases\" in newly-added lines of this run (check via `git diff <base>..HEAD | grep -E '^\\+[^+].*\\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\\b'`; pre-existing strings in untouched regions are out of scope)",
-    "lead substituting its own verdict when every verifier present in the resolved roster returned a non-result terminal status (`timeout`/`error`/`not-run`); in that case the run MUST end as `blocked` with routing recommendation back to `error-analysis`, never with a lead-only verdict",
-    "declaring overall task acceptance — that is `final-verification` ownership; this phase reports only \"ready for final-verification\" or \"needs new planning loop\"",
-    "delegating the self-review pass — the Okstra lead must run it"
-  ],
-  "final-verification": [
-    "source code edits, follow-up bug fixes, or scope expansion",
-    "state-mutating commands against the project or shared environments; permitted mutations are limited to the run's own `.okstra` artifacts (reports, state, `<task_root>/qa/result-*.json` sidecars, `okstra handoff record-verified` on acceptance) and Tier3 conformance scripts that mutate only their qaEnv replica datastore — everything else is read-only execution of pre-existing test or validation commands",
-    "starting any follow-up phase inside this run; record findings and end the run"
-  ],
-  "release-handoff": [
-    "entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited",
-    "local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` / `git rebase --onto` / `git cherry-pick` / `git commit --amend` run by the lead. The single exception is the merge commits `okstra handoff pr-plan` itself creates on a `merge-base` branch — the lead never merges by hand. Rewriting a stage branch breaks the PR stack that sits on it.",
-    "any git push variant that rewrites remote history, regardless of intent or whether the user said \"force it\": `git push --force`, `git push --force-with-lease`, `git push -f`, `git push +<refspec>`, or any other history-rewriting invocation",
-    "pushing directly to a release base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the release base in this run. The only permitted push targets are the branches `okstra handoff pr-plan` listed for this run (each stage `head_branch`, and any `merge-base` branch).",
-    "bypassing repo safeguards: `--no-verify` / `-n` on `git push`, bypassing GPG signing, disabling safeguards via equivalent flags, or any hook bypass.",
-    "release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.",
-    "source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.",
-    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local checkout`; pushing when the user picked `skip`; switching the release base branch silently after the user already chose one; opening a PR for a stage outside `HANDOFF_STAGES`.",
-    "squash-merging, or instructing anyone to squash-merge, a stage PR — and `gh pr merge` in any form. A squash replaces the commits the next stage's PR base points at, so the stack breaks; the PR body states merge-commit-or-rebase and the lead never merges.",
-    "retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.",
-    "worker dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Okstra lead.",
-    "silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim."
-  ],
   "unknown": [
     "any action that belongs to a different lifecycle phase",
     "source code edits or state-mutating commands unless this task type explicitly authorises them"
-  ],
-  "technical-verification": [
-    "source edits or installs in the project checkout, task worktree, or another worker's experiment copy",
-    "production credentials, remote writes, deployments, migrations, publishing, commits or merging experiments into product branches",
-    "marking candidates feasible, selecting a direction, approving a plan, or declaring task acceptance",
-    "starting another lifecycle phase inside this run; return the evidence to implementation-option-selection"
   ]
 }

package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py

@@ -25,7 +25,7 @@ from ..activity import (
 )
 from ...final_report_schema import load_schema_version
 from ...json_boundary import load_owned_object
-from ...implementation_options import validate_implementation_option_selection
+from ...phases.implementation_option_selection.validation import validate_implementation_option_selection
 from ...report_contract import TASK_TYPE_DATA_PROPERTY
 from ...report_assembly import validate_plan_draft
 from ...report_corrections import (

package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py

@@ -34,7 +34,11 @@ from ...assignment_environment import load_assignment_context
 from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignment
 from ...path_hints import hydrate_active_run_context
 from ...worker_prompt_headers import worker_prompt_headers
-from ...worker_prompt_contract import complete_reverify_instruction, validate_reverify_prompt
+from ...worker_prompt_contract import (
+    complete_reverify_instruction,
+    validate_plan_verify_dispatch_identity,
+    validate_reverify_prompt,
+)
 from ...worker_prompt_policy import (
     critic_assignment_ref,
     is_plan_critic_verification,
@@ -340,6 +344,11 @@ def _materialize_run(
         active_context=active_context,
     ))
     body = instruction_path.read_text(encoding="utf-8")
+    identity_errors = validate_plan_verify_dispatch_identity(
+        body, dispatch_kind=args.dispatch_kind, result_name=result_path.name,
+    )
+    if identity_errors:
+        raise AgentPromptCliError("; ".join(identity_errors))
     is_reverify = is_verification_dispatch_kind(args.dispatch_kind)
     if is_reverify:
         body = _complete_run_reverify_body(args, manifest, active_context, assignment, body, instruction_path)

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -73,7 +73,6 @@ _EVIDENCE_RELATION_BY_TYPES = {
 _REPORT_NAME_RE = re.compile(
     r"^final-report-.+-(?P<run_seq>[^-]+)\.data\.json$"
 )
-_FEATURE_ID_RE = re.compile(r"PF-\d{3}")
 _FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
 _RUN_SEQ_RE = re.compile(r"[0-9]{3}")
 
@@ -347,41 +346,3 @@ def resolve_evidence_inputs(
             freshness="exact" if candidate.source_commit == current_commit else "stale",
         ))
     return tuple(resolved)
-
-
-def resolve_analysis_target(
-    raw_target: str,
-    evidence_inputs: Sequence[ResolvedEvidenceInput],
-    candidates: Mapping[Path, AnalysisReportCandidate],
-) -> dict[str, object]:
-    """Normalize a feature-index identifier or a non-empty free-text target."""
-    target = raw_target.strip()
-    if not target:
-        raise AnalysisInputError("analysis target must not be empty")
-    if not _FEATURE_ID_RE.fullmatch(target):
-        return {"inputMode": "free-text", "requestedValue": target}
-    matches: list[dict[object, object]] = []
-    for evidence in evidence_inputs:
-        if evidence.relation != "project-context":
-            continue
-        candidate = candidates.get(evidence.report_path)
-        if candidate is None:
-            candidate = next(
-                (value for path, value in candidates.items() if path.resolve() == evidence.report_path),
-                None,
-            )
-        if candidate is None:
-            continue
-        matches.extend(
-            feature for feature in candidate.feature_index
-            if isinstance(feature, dict) and feature.get("id") == target
-        )
-    if len(matches) != 1:
-        raise AnalysisInputError(
-            f"exactly one project-context feature must match {target}"
-        )
-    return {
-        "inputMode": "feature-index",
-        "requestedValue": target,
-        "feature": dict(matches[0]),
-    }

package/runtime/python/okstra_ctl/analysis_scope.py

@@ -0,0 +1,31 @@
+"""분석 증거와 단계 내용 검증이 공유하는 프로젝트 상대 경로 판독."""
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+
+def _normalized_project_path(path: object) -> PurePosixPath | None:
+    if not isinstance(path, str):
+        return None
+    raw = path.strip().rstrip("/")
+    if not raw or raw == "." or raw.startswith("/"):
+        return None
+    if any(part in {"", ".", ".."} for part in raw.split("/")):
+        return None
+    normalized = PurePosixPath(raw)
+    if normalized.is_absolute():
+        return None
+    return normalized
+
+
+def _path_is_included(path: object, included_paths: list[object]) -> bool:
+    candidate = _normalized_project_path(path)
+    if candidate is None:
+        return False
+    for raw in included_paths:
+        included = _normalized_project_path(raw)
+        if included is not None and (
+            candidate == included or included in candidate.parents
+        ):
+            return True
+    return False

package/runtime/python/okstra_ctl/asset_roots.py

@@ -0,0 +1,19 @@
+"""Ancestor-based runtime asset lookup independent of run and phase state."""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+
+def walk_to_asset_root(
+    relative: Sequence[str],
+    *,
+    start: Path,
+    is_present: Callable[[Path], bool] = Path.is_file,
+) -> Path | None:
+    """Return the nearest ancestor carrying the asset without home overrides."""
+    here = Path(start).resolve()
+    for parent in [here, *here.parents]:
+        if is_present(parent.joinpath(*relative)):
+            return parent
+    return None

package/runtime/python/okstra_ctl/consumers.py

@@ -430,3 +430,15 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
         settled_stages.add(stage)
         recovered += 1
     return recovered
+
+
+def require_done_task_key(rows: List[Dict[str, Any]], stage: int) -> str:
+    from .handoff_error import HandoffError
+
+    done = latest_done_by_stage(rows)
+    row = done.get(stage)
+    if not row:
+        raise HandoffError(
+            f"stage {stage} has no done row in consumers.jsonl — "
+            "finish the implementation stage first")
+    return row.get("impl_task_key", "")

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -59,6 +59,7 @@ from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
+    validate_plan_verify_dispatch_identity,
     validate_prompt_model_header,
     validate_reverify_prompt,
 )
@@ -1905,6 +1906,26 @@ def validate_initial_prompts(
         raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
 
 
+def _validate_plan_verify_identities(jobs: Sequence[WorkerJob]) -> None:
+    errors: list[str] = []
+    for job in jobs:
+        try:
+            text = job.prompt_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            errors.append(f"{job.worker_id}: cannot read prompt {job.prompt_path}: {exc}")
+            continue
+        errors.extend(
+            f"{job.worker_id}: {error}"
+            for error in validate_plan_verify_dispatch_identity(
+                text,
+                dispatch_kind=job.dispatch_kind,
+                result_name=job.worker_result_path.name,
+            )
+        )
+    if errors:
+        raise DispatchError("plan-body dispatch contract: " + "; ".join(errors))
+
+
 def validate_dispatch_prompts(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],
@@ -1912,6 +1933,7 @@ def validate_dispatch_prompts(
 ) -> None:
     if isinstance(manifest.get("agentContract"), Mapping):
         _validate_agent_invocations(manifest, jobs)
+    _validate_plan_verify_identities(jobs)
     initial_jobs = [
         job for job in jobs if not is_verification_dispatch_kind(job.dispatch_kind)
     ]

package/runtime/python/okstra_ctl/doctor.py

@@ -11,7 +11,8 @@ from typing import Iterable
 from okstra_project import ResolverError, project_json_path, resolve_project_root
 from okstra_project.resolver import resolve_review_rule_packs
 
-from . import improvement_lenses, worktree_registry
+from . import worktree_registry
+from .phases.improvement_discovery import lenses as improvement_lenses
 from .models import provider_wrappers
 from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
 from .workers import resolve_profile_workers

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -281,7 +281,8 @@ class ExecutionMutationAudit:
             + tuple(f"unattributed change outside assigned worktree and artifact paths: {path}"
                     for path in sorted(external))
             + _plan_change_warnings(rows, source_changes | untracked_changes,
-                                    artifact_changed, out_of_plan_edits, unobserved),
+                                    artifact_changed, out_of_plan_edits, unobserved)
+            + _linked_dependency_warnings(after.root),
             changed_artifact_paths=tuple(sorted(artifact_changed - external)),
             declared_out_of_plan_paths=tuple(out_of_plan_edits),
             unobserved_artifact_paths=tuple(sorted(unobserved)),
@@ -370,6 +371,31 @@ def _audit_warnings(untracked_artifact_changes: set[str]) -> tuple[str, ...]:
     )
 
 
+def _linked_dependency_warnings(root: Path) -> tuple[str, ...]:
+    """worktree 밖을 가리키는 `node_modules` 링크를 알린다.
+
+    감사는 `node_modules` 를 보지 않으므로, 그 링크를 통한 패키지 설치가 메인
+    체크아웃의 의존성 트리를 덮어써도 흔적이 남지 않는다(2026-09-25 실측).
+    """
+    linked: list[str] = []
+    for current, directories, _ in os.walk(root, followlinks=False):
+        kept: list[str] = []
+        for name in directories:
+            path = Path(current) / name
+            if name == ".git":
+                continue
+            if name not in _INSTALLED_DEPENDENCY_DIRS:
+                kept.append(name)
+            elif path.is_symlink() and not _is_relative_to(path.resolve(), root.resolve()):
+                linked.append(f"{path.relative_to(root).as_posix()} -> {path.resolve()}")
+        directories[:] = kept
+    return tuple(
+        f"dependency tree links outside the assigned worktree: {row}; "
+        "a package install through it rewrites that target and this audit does not observe it"
+        for row in sorted(linked)
+    )
+
+
 def _branch_switch_warnings(
     before: MutationSnapshot, after: MutationSnapshot, switched: set[str],
 ) -> tuple[str, ...]: