okstra 0.201.1 → 0.201.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.201.1",
+  "version": "0.201.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.201.1",
-  "builtAt": "2026-09-13T23:39:01.225Z",
+  "package": "0.201.2",
+  "builtAt": "2026-09-13T23:51:12.747Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -173,7 +173,7 @@ roles:
       **Pick the cases by distinct outcome, not by line coverage.** When the stage writes or reconciles state, its meaningfully different outcomes are usually more than three — normal success, target already in the desired state (resume), existing data reused rather than created, a conflicting concurrent state, target absent, and mid-way failure with rollback. Enumerate the ones this stage actually implements and route them across the three lines (the `boundary` line is where resume / already-done / reuse belongs; `failure` carries conflict, absence, and rollback), naming each in the cell rather than collapsing them into "edge input". An implemented outcome with no declared case is a coverage gap the executor will not backfill.
   - **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
     - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
-    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the same paths as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary.** `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
+    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
     - **The `command` cell runs inside an okstra task worktree, not a bare checkout (BLOCKING).** okstra provisions `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and — for `implementation` — a nested `stage-<N>/` worktree into the tree the step executes in. Two consequences bind every command you write:
       - **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step. Stage completion records the commit in the consumer ledger without creating or moving git tags.
       - **Never read an `.okstra/` artifact back out of a git object.** `.okstra/**` is gitignored and never committed — the executor aborts a commit that stages an ignored path and the verifier reports a committed `.okstra` path as a branch defect — so `git cat-file -e <tag>:.okstra/…`, `git show <tag>:.okstra/…`, and every variant of that read can never resolve, at any tag, in any stage. A later stage that needs a QA artifact reads it from the working tree or receives it through the carry sidecar / verifier result; do not design a stage contract around one being reachable from a tag. Validator S12 rejects the read.

package/runtime/python/okstra_ctl/report_assembly.py

@@ -41,6 +41,7 @@ from .report_projections import (
 )
 from .scope_provenance import parse_source
 from .verification_target import read_verification_target
+from .write_policy import planned_path_declaration_errors
 
 
 @dataclass(frozen=True)
