okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/worker_runner.py

@@ -29,6 +29,7 @@ from .domain.worker_exec import (
     WorkerExecRequest,
 )
 from .domain.worker_presentation import JsonEvents, Presentation
+from .process_group import MemoryWatch, kill_group, memory_cap_bytes
 from .session_transcript import SessionTranscript
 from .json_boundary import JsonBoundaryError, write_owned_object_atomic
 
@@ -42,6 +43,8 @@ _TERM_GRACE_SECONDS = 5
 # this only has to cover a drain, never a producer.
 _DRAIN_AFTER_EXIT_SECONDS = 2
 _TIMEOUT_EXIT_CODE = 124
+# sysexits 의 EX_OSERR. 워커 그룹이 메모리 상한을 넘어 러너가 죽인 run.
+MEMORY_CAP_EXIT_CODE = 71
 _READ_SIZE = 8192
 _WRITE_SIZE = 8192
 _NO_STATUS_EXTRA: Mapping[str, Any] = {}
@@ -66,6 +69,7 @@ def run_worker(
     _validate_status_extra(status_extra)
     _validate_request_write_contract(request, status_extra)
     command = strategy.build_command(request)
+    memory_watch = MemoryWatch(memory_cap_bytes(request.project_root))
     started_monotonic = time.monotonic()
     status = _started_status(status_extra, log_path)
     _write_status(status_path, status)
@@ -73,11 +77,12 @@ def run_worker(
 
     try:
         with guard:
-            exit_code, timed_out, idle_seconds, raw_model, usage = _launch(
+            exit_code, timed_out, idle_seconds, raw_model, usage, reaped = _launch(
                 command,
                 log_path,
                 presentation=presentation,
                 idle_timeout_seconds=request.idle_timeout_seconds,
+                memory_watch=memory_watch,
                 on_spawn=guard.watch,
             )
             at_exit = getattr(command.presentation, "served_model_at_exit", None)
@@ -107,6 +112,11 @@ def run_worker(
             if failure:
                 status["failure"] = failure
                 exit_code = SERVED_MODEL_MISMATCH_EXIT_CODE
+    if reaped:
+        status["leftoverProcessesKilled"] = True
+    if memory_watch.exceeded_bytes:
+        exit_code = MEMORY_CAP_EXIT_CODE
+        status.update(failure=memory_watch.failure(), terminated_by="memory-cap")
     status["exit_code"] = exit_code
     if timed_out:
         status.update(
@@ -176,8 +186,9 @@ def _launch(
     *,
     presentation: str,
     idle_timeout_seconds: int,
+    memory_watch: MemoryWatch,
     on_spawn: Callable[[subprocess.Popen[bytes]], None],
-) -> tuple[int, bool, int, str | None, Mapping[str, Any] | None]:
+) -> tuple[int, bool, int, str | None, Mapping[str, Any] | None, bool]:
     live = presentation == LIVE
     transcript = SessionTranscript(log_path, live=live)
     observation = _ServedModelObservation()
@@ -211,14 +222,18 @@ def _launch(
             strategy=strategy,
             presentation=presentation,
             idle_timeout_seconds=idle_timeout_seconds,
+            memory_watch=memory_watch,
             stdin_text=command.stdin_text,
         )
+        # 워커가 띄운 빌드 워커·서버는 워커가 끝나도 그룹에 남아 계속 자란다.
+        reaped = kill_group(process.pid)
         return (
             exit_code,
             timed_out,
             idle_seconds,
             observation.raw_model,
             usage_observation.usage,
+            reaped,
         )
     finally:
         transcript.close()
@@ -386,6 +401,7 @@ def _pump(
     strategy: Presentation,
     presentation: str,
     idle_timeout_seconds: int,
+    memory_watch: MemoryWatch,
     stdin_text: str | None = None,
 ) -> tuple[int, bool, int]:
     selector = selectors.DefaultSelector()
@@ -418,6 +434,7 @@ def _pump(
         ):
             timed_out = True
             _terminate(process)
+        memory_watch.check(process.pid, time.monotonic())
         drain_deadline = _drain_deadline(process, drain_deadline)
         if drain_deadline is not None and time.monotonic() >= drain_deadline:
             _stop_reading(selector)
@@ -457,7 +474,8 @@ def _drain_deadline(
     holding the write end of the pipe open for as long as it lives. The shell
     wrappers returned as soon as `wait <pid>` did, so blocking on a grandchild is
     a regression rather than a policy, and the exit code the caller gets stays
-    the worker's own.
+    the worker's own. Whatever is still in the group afterwards is killed
+    (`_launch`).
 
     The deadline is set once and never pushed back: output arriving after the
     worker exited is the grandchild's, and letting it extend the wait would

package/runtime/python/okstra_ctl/workflow.py

@@ -7,14 +7,13 @@ task/run status, render-only flag) 만 받아서 WORKFLOW_* 필드 dict 를 돌
 `okstra_ctl.next_phase` 하나가 소유하고, 값은 리포트가 저작한 라우팅에서
 투영된다.
 
-task-type 별 PHASE_ALLOWED_OUTPUTS 본문 매핑은 모듈 상수(`PHASE_RULES`)로 보유하고,
-PHASE_FORBIDDEN_ACTIONS 는 `prompts/profiles/forbidden-actions.json` SSOT 에서 로드한다.
+단계별 출력·금지 문구는 선택한 단계의 boundary.json 에서 읽는다.
 """
 from __future__ import annotations
 
-import json
 from pathlib import Path
 from .json_boundary import load_owned_object
+from .phases.catalog import phase_boundary, phase_record, task_types
 
 PHASE_SEQUENCE = [
     "requirements-discovery",
@@ -35,125 +34,6 @@ ERROR_ANALYSIS_ROUTING_DIRECTIONS = {
     "implementation-option-selection": "begin-option-selection",
 }
 
-# Phase 별 allowed outputs. bash heredoc 원문 그대로 옮긴 값 — 들여쓰기와 백틱은
-# prompt template 에 그대로 박혀 lead 가 읽는다. forbidden actions 는 이 dict 가
-# 아니라 prompts/profiles/forbidden-actions.json (load_phase_forbidden) 이 SSOT.
-PHASE_RULES: dict[str, dict[str, str]] = {
-    "technical-verification": {
-        "allowed": (
-            "  - falsifiable experiment plans for the frozen unresolved facts\n"
-            "  - dependency installation, source experiments, tests and builds only in this run's experiment copies\n"
-            "  - command logs, observed signals and per-fact supported/refuted/inconclusive/not-run results\n"
-            "  - return to implementation-option-selection with evidence, without adoption or plan approval"
-        ),
-    },
-    "requirements-discovery": {
-        "allowed": (
-            "  - work-category classification (bugfix / feature / refactor / ops / improvement)\n"
-            "  - routing decision as the `routing` object `{nextTaskType, readyWhen, rationale}`: `nextTaskType` is `error-analysis` or `implementation-option-selection` and nothing else — this phase never hands off directly to planning or implementation. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `nextTaskType`\n"
-            "  - missing-input list and clarification requests\n"
-            "  - approval / confirmation checkpoints recorded for the next phase\n"
-            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
-        ),
-    },
-    "improvement-discovery": {
-        "allowed": (
-            "  - improvement candidate discovery within the lens whitelist defined in `scripts/okstra_ctl/improvement_lenses.py`\n"
-            "  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n"
-            "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence (path:line)\n"
-            "  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n"
-            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique / unverified)"
-        ),
-    },
-    "project-analysis": {
-        "allowed": (
-            "  - components, dependency directions, entry points, repositories, and external integrations\n"
-            "  - shallow feature index and scan scope\n"
-        ),
-    },
-    "feature-analysis": {
-        "allowed": (
-            "  - confirmed target and normal, alternate, and failure flows\n"
-            "  - rules, state transitions, external calls, and test coverage scope\n"
-        ),
-    },
-    "change-impact-analysis": {
-        "allowed": (
-            "  - preserved behavior, impacted items, and dependency propagation\n"
-            "  - test and operational impact\n"
-            "  - constraints and open decisions passed to implementation-planning\n"
-        ),
-    },
-    "error-analysis": {
-        "allowed": (
-            "  - symptom and trigger evidence\n"
-            "  - root-cause hypotheses with supporting citations\n"
-            "  - reproduction gaps and missing observability\n"
-            "  - validation paths to confirm or refute hypotheses\n"
-            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
-        ),
-    },
-    "implementation-option-selection": {
-        "allowed": (
-            "  - candidate-comparison evidence for up to three options per worker\n"
-            "  - preselected-validation of exactly ONE candidate: every analyser returns its own feasibility verdict on that one direction, `candidateAudit` stays empty, and no analyser generates an alternative. It is not a re-evaluation of the merged set — `okstra_ctl.implementation_options._validate_mode` rejects a preselected-validation report carrying more than one option or a non-empty audit\n"
-            "  - a ranked display of at most three options with requirement mappings\n"
-            "  - an audit record for every rejected candidate\n"
-            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
-        ),
-    },
-    "implementation-planning": {
-        "allowed": (
-            "  - pre-planning context exploration notes (files/interfaces inspected, recent commits scanned, ambiguities flagged)\n"
-            "  - selected-direction planning: realize the one validated selected direction without reopening candidate comparison, with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
-            "  - legacy candidate-comparison planning only: at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
-            "  - legacy candidate-comparison planning only: a trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
-            "  - bite-sized stepwise execution order for the selected direction or legacy recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
-            "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
-            "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
-            "  - report record `frontmatter.approved: false` awaiting `--approve` or the in-session wizard\n"
-            "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)\n"
-            "  - one endStateCoverage row per brief end-state id, each mapped to the R-NNN row that carries it"
-        ),
-    },
-    "implementation": {
-        "allowed": (
-            "  - approved-plan reference and quoted user-approval evidence\n"
-            "  - commit list with SHA, message, and the plan step each commit satisfies\n"
-            "  - `git diff --stat <base>..HEAD` summary plus per-file one-line change summary\n"
-            "  - `Out-of-plan edits` block listing every file touched outside the approved plan with rationale (empty block preferred)\n"
-            '  - validation evidence: actual stdout/stderr and exit code for every pre / mid / post command from the plan (no paraphrased "tests pass")\n'
-            "  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n"
-            "  - per-verifier sections for every verifier in the resolved roster, with an independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by the Okstra lead\n"
-            "  - rollback verification (advisory, never blocks — record the revert path for a human; `result` is ok / not-applicable / advisory — human-run)\n"
-            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`, and `rationale` is why that one and nothing else. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
-        ),
-    },
-    "final-verification": {
-        "allowed": (
-            "  - acceptance verdict with requirement coverage assessment\n"
-            "  - residual risk and regression notes\n"
-            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`, and `rationale` ties that choice to the verdict and the blocker list. Both `release-handoff` forms require a release-ready verdict — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`); either verification scope may route there, because release-handoff opens one PR per stage. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
-        ),
-    },
-    "release-handoff": {
-        "allowed": (
-            "  - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n"
-            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n"
-            "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
-            "  - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n"
-            "  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n"
-            "  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n"
-            "  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n"
-            "  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template"
-        ),
-    },
-}
-
-PHASE_RULES_UNKNOWN = {
-    "allowed": "  - outputs defined by the active task type",
-}
-
 
 def render_forbidden(items: list[str]) -> str:
     """Render a forbidden-action list to the `  - item` bullet block injected
@@ -161,24 +41,30 @@ def render_forbidden(items: list[str]) -> str:
     return "\n".join(f"  - {item}" for item in items)
 
 
-def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
-    """Load the forbidden-actions SSOT and render each phase to its bullet block.
-
-    `workspace_root` is the resolved okstra asset root (repo or runtime); the
-    JSON lives beside the profile `.md` files at
-    `prompts/profiles/forbidden-actions.json`.
-    """
-    path = Path(workspace_root) / "prompts" / "profiles" / "forbidden-actions.json"
-    data = load_owned_object(path, artifact="forbidden actions profile")
-    if "unknown" not in data:
-        # compute_workflow_state falls back to the "unknown" entry for any
-        # unmapped task_type; without it a missing/renamed key would surface as
-        # a KeyError deep in prompt assembly instead of here at the SSOT seam.
+def load_phase_boundary(workspace_root: Path, task_type: str) -> dict[str, str]:
+    """선택한 단계의 출력 경계를 읽고 구형 자산 루트의 금지 목록도 보존한다."""
+    fallback_path = Path(workspace_root) / "prompts" / "profiles" / "forbidden-actions.json"
+    fallback = load_owned_object(fallback_path, artifact="forbidden actions profile")
+    if "unknown" not in fallback:
         raise ValueError(
-            f"forbidden-actions SSOT at {path} is missing the required "
+            f"forbidden-actions SSOT at {fallback_path} is missing the required "
             "'unknown' fallback entry"
         )
-    return {phase: render_forbidden(items) for phase, items in data.items()}
+    if task_type not in task_types():
+        return {
+            "allowed": "  - outputs defined by the active task type",
+            "forbidden": render_forbidden(fallback.get(task_type, fallback["unknown"])),
+        }
+    path = phase_boundary(workspace_root, task_type)
+    if path is None:
+        # 패키지 없는 외부 프로필 루트는 기존 코드의 출력 정책과 자체 금지 목록을 쓴다.
+        path = Path(__file__).parent / "phases" / phase_record(task_type).package_name / "boundary.json"
+        data = load_owned_object(path, artifact="phase boundary")
+        items = fallback.get(task_type, fallback["unknown"])
+    else:
+        data = load_owned_object(path, artifact="phase boundary")
+        items = data["forbidden"]
+    return {"allowed": data["allowed"], "forbidden": render_forbidden(items)}
 
 
 def phase_position(task_type: str) -> str:
@@ -203,7 +89,7 @@ def compute_workflow_state(
     current_run_status: str,
     current_task_status: str,
     render_only: bool,
-    forbidden_by_phase: dict[str, str],
+    boundary: dict[str, str],
     work_category: str = "",
 ) -> dict:
     """WORKFLOW_* + PHASE_* 값을 dict 로 돌려준다."""
@@ -234,7 +120,6 @@ def compute_workflow_state(
     else:
         checkpoint_label = "run-prepared"
 
-    rules = PHASE_RULES.get(task_type, PHASE_RULES_UNKNOWN)
     last_completed = task_type if current_run_status == "completed" else ""
 
     resolved_work_category = (work_category or "").strip() or "unknown"
@@ -256,8 +141,6 @@ def compute_workflow_state(
         "WORKFLOW_LAST_COMPLETED_PHASE": last_completed,
         "WORKFLOW_AWAITING_APPROVAL": "false",
         "WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL": checkpoint_label,
-        "PHASE_ALLOWED_OUTPUTS": rules["allowed"],
-        "PHASE_FORBIDDEN_ACTIONS": forbidden_by_phase.get(
-            task_type, forbidden_by_phase["unknown"]
-        ),
+        "PHASE_ALLOWED_OUTPUTS": boundary["allowed"],
+        "PHASE_FORBIDDEN_ACTIONS": boundary["forbidden"],
     }

package/runtime/python/okstra_ctl/write_policy.py

@@ -26,6 +26,7 @@ from .domain.write_policy import (  # noqa: F401 — 재노출(값 코어는 도
     write_policy_digest,
     write_policy_from_payload,
 )
+from .conformance import conformance_result_file
 from .final_report_paths import final_report_data_path
 from .json_boundary import JsonBoundaryError, load_owned_object
 from .path_hints import hydrate_active_run_context
@@ -65,11 +66,15 @@ def build_write_policy(
         ),
         "externalRoots": [str(path) for path in external_roots],
     }
+    artifact_policy: dict[str, Any] = {
+        "allowedRoot": str(project_root),
+        "allowedPaths": list(artifact_paths),
+    }
+    preserved_paths = _relative_paths(invocation.get("preservedPaths", ()))
+    if preserved_paths:
+        artifact_policy["preservedPaths"] = list(preserved_paths)
     policy = WritePolicy(
-        artifact_policy={
-            "allowedRoot": str(project_root),
-            "allowedPaths": list(artifact_paths),
-        },
+        artifact_policy=artifact_policy,
         source_policy=source_policy,
         git_policy=git_policy,
         auxiliary_policy=auxiliary_policy,
@@ -94,9 +99,12 @@ def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ..
     conformance script, its `tsconfig.json` and any real-IO qa spec under
     `qa/scripts/`, plus the manifest entry naming them
     (`_implementation-executor.md` §"Stage conformance script", §"Real-IO test
-    isolation"). Everything else under `qa/` — the self-mock sidecar and its
-    diff, the conformance run's `result-*.json` — is written while the verifier
-    runs its own gates. Keeping the executor's grant to those two entries is
+    isolation"), plus `qa/output/` for whatever those scripts write when the
+    executor runs them against its own work — a baseline capture, build logs
+    (§"Verifier gates are not yours to run" lets it run them). Everything else
+    under `qa/` — the self-mock sidecar and its diff, the conformance run's
+    `result-*.json` — is written while the verifier runs its own gates.
+    Keeping the executor's grant to those three entries is
     what leaves the audit able to catch an executor that runs the verifier's
     self-mock gate (`_implementation-executor.md` §"Verifier gates are not
     yours to run"); widening it to `qa/` would silence that.
@@ -114,6 +122,7 @@ def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ..
     if role == "implementer":
         return (
             task_qa_dir(task_root) / "scripts",
+            task_qa_dir(task_root) / "output",
             task_conformance_manifest_file(task_root),
         )
     if role == "verifier":
@@ -121,6 +130,42 @@ def _role_qa_artifact_paths(role: str, task_root: Path | None) -> tuple[Path, ..
     return ()
 
 
+def _inherited_qa_evidence(
+    role: str, task_type: str, task_root: Path | None,
+) -> tuple[Path, ...]:
+    """Existing qa files a final-verification verifier must leave byte-identical.
+
+    Its grant is the whole `qa/` tree, so re-running a plan step that captures a
+    baseline overwrote the implementation's RED evidence and still passed the
+    audit (observed 2026-09-26, dev-11054 `qa/baseline/base.json`). New files and
+    the conformance results it re-runs (`qa/result-<stageKey>.json`, the only qa
+    write `final_verification/boundary.json` names) stay writable.
+    """
+    if role != "verifier" or task_type != "final-verification" or task_root is None:
+        return ()
+    qa_dir = task_qa_dir(task_root)
+    if not qa_dir.is_dir():
+        return ()
+    rerun = {
+        conformance_result_file(qa_dir, key)
+        for key in _conformance_stage_keys(task_root)
+    }
+    return tuple(sorted(
+        path for path in qa_dir.rglob("*")
+        if path.is_file() and not path.is_symlink() and path not in rerun
+    ))
+
+
+def _conformance_stage_keys(task_root: Path) -> tuple[str, ...]:
+    path = task_conformance_manifest_file(task_root)
+    if not path.is_file():
+        return ()
+    entries = _read_json(path, "conformance manifest").get("entries")
+    return tuple(
+        entry["stageKey"] for entry in entries or ()
+        if isinstance(entry, dict) and isinstance(entry.get("stageKey"), str)
+    )
+
 
 def _technical_experiment_paths(
     artifact_paths: Sequence[Path], task_root: Path | None,
@@ -145,6 +190,7 @@ def _technical_experiment_paths(
 def build_invocation_write_contract(
     *,
     role: str,
+    task_type: str,
     project_root: Path,
     worktree: Path | None,
     artifact_paths: Sequence[Path],
@@ -180,6 +226,10 @@ def build_invocation_write_contract(
         "plannedPaths": list(source_paths),
         "plannedPathsDeclared": planned_paths_declared,
         "protectedPaths": [".okstra", ".git"],
+        "preservedPaths": [
+            _relative_to_root(path, root, "preserved")
+            for path in _inherited_qa_evidence(role, task_type, task_root)
+        ],
         "generatedPaths": list(generated_paths),
         "scratchRoots": [str(path) for path in scratch_roots],
         "auxiliaryRoots": [str(path) for path in auxiliary_roots],

package/runtime/python/okstra_project/dirs.py

@@ -87,6 +87,20 @@ def okstra_root(project_root: Path) -> Path:
     return Path(project_root) / OKSTRA_RELATIVE
 
 
+def ensure_okstra_gitignore(project_root: Path) -> Path:
+    """`.okstra/.gitignore` 에 `*` 를 둔다. 이미 있으면 건드리지 않는다.
+
+    전역 gitignore 로만 `.okstra` 를 빼면 그것을 읽지 않는 도구가 산출물을 훑는다.
+    Tailwind v4(4.3.2) 스캐너는 전역 설정은 무시하고 중첩 `.gitignore` 는 따른다
+    (2026-09-27 실측) — 실험 사이트 복사본을 읽어 빌드가 수십 GB 로 커졌다.
+    """
+    path = okstra_root(project_root) / ".gitignore"
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("*\n", encoding="utf-8")
+    return path
+
+
 def project_json_path(project_root: Path) -> Path:
     """`<project_root>/.okstra/project.json` 절대 path."""
     return Path(project_root) / PROJECT_JSON_RELATIVE

package/runtime/python/okstra_project/resolver.py

@@ -11,6 +11,7 @@ from typing import Optional
 from .dirs import (
     OKSTRA_DIR_NAME,
     PROJECT_JSON_RELATIVE,
+    ensure_okstra_gitignore,
     project_json_path,
 )
 
@@ -154,7 +155,7 @@ def upsert_project_json(project_root: Path, project_id: str, *,
     if not project_id:
         raise ResolverError("project_id is required for upsert_project_json")
     target = project_json_path(project_root)
-    target.parent.mkdir(parents=True, exist_ok=True)
+    ensure_okstra_gitignore(project_root)
     when = now or _now_iso()
     abs_root = str(Path(project_root).resolve())
     if target.is_file():

package/runtime/schemas/execution-manifest-v2.schema.json

@@ -137,7 +137,8 @@
           "required": ["allowedRoot", "allowedPaths"],
           "properties": {
             "allowedRoot": {"type": "string", "pattern": "^/"},
-            "allowedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "minItems": 1, "uniqueItems": true}
+            "allowedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "minItems": 1, "uniqueItems": true},
+            "preservedPaths": {"type": "array", "items": {"type": "string", "pattern": "\\S"}, "uniqueItems": true}
           },
           "additionalProperties": false
         },

package/runtime/skills/okstra-brief-gen/SKILL.md

@@ -345,7 +345,7 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 
 1. `AskUserQuestion` (free text):
    `"Scan scope — comma-separated paths inside the project (e.g. src/foo/, src/bar/baz.py)"` → `scan_scope` (CSV).
-2. `AskUserQuestion` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/improvement_lenses.py`):
+2. `AskUserQuestion` (multi-select, options = the lens values from `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py`'s `LENSES` — code source: `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`):
    `"Priority lenses (pick 1–4)"` → `priority_lenses` (1..4 values from the enum).
    Current `LENSES` values (this list mirrors the module — if they diverge, the module wins; Step 6.6 `validate-brief` enforces the subset): `performance`, `security`, `readability`, `architecture`, `test-coverage`, `dx`, `observability`, `accessibility`.
 3. `AskUserQuestion` (free text):
@@ -362,7 +362,7 @@ If the user picked `Codebase scan`, gather the codebase-scan-specific inputs:
 Validation (before Step 4 sharpening):
 
 - Confirm that each path in `scan_scope` actually exists inside `<PROJECT_ROOT>` via `ls` — if not, correct it with a single question.
-- Confirm that `priority_lenses` is a subset (1–4) of `LENSES` in `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py` — on violation, show the enum + re-select. Final enforcement is done by Step 6.6 `validate-brief` (`check_codebase_scope`).
+- Confirm that `priority_lenses` is a subset (1–4) of `LENSES` in `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py` — on violation, show the enum + re-select. Final enforcement is done by Step 6.6 `validate-brief` (`check_codebase_scope`).
 - Confirm that `candidate_cap` is an integer in 1–12.
 
 Once validation passes, jump to Step 2 (task key).
@@ -632,7 +632,7 @@ These 5 rules apply only to `scope: codebase` briefs. The budget expands from th
 
 1. **scan-scope path existence check.** Confirm each path via `ls` / `Read`. If missing, correct it with a single question (offer the nearest path candidate as `Recommended:`).
 2. **Ambiguous path narrowing.** Narrow abstract paths like `"backend"`, `"payment module"` down to one or more concrete directories. Guess codebase-first, then confirm with a single question.
-3. **priority-lenses whitelist check.** Confirm it is a subset of `LENSES` in `~/.okstra/lib/python/okstra_ctl/improvement_lenses.py`. If out-of-enum, offer the nearest in-enum value as `Recommended:`.
+3. **priority-lenses whitelist check.** Confirm it is a subset of `LENSES` in `~/.okstra/lib/python/okstra_ctl/phases/improvement_discovery/lenses.py`. If out-of-enum, offer the nearest in-enum value as `Recommended:`.
 4. **out-of-scope consistency.** Confirm each path in `out-of-scope` is a subset of `scan-scope`. If a path is unrelated, remove it with a single question or absorb it into scan-scope.
 5. **One line of lens-priority rationale.** If the brief body lacks a line on *why* each priority lens takes precedence in this scope, offer the result of a first codebase pass as `Recommended:` and ask one question.