okstra 0.152.0 → 0.154.0

package/README.md

@@ -184,7 +184,7 @@ Use these slash commands inside a Claude Code session:
 | `/okstra-inspect` | Unified read side. Subcommands: `status` (phase/state and workStatus updates), `history` (past tasks, reruns, resumes), `report` (find/read final reports), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory and cleanup suggestions), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), and `recap` (run-to-run before/after summary plus free-form Q&A over a task's `.okstra` artifacts) |
 | `/okstra-rollup` | Aggregate every task run in a task group or project, including per-task run counts, duration, errors, group totals, and a cross-task report digest |
 | `/okstra-usage` | Show the current project's recent run coverage, raw and billable-equivalent tokens, known USD cost, CPU time, and wall-clock time grouped by task type (default: last 30 days) |
-| `/okstra-schedule-gen` | Generate a work schedule for an entire task group. Stages are sourced from each non-done task's `implementation-planning` final-report **Stage Map**; you pick which stages to include, and the final file is written only after an independent verifier subagent confirms the draft covers exactly the selected stages |
+| `/okstra-schedule-gen` | Invoke as `/okstra-schedule-gen [task-group]` to generate a work schedule for an entire task group. Each non-done task is resolved through the source-aware `stage-map` response; your unfinished-stage choices are captured in a temporary selection contract, and only the same draft that passes deterministic selection validation followed by independent narrative verification is published |
 | `/okstra-container-build` | Deploy a verified task's code as a local Docker Compose group and monitor per-container logs (subcommands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `/okstra-manager` | Coordinate cross-project okstra tasks through manager-owned plans, assignments, one-way project sync snapshots, status, and child launch context packets |
 | `/okstra-pr-gen` | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (subcommands: `template` / `branches` / `gen`). Global skill—needs a Git repo, not a registered okstra project |

package/bin/okstra

@@ -18,6 +18,13 @@ async function main(argv) {
   const [cmd, ...rest] = args;
   const loader = COMMANDS.get(cmd);
   if (!loader) {
+    if (cmd === "schedule") {
+      process.stderr.write(
+        "unknown command: schedule\n" +
+          "Schedule generation runs in an agent host: /okstra-schedule-gen [task-group]\n",
+      );
+      return 2;
+    }
     process.stderr.write(
       `unknown command: ${cmd}\n` +
         "hint: this okstra binary may predate the skill calling it — update it " +

package/docs/cli.md

@@ -324,6 +324,10 @@ Example:
 scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
 ```
 
+### Schedule generation skill
+
+The public schedule entry point is the host skill `/okstra-schedule-gen [task-group]`; `stage-map` and `validate-schedule.py` are its backend contracts, not an additional schedule-generation shell command. For each candidate task, the skill branches on the `stage-map` `state` and `sourcePlanPath`, records the selected, completed, and full stage sets in a temporary `.selection.json`, and runs deterministic `--selection-json` validation before an independent narrative verifier. Only the same draft that passes both gates is promoted, and the temporary selection contract is removed after final validation.
+
 ### `--directive`
 
 A free-text channel for passing user intent to the lead, workers, and downstream skills. The value is embedded in a `## Directive` section at the end of `instruction-set/analysis-material.md` and in `instruction-set/analysis-packet.md`, the analysis workers' primary input. It is also backed up to `instruction-set/directive.txt`.
@@ -737,7 +741,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | One-time migration of the project artifact root from `.project-docs/okstra/` to `.okstra/`. It is a dry run by default; `--apply` performs the move with `git mv` in a Git worktree, removes an empty `.project-docs/`, and synchronizes the `<PROJECT>/CLAUDE.md` import line, `.gitignore`, the project's rows in `~/.okstra/{recent,active}.jsonl`, and `~/.okstra/worktrees/registry.json`. It exits 1 if `.okstra/` already exists or the legacy directory is absent. Scheduled for removal by the end of v0.x |
 | `okstra task-list [--project-root <path>]` | Combine `list_project_tasks` and `read_latest_task` into JSON containing the task catalog and latest task |
 | `okstra task-show <task-key> [--project-root <path>]` | Summarize workflow, phase, status, and artifacts from the Task Read-Side Snapshot |
-| `okstra stage-map <task-key> [--cwd <dir>\|--project <dir>]` | Dump the task's implementation-planning Stage Map as JSON: `{ ok, taskKey, taskRoot, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }`. `stages` is `[]` when the task has no implementation-planning Stage Map. `doneStages` is read from the implementation-planning stage consumer state (with carry recovery). This is the read-side source the `okstra-schedule-gen` skill uses to derive stage units and their dependency closure |
+| `okstra stage-map <task-key> [--cwd <dir>\|--project <dir>]` | Dump the task's implementation-planning Stage Map as JSON: `{ ok, taskKey, taskRoot, state, sourcePlanPath, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }`. `state` is `ready` for one resolved source and `missing` when no Stage Map exists; corrupt or conflicting sources return structured non-zero errors instead of silently selecting another report. `doneStages` is read from the implementation-planning stage consumer state (with carry recovery). This is the read-side source `/okstra-schedule-gen [task-group]` uses to derive selectable unfinished stages and their completed dependency closure |
 | `okstra incremental-scope <args…>` | Decide re-verify vs carry-forward scope for an `implementation-planning` clarification re-run. Thin shim into `scripts/okstra_ctl/incremental_scope.py` (deterministic pure function): it reads the dependency graph from the prior run `data.json`'s `implementationPlanning.stageMap` and returns `mode:"incremental"` only when the base-ref SHA is unchanged and the affected stages' `downstream_stage_closure` covers at most half of all stages; otherwise it signals a full re-run. Used to bound the cost of a clarification re-run |
 | `okstra incremental-carry <args…>` | Merge carried-forward plan-item verdicts into an incremental re-run. Thin shim into `scripts/okstra_ctl/incremental_carry.py`: it takes the prior run's plan-item verdicts that the current run does not re-verify and merges them into the current `data.json` tagged with `carriedForwardFromSeq`. A `schemaVersion` drift raises `CarryError` and exits non-zero to force a full fallback. Runs after `incremental-scope` returns `mode:"incremental"` |
 | `okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] [--json]` / `okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] [--cwd <dir>] [--json]` | Resolve what a code review reads and where its result file goes. Output is always JSON, so `--json` only makes that explicit. `--project-root` and `--cwd` are shared pre-dispatch arguments and apply to both modes; `--cwd` is only consulted when `--project-root` is absent. Both modes return `{ ok, projectRoot, mode, worktreePath, branch, baseCommit, headCommit, reviewPath, round }`; stage mode additionally returns `taskKey`, `taskRoot`, and `stage`. Stage mode takes the diff base from the `base_ref` recorded on that stage's worktree-registry row when it was provisioned — not from a rule re-applied at review time — and names the result `.okstra/tasks/<task-group>/<task-id>/code-reviews/stage-<NN>.md`, where a re-review of the same stage becomes `-r2`, `-r3`, … (the `round` field). Only a legacy row provisioned before `base_ref` was recorded falls back to re-deriving the base through `stage_targets`, and a failure there is reported as `stage_base_unresolved`. `worktreePath` comes back empty whenever the stage worktree is not usable as a live checkout — the registry row is no longer `active` (whole-task final-verification released it), the row never carried a path, or the recorded directory is gone — and the review then reads the `branch` ref instead. Branch mode uses `--base` when given, otherwise the merge-base with the default branch (`refs/remotes/origin/HEAD`, else `main`/`master`), and names the result `.project-docs/code-reviews/<branch>/<YYYY-MM-DD>-<NN>.md`, where `<NN>` (the `round` field) is the next sequence number for that date — the highest already on disk plus one. Read-only: it resolves paths and creates no directory and no file, so the review directory does not exist until the caller writes the report. Backend for the okstra-code-review skill |

package/docs/for-ai/skills/okstra-schedule-gen.md

@@ -3,318 +3,238 @@
 ## Source
 
 - Skill source: [`skills/okstra-schedule-gen/SKILL.md`](../../../skills/okstra-schedule-gen/SKILL.md)
-- schedule template: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
-- schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
+- Schedule template: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
+- Schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
+- Stage Map read side: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py)
+- Selection semantics: [`scripts/okstra_ctl/schedule_semantics.py`](../../../scripts/okstra_ctl/schedule_semantics.py)
+- Work-category source of truth: [`scripts/okstra_ctl/work_categories.py`](../../../scripts/okstra_ctl/work_categories.py)
 - workStatus inference reference: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
 
-## Purpose
+## Purpose and invocation
 
-`okstra-schedule-gen` gathers the non-done tasks within a task-group and produces a client-facing work-schedule Markdown. It is not a skill for starting an execution task, and it is not a single-task analysis.
+`okstra-schedule-gen` gathers non-done tasks in a task group and produces one client-facing work schedule from user-selected unfinished implementation stages.
 
-Output location:
+Public invocation:
 
 ```text
-<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
+/okstra-schedule-gen [task-group]
 ```
 
-## When to Use
+This is a host skill, not a schedule-generation shell command. Use `stage-map` and `validate-schedule.py` only as backend contracts inside the skill.
 
-Use it when:
-
-- The user requests a "schedule", "work plan", or work-schedule table for an entire task-group.
-- `.okstra/discovery/task-catalog.json` contains that task-group and it has at least one task that is not `done`.
+Output location:
 
-Do not use it when:
+```text
+<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
+```
 
-- Single-task status/analysis: `okstra-inspect status`
-- Actual phase execution: `okstra-run`
-- An already-completed task-group: do not create a file; state that all tasks are done.
+Do not use it for single-task status analysis or phase execution. Use `okstra-inspect status` and `okstra-run` for those jobs.
 
-## Preflight
+## Preflight and task-group resolution
 
-A single Bash call:
+Run one literal-token preflight call:
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-If there is no runtime or project setup, point the user to `/okstra-setup` and stop.
-
-## Resolving the task-group
+On `ok: false`, point the user to `/okstra-setup` and stop. Otherwise:
 
 1. Read `.okstra/discovery/task-catalog.json`.
-2. Lowercase the user-supplied task-group and strip characters outside `[a-z0-9]`.
-3. Apply the same transform to each catalog entry's `taskGroupPathSegment` and compare.
-4. Do not fall back to the raw `taskGroup`.
-5. Read each matched task's `task-manifest.json` directly. The catalog may be stale; the manifest is authoritative.
+2. Resolve an explicit task-group from the invocation or host request. If none is unambiguous, ask the user to choose; never guess.
+3. Lowercase the token and strip characters outside `[a-z0-9]`.
+4. Apply the same transform to each catalog `taskGroupPathSegment` and compare only those normalized values.
+5. Read each matched `task-manifest.json`; it is authoritative when the catalog is stale.
 
-On zero matches, output `That task-group could not be found.` and stop.
+On zero matches, report that the task group was not found and do not create a file.
 
-## workStatus filter
+## Candidate filter
 
-Check the workStatus in each manifest. When it is missing or empty, apply `okstra-inspect`'s `status.4` inference table.
+`workStatus` is used only to decide which tasks are candidates. When it is missing or empty, use the `okstra-inspect` `status.4` inference table.
 
-Exclude:
+- Exclude resolved `done` tasks.
+- Include every other resolved state.
+- If no task remains, report that all tasks are done and do not create a file.
 
-- explicit `done`
-- inferred `done`
+Do not render `workStatus` as the detailed task status. The per-task `Status` value is `<taskType> / <currentPhase>`.
 
-Include:
+## Source-aware Stage Map resolution
 
-- `todo`
-- `in-progress`
-- `blocked`
-- `phase-done`
-- other non-done inferred/display states
+For every candidate task, call:
 
-If 0 remain after filtering, do not create a schedule file; output `All tasks in this task-group are done. There is no schedule to generate.`
+```bash
+okstra stage-map <task-key> --json
+```
 
-## per-task data extraction
+The successful response has this boundary shape:
+
+```text
+{ ok, taskKey, taskRoot, state, sourcePlanPath,
+  stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }
+```
 
-Read from the manifest:
+Handle each result explicitly:
 
-- `taskId`, `taskGroup`, `taskKey`
-- `workCategory`
-- `workflow.currentPhase`
-- `workflow.currentPhaseState`
-- `taskType`
-- `workStatus`
-- `latestReportPath`
+- `state: ready`: use exactly `sourcePlanPath`; do not pick a report by mtime or `latestReportPath`. Select only `stages − doneStages`.
+- `state: missing`: record an empty source and empty stage sets, mark the task `[NEEDS-PLANNING]`, and emit no forward Work Breakdown, Gantt, or day total for it.
+- `ok: false` or another state: stop before drafting and report the structured `stage` and `reason`. A corrupt or conflicting source must never fall back to a guessed report.
 
-Parse from the report:
+A valid selected set is dependency-closed: every transitive prerequisite of a selected stage is either also selected or present in `doneStages`. Completed prerequisites remain evidence only and are never scheduled forward.
 
-- Title / Problem statement
-- Solution / Architecture
-- Work Breakdown
-- Verification Commands
-- Rollback strategy
-- Effort, Risk, Priority, Scope, Repos
+If a ready task has no unfinished stages, render `_Complete — no remaining stage_` and omit forward effort.
 
-If there is no report or the manifest pointer is stale, fall back:
+## Stage selection
 
-1. From `taskRootPath`, find the newest-mtime file under `runs/<taskType>/reports/final-report-*.md`.
-2. If none, also look at `runs/*/reports/final-report-*.md`.
-3. If found, parse it and put a fallback note in the schedule task block.
-4. If still nothing, mark it `[NEEDS-OKSTRA-RUN]` and use only the manifest metadata.
+Offer up to three dependency-closed cumulative bundles in topological order, plus all remaining stages. A custom set is accepted only after closing it over unfinished prerequisites; completed prerequisites are preserved separately.
 
-Mark a specific section's parse failure as `[PARSE-ERROR: <section>]` and continue.
+Skip the picker when the remaining work has only one possible bundle and use all unfinished stages. Record the final stage numbers as `selectedStages`.
 
-## client-facing audience rule
+## Temporary selection contract
 
-The schedule is a client-facing work plan. Do not surface the internal report's approval, blocking decisions, or items requiring user confirmation in the schedule.
+Write a paired draft and selection input with one timestamp:
 
-Remove from the output:
+```text
+.okstra/tasks/<task-group-segment>/schedule/.draft/<timestamp>.md
+.okstra/tasks/<task-group-segment>/schedule/.draft/<timestamp>.selection.json
+```
 
-- permission/authority confirmation steps
-- approval waiting buffer
-- stakeholder coordination
-- legal/organizational sign-off
-- `Consolidated User Decision Checklist`
-- `#### Items requiring user confirmation`
-- `Done`, `Ready?`, `Blocking Decisions` column
-- checkbox list/cell
+The selection file is a temporary verification input. It freezes the exact source, full stage map, completed stages, and user-selected forward work so both validators judge the same facts instead of re-resolving mutable task state.
+
+Schema version 1:
+
+```json
+{
+  "schemaVersion": 1,
+  "tasks": [
+    {
+      "taskKey": "demo:group:DEV-1",
+      "taskId": "DEV-1",
+      "state": "ready",
+      "sourcePlanPath": "/absolute/path/final-report-implementation-planning-001.md",
+      "selectedStages": [2, 3],
+      "doneStages": [1],
+      "stages": [
+        {
+          "stageNumber": 1,
+          "title": "Prepare port",
+          "dependsOn": [],
+          "stepCount": 2
+        },
+        {
+          "stageNumber": 2,
+          "title": "Build adapter",
+          "dependsOn": [1],
+          "stepCount": 3
+        },
+        {
+          "stageNumber": 3,
+          "title": "Wire consumer",
+          "dependsOn": [2],
+          "stepCount": 2
+        }
+      ]
+    }
+  ]
+}
+```
 
-effort and Gantt reflect engineering duration only.
+Include every candidate task. A `missing` task has an empty `sourcePlanPath`, `selectedStages`, `doneStages`, and `stages`. Convert the CLI stage-row keys to the camel-case selection boundary exactly as shown.
 
-## phase classification
+## Phase classification
 
-Default mapping:
+Only these canonical categories are valid:
 
-| workCategory | phase |
+| workCategory | Default phase |
 |---|---|
-| `bugfix` | Phase 1 when High/Med-High risk, otherwise Phase 2 |
+| `bugfix` | Phase 1 for High or Med-High risk; otherwise Phase 2 |
 | `feature` | Phase 2 |
 | `improvement` | Phase 2 |
 | `refactor` | Phase 3 |
 | `ops` | Phase 3 |
-| `docs` / `doc` | Phase 2 |
-| `unknown` or undefined | Phase 2, add a rationale note |
 
-priority override:
+Priority overrides category: P0 maps to Phase 1, P1/P2 to Phase 2, and P3 to Phase 3. An unknown or missing raw category falls back to Phase 2 with a one-line rationale naming the raw value. Do not invent another category.
 
-- `P0`: Phase 1
-- `P1`, `P2`: Phase 2
-- `P3`: Phase 3
+## Template contract
 
-When ambiguous, place it in the closest phase and write the rationale at the top of the phase section. This rationale is a current validator gap, so the document owns it.
-
-## section contract
-
-Follow the template's heading order and spelling. `validate-schedule.py` checks section order, title suffix, metadata, field labels, enum, Gantt axis, and more.
-
-top-level contract sections:
+Follow `schedule.template.md` exactly. The required top-level order is:
 
 1. `## At a Glance`
-2. `## Executive Summary` (includes the mandatory subsection `### Effort Sizing Criteria` — checked by `validate-schedule.py`)
+2. `## Executive Summary`
 3. `## Task Dependency Graph`
-4. `## Phase 1: Critical Fixes`
-5. `## Phase 2: Enhancements`
-6. `## Phase 3: Architecture`
-7. `## Execution Priority Matrix`
-8. `## Cross-Task Dependencies & Shared Concerns`
-9. `## Risk Mitigation Strategy`
-10. `## Recommended Immediate Actions`
-
-optional sections:
-
-- `## Gantt Chart`: between `Task Dependency Graph` and `Phase 1`.
-- `## Glossary`: last section. Use only when opaque codes remain in the body.
-
-Keep the heading even when a phase has no task, and write `_none_`.
-
-## top header
-
-Shape:
-
-```markdown
-# <Title> — Work Schedule
-
-> Generated: <YYYY-MM-DD HH:MM> | Project: <project-id> | Task Group: <task-group>
-> Source: okstra <mode> (<N> tasks included, <M> done excluded)
-```
-
-The validator checks the title suffix `— Work Schedule`. For `<project-id>`, prefer `task-catalog.json`'s top-level `projectId`, and if absent use the first matched manifest's `projectId`. Do not invent a value.
-
-## At a Glance
-
-This totals line must be present exactly.
-
-```markdown
-**<N> tasks total / estimated effort: <X.X> ~ <Y.Y> days (Effort sum)**
-```
-
-The Effort-to-day mapping's SSOT is the template's `### Effort Sizing Criteria` table. Build the total day range by summing the lower/upper bounds.
-
-enum values:
-
-| Field | value |
-|---|---|
-| Effort | `S`, `M`, `L`, `XL`, `XXL` |
-| Priority | `P0`, `P1`, `P2`, `P3` |
-| Risk | `Very Low`, `Low`, `Medium`, `Med-High`, `High` |
-| Phase | `1`, `2`, `3` |
-
-`Med-High` is canonical.
-
-## per-task block
+4. optional `## Gantt Chart`
+5. `## Phase 1: Critical Fixes`
+6. `## Phase 2: Enhancements`
+7. `## Phase 3: Architecture`
+8. `## Execution Priority Matrix`
+9. `## Cross-Task Dependencies & Shared Concerns`
+10. `## Risk Mitigation Strategy`
+11. `## Recommended Immediate Actions`
+12. optional final `## Glossary`
 
-Every task block has a `| Item | Detail |` table. field row order:
+Keep an empty required section and render `_none_`. Headings and field labels stay as English template literals; body prose is Korean.
 
-1. `**Category**`
-2. `**Priority**`
-3. `**Effort**`
-4. `**Status**`
-5. `**Risk**`
-6. `**Scope**`
-7. `**Repo**`
-
-Then the subsection order:
-
-1. `**Problem**:`
-2. `**Solution**:`
-3. `**Work Breakdown**:` — followed by a `| Step | File | Action | Detail |` table
-4. `**Verification Commands**:` — followed by a ` ```bash ` fenced block
-5. `**Rollback**:`
-
-For a `[NEEDS-OKSTRA-RUN]` or `[PARSE-ERROR: <section>]` task, fill only the available fields but place the marker right below the task heading.
-
-## Task Dependency Graph
-
-When there is no dependency, literal:
+Each scheduled task uses this stage-level Work Breakdown shape:
 
 ```markdown
-_none_
-```
-
-When dependencies exist, use a plain fenced block. Do not attach a language tag.
-
-````
+| Stage | Title | Steps | Depends On | Days |
+|---:|---|---:|---|---:|
+| 2 | Build adapter | 3 | 1 (done) | 2.0 ~ 3.0 |
+| 3 | Wire consumer | 2 | 2 | 1.0 ~ 2.0 |
 ```
-DEV-1 -> DEV-2, DEV-3
-DEV-2 -> DEV-4
-```
-````
-
-Use only the ASCII arrow `->`.
-
-## Gantt Chart
-
-**directive override (highest priority):** before applying the heuristic below, first check the directive source's `## Directive` section. Resolution order (first hit): (1) the `--directive-file <abs-path>` argument, (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`, (3) if none, the heuristic as-is (normal path — no warning·stop). When the directive instructs Gantt render/skip, it overrides the heuristic·skip rules, and leave one line in that section: `> _Per Directive directive: <verbatim short excerpt>._`. When the directive supplies day allocation·phase weight·sub-task decomposition, reflect it verbatim in bar length.
 
-By default, render. If there is any day signal, produce a chart even as a rough estimate.
+Use the template's Effort Sizing Criteria values without redefining them. Allocate a task's range across selected stages in `stepCount` proportion: round every stage except the last to 0.5 day and let the last absorb the remainder. The stage ranges must sum to the task range, and finite task ranges must sum to the displayed total. XXL, missing, and complete tasks contribute no forward total.
 
-Render-condition examples:
+An unrepresentable half-day allocation is a validation error. Do not substitute a fallback allocation algorithm; revise the task sizing or selected-stage scope.
 
-- 2+ tasks have effort sizing.
-- Even 1 task has an effort range.
-- The source report has Part/Phase/Step decomposition.
-- Total effort is 3 days or more.
-
-Skip only when every task is XXL with no decomposition, or when all tasks lack both effort and decomposition. On skip, place the following blockquote at the `Gantt Chart` position.
-
-```markdown
-> _Gantt Chart skipped: <concrete reason referencing the actual data>._
-```
+## Gantt contract
 
-The Gantt is plain fenced ASCII. Do not use Mermaid, PlantUML, Graphviz, or a date axis.
+Render a plain fenced relative-day Gantt when the selected stages have finite day ranges. Every forward row is identified by stage and repeats its Work Breakdown range:
 
-````
-```
-Day:            1    5    10   15   20
-                |    |    |    |    |
-Phase 1
-  DEV-1 (M)          ██████          ! crit
-Phase 2
-  DEV-2 (L)                ██████░░  est
+```text
+DEV-1/S2  ████      days=2.0~3.0
+DEV-1/S3      ████  days=1.0~2.0
 ```
-````
 
-The axis uses relative day count only. Do not put in a calendar date, weekday, or "today + N".
+The identifier format is `<TASK-ID>/S<stage-number>` and the annotation is `days=<lower>~<upper>`. Do not emit a row for a completed, unselected, missing, or unknown stage. Bar length is illustrative; `days=` is the validated duration contract.
 
-## handling opaque code
+Skip the chart only when no forward task has a finite day signal, and state the concrete reason. Do not use calendar dates, Mermaid, PlantUML, Graphviz, or another graph language.
 
-Do not surface internal report codes (`FC-5`, `UC-3`, `M2`, etc.) as-is.
+A host-supplied directive or the first `## Directive` in the configured analysis material may override the render/skip heuristic, but it cannot override stage selection, dependency closure, or validated day arithmetic.
 
-Option A: inline replacement with a short description.
+## Client-facing boundary
 
-Option B: when many codes recur, resolve every code in a final `## Glossary`. The glossary table header is exactly `| Code | Description |` (English literal — checked by the validator). Milestone codes (`M1`, `M2` …) also fail the validator when left unresolved in the glossary, just like `FC-N`.
+Assume the team has the required authority. Exclude approval waits, permission checks, stakeholder coordination, decision checklists, and internal blocker codes from forward engineering work. Gantt duration and totals represent engineering work only.
 
-Do not put decision-item letter codes (`A1`, `B2`, `C3`, `D4`) in the schedule.
+Resolve opaque source-report codes inline or in the optional final Glossary. Decision-item codes do not belong in the schedule.
 
-## validation
+## Two validation gates
 
-After writing, re-read it and run the validator before the completion message.
+Run both gates against the same draft and temporary selection contract.
 
-```bash
-python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
-```
+1. Deterministic gate:
 
-If the installed validator is absent, use the repo validator.
+   ```bash
+   python3 ~/.okstra/lib/validators/validate-schedule.py <draft> --selection-json <selection>
+   ```
 
-```bash
-python3 validators/validate-schedule.py <output-path>
-```
+2. Only after that command passes, dispatch an independent LLM verifier with the draft and selection JSON, but not the lead's reasoning. It checks narrative coherence, phase rationale, executable order, engineering-only scope, and contradictions with the structured rows.
 
-On failure, fix the file and re-validate. Fall back to a manual checklist only when there is no validator.
+If either gate finds a defect, revise the same draft in place and restart from the deterministic gate. Allow at most two revision rounds across both gates. Never publish a draft that has not passed both gates in that order.
 
-## completion message
+After both gates pass:
 
-```text
-Schedule generated: <relative-path>
-- Included tasks: N
-- Excluded (done) tasks: M
-- Estimated effort: X.X ~ Y.Y days (Effort sum)
-- Mode: lightweight
-```
+1. Move the same draft content to the collision-safe final path; do not re-render it.
+2. Re-read it and run the installed format validator on the final path, falling back to the repository validator only when needed.
+3. Delete the temporary selection file only after final validation passes.
+4. Report completion in Korean with the output path, included/excluded counts, finite total range, and lead-plus-verifier mode.
 
 ## Forbidden patterns
 
-- Translating a heading into Korean/French/etc.
-- Adding `## Cumulative Timeline`.
-- Adding an extra top-level section such as `## Effort-to-Day mapping`.
-- Rendering the Gantt as mermaid.
-- Putting a calendar date on the Gantt axis.
-- Creating a checkbox, Done, Ready, or Blocking Decisions column.
-- Surfacing internal approval/blocker/user-decision items in the client schedule.
-- Excluding a task because it has no report. Include it as `[NEEDS-OKSTRA-RUN]`.
-- Overwriting an existing file on a timestamp collision. Append a `-2`, `-3` suffix.
+- Guessing a planning report after `stage-map` reports a structured error.
+- Treating `workStatus` as the detailed schedule status.
+- Scheduling completed or non-selected stages.
+- Publishing a task-level Gantt row without the `/S<stage-number>` suffix and `days=` range.
+- Dispatching narrative validation before deterministic `--selection-json` validation.
+- Re-rendering after validation instead of promoting the same draft.
+- Deleting the selection contract before final validation.
+- Publishing after more than two unsuccessful revision rounds.

package/docs/project-structure-overview.md

@@ -243,7 +243,7 @@ Important modules:
 | `build_tools.py` | allowlist SSOT for deciding whether a plan's command cell invokes the project build toolchain (`npm`/`pytest`/`cargo`/`gradle`/… behind transparent leaders like `sudo`/`env`). The planning worktree has no dependencies installed, so `validators/validate-run.py` uses this to warn (advisory) when a toolchain stage declares no install precondition. Intentionally an allowlist, not a denylist, so unknown tokens go undetected rather than firing on `grep`/`sed` in every plan |
 | `stage_citations.py` | shared grammar SSOT for reading the Stage Map stage numbers a prose cell cites (`Stages 1, 2, and 3`, ranges, etc.). One definition serves two readers that must not drift — the coverage check in `validators/validate-run.py` proving every stage traces to a requirement, and `incremental_scope.py`'s back-trace resolving which stages an answered clarification touches |
 | `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and the waiver-matching mechanics both gates share — `selfmock_path_key` (the one path-normalization), `waiver_entry_key` (the `(file, line, <discriminator>)` triple, with the hand-typed line coerced to `int`) and `partition_waived_entries` (the split into still-failing vs waived). Gate A passes the discriminator `signal`, gate B `mutant`; one definition means the two cannot disagree about whether a waiver matches a finding. The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). The static detector `validators/detect_self_mock.py`, the drift guard and `mutation_probe.py` MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate (`mutation_probe.py`) |
-| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
+| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `python` → Cosmic Ray, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). The Python adapter activates only when the worktree has both an installed `cosmic-ray` executable and `cosmic-ray.toml`; Okstra never installs it. It verifies that `module-path` covers every changed Python target and that no target is excluded, snapshots the configured Python source bytes and modes, restores them after every run, and filters the JSONL dump to diff-added lines. A completed session with no applicable operator on a changed line is `nothing-to-verify`; malformed configuration, command/report failures, incomplete trials, and failed source restoration are blocking `integrity-inspection` results. `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `path_hints.py` | Compact path-hint persistence + legacy context hydration — stores `run-context` / `active-run-context` in the schemaVersion `2.0` `identity` + `pathHints` compact schema, and hydrates the legacy flat path keys (`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH`, etc.) in memory the moment the host-side reader reads them |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
@@ -386,7 +386,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 | `validate-schedule.py` | Schedule section/order/code validation |
 | `validate-implementation-plan-stages.py` | enforces the Stage Map structure — checks the S1–S8 rules (`## 5.5 Stage Map` + `## 5.5.<i> Stage <i>` sections, ≤ 8 steps per stage, etc.) |
 | `validate_improvement_report.py` | enforces the 11-item contract of the improvement-discovery final-report. Automatically invoked by `validate-run.py` when `task_type == "improvement-discovery"` |
-| `detect_self_mock.py` | self-mock detector — runs BOTH gates and writes the run's sidecar. Gate A (static) scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Gate B (mutation) runs in the same call: `--changed-file` takes the stage's WHOLE changed set (each adapter selects its own production sources out of it), `--diff` and `--worktree` scope it, and `scripts/okstra_ctl/mutation_probe.py` writes the result into the sidecar's `mutation` block; the received set is recorded as `changedFiles` so the gate can prove gate B was not handed an empty input. `overall` and the exit code follow BOTH gates — a mutation FAIL with a clean static scan still exits 1. The same `--waivers` file feeds both (gate A reads its `signal` entries, gate B its `mutant` ones). Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
+| `detect_self_mock.py` | self-mock detector — runs BOTH gates and writes the run's sidecar. Gate A (static) scans the changed TEST files for SUT-stub signals (patterns imported from the SSOT `scripts/okstra_ctl/self_mock_signals.py`, never redefined here), matching each file as one whole-file string so multi-line signals are caught. Python strings and comments are token-masked without changing line positions before those regexes run, so examples in docstrings and comments do not become findings while executable `patch.object(self, ...)` and `sut._private` accesses remain detectable. Writes a `qa/self-mock[-stage-<N>].json` sidecar and prints `QA-RESULT: PASS|FAIL` as its last line (exit 0 = no hits, exit 1 = at least one hit). The sidecar records `scannedFiles`/`skippedFiles` so the gate can prove every changed test file was actually scanned (a run that skips them cannot pass on empty input). An optional `--waivers <path>` moves hits matching `(file,line,signal)` from `staticDetect.hits` to `staticDetect.waived` (each carrying the user's `reason`/`acknowledgedBy`) and records the file as `waiverSource`. Gate B (mutation) runs in the same call: `--changed-file` takes the stage's WHOLE changed set (each adapter selects its own production sources out of it), `--diff` and `--worktree` scope it, and `scripts/okstra_ctl/mutation_probe.py` writes the result into the sidecar's `mutation` block; the received set is recorded as `changedFiles` so the gate can prove gate B was not handed an empty input. `overall` and the exit code follow BOTH gates — a mutation FAIL with a clean static scan still exits 1. The same `--waivers` file feeds both (gate A reads its `signal` entries, gate B its `mutant` ones). Its verdict feeds the fail-closed `_validate_selfmock` gate in `validate-run.py` (implementation / final-verification): a diff that touches test files with no readable PASS sidecar blocks the run; a `waived` entry missing `reason`/`acknowledgedBy`, or a `waiverSource` that is not the task's own `qa/self-mock-waivers.json`, also blocks |
 | `validate-workflow.sh` | End-to-end fixture workflow validation |
 | `lib/*.sh` | Shared shell validator helpers and fixtures |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.152.0",
+  "version": "0.154.0",
   "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.152.0",
-  "builtAt": "2026-08-05T09:28:14.647Z",
+  "package": "0.154.0",
+  "builtAt": "2026-08-05T16:08:35.394Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-antigravity-exec.sh

@@ -245,11 +245,15 @@ fi
 # non-interactive dispatch from blocking on tool-permission prompts (the worker
 # is sandboxed to the supplied `--add-dir` workspace).
 #
-# stdout: tee'd to both the live log (for `tail -f`) AND the wrapper's own
-#         stdout (so the subagent's `BashOutput` still captures the final
-#         text verbatim for Phase 5 synthesis). Implemented via process
-#         substitution so agy itself stays a single addressable PID we
-#         can SIGTERM from the watchdog.
+# stdout: agy runs in `stream-json` so the live log records the tool calls it
+#         made — in the default `text` format agy prints only its closing
+#         summary, leaving ~2KB of self-report where codex leaves ~487KB of
+#         trace, and no way to check from outside whether the worker opened the
+#         evidence it was asked to verify. `okstra-wrapper-agy-stream.py`
+#         appends every event to the log and forwards ONLY the final response
+#         text to the wrapper's own stdout, so what the subagent's `BashOutput`
+#         captures for Phase 5 synthesis is unchanged by the format switch.
+#         agy stays a single addressable PID we can SIGTERM from the watchdog.
 # stderr: appended to the live log only — keeps the wrapper's stderr clean.
 # exit:   agy's own exit code is preserved by `wait`.
 # stdout mirror via a named FIFO instead of a `> >(tee …)` process substitution:
@@ -261,7 +265,7 @@ fi
 stdout_fifo="${log_path}.stdout.fifo"
 rm -f "$stdout_fifo"
 mkfifo "$stdout_fifo"
-tee -a "$log_path" < "$stdout_fifo" &
+python3 "$script_dir/okstra-wrapper-agy-stream.py" "$log_path" < "$stdout_fifo" &
 stdout_tee_pid=$!
 
 # Disable git's fsmonitor for every git command agy runs in this process tree —
@@ -275,6 +279,7 @@ export "GIT_CONFIG_VALUE_${_gc_idx}=false"
 export GIT_CONFIG_COUNT="$(( _gc_idx + 1 ))"
 
 agy --print "$(cat "$prompt_path")" --model "$model" "${add_dir_args[@]}" \
+  --output-format stream-json \
   --print-timeout "$PRINT_TIMEOUT" --dangerously-skip-permissions \
   2>> "$log_path" \
   > "$stdout_fifo" &