okstra 0.152.0 → 0.153.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.152.0",
+  "version": "0.153.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.153.0",
+  "builtAt": "2026-08-05T13:40:55.050Z",
   "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" &