@@ -594,6 +595,7 @@ def validate_plan_draft(
         *task_narrative_errors(
             draft, load_schema_version("3.0"), str(manifest.get("taskType", "")),
         ),
+        *planned_path_declaration_errors(draft),
         *[
             f"implementationPlanning: {error}"
             for error in selected_direction_plan_errors(draft, project_root, manifest)
@@ -880,6 +882,12 @@ def assemble_report(
         raise ReportAssemblyError(tuple(input_issues))
     data = _compose(project_root, manifest_path, manifest, inputs, schema)
     errors = validate(data, schema)
+    path_errors = planned_path_declaration_errors(data)
+    if path_errors:
+        raise ReportAssemblyError(tuple(
+            AssemblyIssue("report-writer", str(inputs["narrative"].path), error.split(":", 1)[0], error)
+            for error in path_errors
+        ))
     direction_errors = selected_direction_plan_errors(
         data, project_root, manifest
     )

package/runtime/python/okstra_ctl/write_policy.py

@@ -447,7 +447,7 @@ def _relative_to_root(path: Path, root: Path, label: str) -> str:
     except ValueError as exc:
         raise WritePolicyError(f"{label} path is outside project root") from exc
     if not relative or relative == ".":
-        raise WritePolicyError(f"{label} path must name a file")
+        raise WritePolicyError(f"{label} path must name a file or scoped subdirectory, not root: {path}")
     current = root
     for part in PurePosixPath(relative).parts:
         current /= part
@@ -466,6 +466,9 @@ def _planned_paths_from_report(
     # 그 파일은 없으므로 implementer 디스패치가 전부 막혔다. 정본 헬퍼는 이미
     # 레코드인 경로를 그대로 돌려주고 `.md` 만 짝으로 바꾼다.
     payload = _read_json(final_report_data_path(report_path), "approved plan data")
+    errors = planned_path_declaration_errors(payload)
+    if errors:
+        raise WritePolicyError(f"{report_path}: {'; '.join(errors)}")
     planning = payload.get("implementationPlanning")
     stages = planning.get("stages") if isinstance(planning, Mapping) else None
     selected = next(
@@ -489,7 +492,10 @@ def _planned_paths_from_report(
         for path in (step.get("plannedPaths") or [])
         if isinstance(path, str) and path.strip()
     }
-    if paths:
+    if paths or (rows and all(
+        isinstance(step, Mapping) and isinstance(step.get("plannedPaths"), list)
+        for step in rows
+    )):
         # 경로 분류는 산출물 권한과 배정 작업 디렉터리를 함께 아는 정책 생성기가 맡는다.
         return tuple(sorted(paths)), True
     # A plan approved before `plannedPaths` existed carries its paths only in
@@ -516,6 +522,32 @@ def _planned_paths_from_report(
     return (), False
 
 
+def planned_path_declaration_errors(data: Mapping[str, Any]) -> list[str]:
+    """검사 단계의 빈 선언은 보존하고 저장소 전체를 쓰기 대상으로 승인하지 않는다."""
+    planning = data.get("implementationPlanning")
+    stages = planning.get("stages") if isinstance(planning, Mapping) else None
+    errors: list[str] = []
+    for si, stage in enumerate(stages if isinstance(stages, list) else []):
+        steps = stage.get("stepwiseExecution") if isinstance(stage, Mapping) else None
+        for ti, step in enumerate(steps if isinstance(steps, list) else []):
+            paths = step.get("plannedPaths") if isinstance(step, Mapping) else None
+            for pi, value in enumerate(paths if isinstance(paths, list) else []):
+                if not isinstance(value, str):
+                    continue
+                path = Path(value.strip().strip("`"))
+                # 절대 경로는 디스패치와 같은 실제 작업트리를 가리킨다. 새 파일은 없어도 된다.
+                root = path == Path(".") or path == Path(path.anchor or ".")
+                if path.is_absolute():
+                    root = root or (path / ".git").exists()
+                if root:
+                    field = f"implementationPlanning.stages[{si}].stepwiseExecution[{ti}].plannedPaths[{pi}]"
+                    errors.append(
+                        f"{field}: planned path must name a file or a scoped subdirectory, "
+                        f"not a repository/worktree root: {value!r}; use [] for a read-only step"
+                    )
+    return errors
+
+
 def _rooted(project_root: Path, value: str) -> Path:
     path = Path(value)
     return path if path.is_absolute() else project_root / path

package/runtime/schemas/final-report-v2.0.schema.json

@@ -8943,9 +8943,9 @@
           "minLength": 1
         },
         "plannedPaths": {
-          "description": "Paths this step may write, one per entry. Source paths are relative to the assigned worktree; absolute paths under that worktree or the project checkout identify the same repository-relative source. `.okstra` artifact paths are anchored at the original project root and may be absolute. The write-policy builder checks artifact paths against the worker's existing artifact permissions and keeps them out of the source ledger. Keep absolute artifact paths in executable commands. `files` is human-readable prose, not a path ledger.",
+          "description": "Paths this step may write, one per entry. Use an empty array for read-only steps. Never name the repository or worktree root; scoped subdirectories remain allowed. Source paths are relative to the assigned worktree; absolute paths under that worktree or the project checkout identify the same repository-relative source. `.okstra` artifact paths are anchored at the original project root and may be absolute. The write-policy builder checks artifact paths against the worker's existing artifact permissions and keeps them out of the source ledger. Keep absolute artifact paths in executable commands. `files` is human-readable prose, not a path ledger.",
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "items": {
             "type": "string",
             "minLength": 1

package/runtime/schemas/final-report-v3.0.schema.json

@@ -9088,9 +9088,9 @@
           "minLength": 1
         },
         "plannedPaths": {
-          "description": "Paths this step may write, one per entry. Source paths are relative to the assigned worktree; absolute paths under that worktree or the project checkout identify the same repository-relative source. `.okstra` artifact paths are anchored at the original project root and may be absolute. The write-policy builder checks artifact paths against the worker's existing artifact permissions and keeps them out of the source ledger. Keep absolute artifact paths in executable commands. `files` is human-readable prose, not a path ledger.",
+          "description": "Paths this step may write, one per entry. Use an empty array for read-only steps. Never name the repository or worktree root; scoped subdirectories remain allowed. Source paths are relative to the assigned worktree; absolute paths under that worktree or the project checkout identify the same repository-relative source. `.okstra` artifact paths are anchored at the original project root and may be absolute. The write-policy builder checks artifact paths against the worker's existing artifact permissions and keeps them out of the source ledger. Keep absolute artifact paths in executable commands. `files` is human-readable prose, not a path ledger.",
           "type": "array",
-          "minItems": 1,
+          "minItems": 0,
           "items": {
             "type": "string",
             "minLength": 1

package/runtime/validators/validate-implementation-plan-stages.py

@@ -21,6 +21,7 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
+from okstra_ctl.write_policy import planned_path_declaration_errors  # noqa: E402
 from okstra_ctl.tdd_bypass import (  # noqa: E402
     REASON_TOKEN as TDD_USER_BYPASS_TOKEN,
     bypass_file,
@@ -688,6 +689,10 @@ def collect_data_validation_errors(
 
     raw_stage_map = planning.get("stageMap") or []
     stage_map, errors = _data_stage_metas(raw_stage_map)
+    errors.extend(
+        ValidationError("S10", 0, error)
+        for error in planned_path_declaration_errors({"implementationPlanning": planning})
+    )
     stages = [s for s in (planning.get("stages") or []) if isinstance(s, dict)]
     if not stage_map and not stages:
         return errors