okstra 0.34.1 → 0.36.1

package/runtime/python/okstra_ctl/workflow.py

@@ -20,6 +20,7 @@ PHASE_SEQUENCE = [
 
 DEFAULT_NEXT_PHASE = {
     "requirements-discovery": "pending-routing-decision",
+    "improvement-discovery": "pending-routing-decision",
     "error-analysis": "implementation-planning",
     "implementation-planning": "implementation",
     "implementation": "final-verification",
@@ -47,6 +48,24 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - 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": {
+        "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 / 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)"
+        ),
+        "forbidden": (
+            "  - source code edits of any kind\n"
+            "  - implementation planning, root-cause analysis, builds, migrations, or deployments\n"
+            "  - starting `implementation-planning`, `implementation`, `error-analysis`, or any other lifecycle phase inside this run\n"
+            "  - generating candidates outside the lens whitelist (Lens enum violation rejects the report)\n"
+            "  - exceeding the candidate cap (absolute cap 12)\n"
+            "  - free external data fetch beyond the brief's Source Material or Phase 1.5 resolved scope\n"
+            "  - interpreting user phrases like `다음 단계 진행해` as authorisation to enter another phase"
+        ),
+    },
     "error-analysis": {
         "allowed": (
             "  - symptom and trigger evidence\n"
@@ -69,7 +88,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - bite-sized stepwise execution order for the 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 `## 5. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)\n"
-            "  - explicit `User Approval Request` block awaiting human approval\n"
+            "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
             "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)"
         ),
         "forbidden": (
@@ -95,7 +114,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - routing recommendation for `final-verification` (ready / needs new error-analysis or planning loop)"
         ),
         "forbidden": (
-            "  - any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md with a recorded user approval marker)\n"
+            "  - 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`)\n"
             "  - `git push` of any kind, `npm publish` / `cargo publish` / `pip publish`, `gh release`, `docker push`\n"
             "  - real database migrations, schema changes against shared environments, or writes to non-local datastores\n"
             "  - production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)\n"

package/runtime/python/okstra_ctl/worktree.py

@@ -43,7 +43,14 @@ from typing import Optional
 
 from .ids import _safe_fs_segment
 from . import worktree_registry
-from .seeding import SettingsLinkError, ensure_project_settings_symlink
+from .seeding import (
+    AgentsMdLinkError,
+    ClaudeMdLinkError,
+    SettingsLinkError,
+    ensure_project_agents_md,
+    ensure_project_claude_md,
+    ensure_project_settings_symlink,
+)
 
 
 # Project-root directories that hold okstra task state, ignored by git, or
@@ -390,6 +397,48 @@ def _seed_worktree_settings_symlink(worktree_path: Path) -> None:
         )
 
 
+def _seed_worktree_claude_md(worktree_path: Path) -> None:
+    """Seed `.project-docs/okstra/CLAUDE.md` symlink + `<worktree>/CLAUDE.md`
+    import block in the worker worktree so dispatched Claude sessions auto-load
+    okstra's runtime guidance. Mirrors `_seed_worktree_settings_symlink` —
+    needed because the worktree's `CLAUDE.md` comes from the git checkout (no
+    marker block unless committed) and `.project-docs/` is only dir-symlinked,
+    not its contents.
+    """
+    try:
+        link = ensure_project_claude_md(project_root=worktree_path)
+    except ClaudeMdLinkError as exc:
+        print(
+            f"okstra-claude-md: failed to seed worker worktree CLAUDE.md at "
+            f"{worktree_path} — dispatched Claude sessions will not auto-load "
+            f"okstra guidance. ({exc})",
+            file=__import__("sys").stderr,
+        )
+        return
+    if 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,
+        )
+
+
+def _seed_worktree_agents_md(worktree_path: Path) -> None:
+    """Seed `<worktree>/AGENTS.md` symlink so codex / aider sessions dispatched
+    into this worktree auto-load okstra's guidance. Only acts when AGENTS.md
+    is absent — never overwrites user content.
+    """
+    try:
+        ensure_project_agents_md(project_root=worktree_path)
+    except AgentsMdLinkError as exc:
+        print(
+            f"okstra-agents-md: failed to seed worker worktree AGENTS.md at "
+            f"{worktree_path} — dispatched codex / aider sessions will not "
+            f"auto-load okstra guidance. ({exc})",
+            file=__import__("sys").stderr,
+        )
+
+
 def _copy_snapshot_files(source_root: Path, worktree_path: Path) -> list[str]:
     """Copy fixture files from MAIN → task worktree as read-only snapshots
     (FU-V3).
@@ -515,6 +564,8 @@ def provision_task_worktree(
     if existing is not None and existing.status == "active":
         worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
         _seed_worktree_settings_symlink(Path(existing.worktree_path))
+        _seed_worktree_claude_md(Path(existing.worktree_path))
+        _seed_worktree_agents_md(Path(existing.worktree_path))
         return WorktreeProvision(
             status="reused",
             path=existing.worktree_path,
@@ -617,6 +668,8 @@ def provision_task_worktree(
         raise
 
     _seed_worktree_settings_symlink(worktree_path)
+    _seed_worktree_claude_md(worktree_path)
+    _seed_worktree_agents_md(worktree_path)
 
     base_label = (
         f"{base_origin} @ {resolved_base_ref[:12]}"

package/runtime/python/okstra_project/resolver.py

@@ -118,9 +118,10 @@ def upsert_project_json(project_root: Path, project_id: str, *,
                 f"under a different id. "
                 f"(projectId 불일치: 한 PROJECT_ROOT 에는 하나의 projectId 만 허용됩니다.)")
         # Preserve any user-managed fields (e.g. `worktreeSyncDirs`,
-        # `mcpServers`) so manual edits to project.json are not wiped
-        # by the per-run self-registration upsert. Only the canonical
-        # identity/timestamp fields below are owned by this function.
+        # `qaCommands`, `prTemplatePath`, `reportLanguage`, `mcpServers`) so
+        # manual edits to project.json are not wiped by the per-run
+        # self-registration upsert. Only the canonical identity/timestamp
+        # fields below are owned by this function.
         result = dict(data) if isinstance(data, dict) else {}
         result["projectId"] = project_id
         result["projectRoot"] = abs_root

package/runtime/python/okstra_token_usage/report.py

@@ -15,7 +15,7 @@ if str(_HERE) not in sys.path:
     sys.path.insert(0, str(_HERE))
 
 from okstra_ctl.render_final_report import (  # noqa: E402
-    RenderError,
+    FinalReportRenderError,
     render_to_file,
 )
 
@@ -171,6 +171,6 @@ def populate_and_render(
 
     try:
         bytes_written = render_to_file(data_path, output_path)
-    except RenderError as exc:
+    except FinalReportRenderError as exc:
         raise SubstituteRefusedError(f"render after substitute failed: {exc}") from exc
     return changes, bytes_written

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

@@ -6,6 +6,7 @@
   "type": "object",
   "required": [
     "schemaVersion",
+    "meta",
     "frontmatter",
     "header",
     "verdictCard",
@@ -27,6 +28,19 @@
       "description": "Schema version. Renderer refuses to process unknown versions."
     },
 
+    "meta": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["reportLanguage"],
+      "properties": {
+        "reportLanguage": {
+          "type": "string",
+          "enum": ["en", "ko"],
+          "description": "Resolved language used for prose + i18n dictionary. 'auto' must be resolved to 'en' or 'ko' by the lead before the report-writer worker writes data.json."
+        }
+      }
+    },
+
     "frontmatter": {
       "type": "object",
       "required": [
@@ -40,7 +54,8 @@
         "taskGroup",
         "projectId",
         "taskType",
-        "workerId"
+        "workerId",
+        "approved"
       ],
       "additionalProperties": false,
       "properties": {
@@ -64,7 +79,11 @@
         "taskGroup": { "type": "string", "minLength": 1 },
         "projectId": { "type": "string", "minLength": 1 },
         "taskType": { "$ref": "#/$defs/TaskType" },
-        "workerId": { "const": "report-writer" }
+        "workerId": { "const": "report-writer" },
+        "approved": {
+          "type": "boolean",
+          "description": "사용자 승인 플래그. report-writer 는 항상 false 로 발행하고, 사용자가 `--approve` 또는 직접 편집으로 true 로 토글합니다. `implementation` task-type 의 prepare 단계가 `--approved-plan` 으로 지정된 보고서의 이 필드를 읽어 진입 여부를 결정합니다. 다른 task-type 에서는 의미 없이 false 로 유지됩니다."
+        }
       }
     },
 
@@ -94,19 +113,6 @@
       }
     },
 
-    "approvalBlock": {
-      "type": "object",
-      "description": "RENDER_IF taskType == implementation-planning. Renderer emits the User Approval Request section.",
-      "required": ["approved"],
-      "additionalProperties": false,
-      "properties": {
-        "approved": {
-          "type": "boolean",
-          "description": "When true, renders `- [x] Approved`; when false, `- [ ] Approved`. Plan Body Verification gate decides which."
-        }
-      }
-    },
-
     "clarificationCarryIn": {
       "type": "object",
       "description": "RENDER_IF non-empty. Carry-in clarifications from the previous run.",
@@ -593,7 +599,7 @@
         "required": ["header"]
       },
       "then": {
-        "required": ["implementationPlanning", "approvalBlock"]
+        "required": ["implementationPlanning"]
       }
     },
     {