okstra 0.202.0 → 0.205.0

package/docs/for-ai/skills/okstra-run.md

@@ -1,250 +0,0 @@
-# okstra-run AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-run/SKILL.md`](../../../skills/okstra-run/SKILL.md)
-- wizard CLI wrapper: [`src/commands/execute/wizard.mjs`](../../../src/commands/execute/wizard.mjs)
-- wizard state machine: [`scripts/okstra_ctl/wizard/`](../../../scripts/okstra_ctl/wizard/)
-- render-bundle CLI: [`src/commands/execute/render-bundle.mjs`](../../../src/commands/execute/render-bundle.mjs)
-- prepare entrypoint: [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py)
-
-## Purpose
-
-`okstra-run` starts an okstra task run inside the current supported agent host. Input collection is owned entirely by the `okstra wizard` state machine; the skill relays the wizard prompts to the user and then prepares the task bundle via `okstra render-bundle`. Once the bundle is ready, the current Claude Code, Codex, or Antigravity session takes over as the host-native Okstra lead.
-
-Single authority:
-
-- Question order: `scripts/okstra_ctl/wizard/registry.py` (`STEPS`); branching: `engine.py`; per-step validation: `steps_*.py`
-- task bundle materialization: `prepare_task_bundle()`
-- Skill document: thin prompt-relay loop
-
-## When to Use
-
-Use it when:
-
-- The user wants to start an okstra task in the current session.
-- The user wants to continue the next phase of an existing task.
-- "okstra run", "okstra start", "start okstra in this session", "run the next phase", etc.
-
-Do not use it when:
-
-- The user only wants status: `okstra-inspect status`
-- The user wants past runs or a resume command: `okstra-inspect history`
-- The user explicitly named a new terminal / new claude process: point them to inspect history/resume
-
-## Preflight
-
-Resolve `<host-runtime>` from the executing harness: Claude Code → `claude-code`, Codex → `codex`, Antigravity CLI → `antigravity`, and another adapter host → `external`. This is a host capability, not a `PATH` inference or worker-provider choice. The lead provider is derived from this value and cannot be selected independently. Then make one Bash call:
-
-```bash
-okstra preflight --runtime <host-runtime>
-```
-
-On `Okstra preflight: failed`, show `Reason`, `Recovery`, `Runtime readiness`,
-and every repeated `Readiness check` line, then stop. On
-`Okstra preflight: ready`, require `Runtime readiness: ready`, carry the fixed
-`Project root` line, and read the `Relay contract` path. Do not create an
-`export PYTHONPATH`.
-
-## Bash invocation rule
-
-Every okstra call begins with the literal token `okstra`. Read the `--state-file`, `--answer`, path, model, and worker values from the prior JSON/tool output and paste them as literal strings.
-
-Avoid:
-
-- `$STATE_FILE`, `$ANSWER`
-- `$(...)`
-- `VAR=... okstra ...`
-- `eval`, `export`
-- `okstra ... && okstra ...`
-
-Do not drop the flag even for an empty answer.
-
-```bash
-okstra wizard step --state-file /tmp/okstra-wizard/state.json --answer ""
-```
-
-## wizard initialization
-
-Create the state file:
-
-```bash
-okstra wizard new-state-file
-```
-
-Carry the printed absolute path verbatim.
-
-wizard init:
-
-```bash
-okstra wizard init --state-file /tmp/okstra-wizard/state.json --project-root /abs/project --project-id project-id --host-runtime <host-runtime>
-```
-
-The result is `{ok, next}` JSON. The first step is `task_pick`.
-
-## Interpreting the wizard JSON
-
-Pick the UI according to `next.kind`.
-
-| kind | Handling |
-|---|---|
-| `pick`, `multi: false` | Render every `options[]` verbatim as a selectable choice. Submit the chosen option's `value` |
-| `pick`, `multi: true` | Submit all chosen values as a comma-separated string. An empty selection still submits `--answer ""` |
-| `pick_group` | Render the wizard's `questions[]` as a single multi-question UI. Build a JSON object of per-step values and submit it in one shot |
-| `text` | Show a plain text label without a picker, then submit the user's next message verbatim |
-| `done` | Input collection finished. Move to render-args |
-| `aborted` | Delete the state file and stop. Do not call render-args/render-bundle |
-
-`progress.label` is a string the wizard composed. Append it verbatim after the UI prompt; do not compute it yourself.
-
-## wizard loop
-
-1. Render the prompt.
-2. Submit the user's answer as a literal `--answer`.
-3. `ok: true`: show `result.echo` to the user on one line and advance to the next step.
-4. `ok: false`: show `result.error` verbatim and retry the same step via `result.current`.
-5. `current: null`: a terminal error where the prompt cannot be reconstructed. Show the error and stop.
-
-Important: never trim, hide, or restructure the wizard-provided options into a "recommended + Enter directly" form. The wizard's `options[]` is the complete choice set.
-
-## brief candidate ordering
-
-The brief selection is handled by the wizard. A new task is asked for its brief right after task-group and **before** the task-type; an existing task is asked only on an entry phase (`requirements-discovery`, `error-analysis`, `improvement-discovery`, `project-analysis`, `feature-analysis`, `change-impact-analysis`).
-
-- task-group candidates are shown newest-first by combining recent task-catalog use with the recent brief creation/modification times under `.okstra/briefs/<group>/`.
-- brief file candidates are chosen from within the selected group's `.okstra/briefs/<task-group>/**/*.md`.
-- The brief-file sort key is `max(file created/modified time, task-catalog updatedAt of the task that used this brief)`.
-- direct input is always last.
-- for a new task the following task-type pick offers entry phases only, and its recommended slot is the selected brief's `Recommended next phase:` line (fallback `requirements-discovery`).
-
-## confirm step
-
-When `next.step == "confirm"`, first fetch the confirmation summary.
-
-```bash
-okstra wizard confirmation --state-file /tmp/okstra-wizard/state.json
-```
-
-Show `text` to the user, then render the Proceed/Edit/Abort picker as the final output of that turn — the rendered question is the last thing you emit in that turn, and text emitted after the call renders below the picker. `Edit` rewinds the wizard to an earlier step.
-
-## outcome and render-bundle
-
-When `next.kind == "done"`:
-
-```bash
-okstra wizard outcome --state-file /tmp/okstra-wizard/state.json
-```
-
-Run `outcome.persistActions[]` first, then pass each key of the `outcome.renderArgs` object exactly once as an `okstra render-bundle` flag. Pass empty string values explicitly too, and add `--lead-runtime <host-runtime>` from preflight. Do not enumerate provider-specific keys in this manual; the wizard and provider registry own the emitted arguments. Exception: the `chain-stages` key is not a render-bundle flag — it drives the Step 7 unattended-chaining loop, so do not pass it as a flag (`run.py` accepts only `--stage`/`--stages`).
-
-```bash
-okstra render-bundle \
-  --lead-runtime <host-runtime> \
-  --<first-renderArgs-key> "<first-renderArgs-value>" \
-  --<each-remaining-renderArgs-key> "<corresponding-value>"
-```
-
-Parse the following labeled lines from stdout.
-
-- `okstra task root:`
-- `okstra instruction-set:`
-- optionally `okstra concurrent-run stages:`
-
-render-bundle calls `prepare_task_bundle()` in render-only mode to prepare the manifests, run context, instruction set, and discovery files, and registers the run as `prepared` in `~/.okstra/recent.jsonl`.
-
-## conformance waiver
-
-Classify the entry before offering a waiver. If `requires` contains `db`,
-`http`, or `external`, do not offer a waiver: Okstra still attempts the command,
-but any non-PASS or unavailable outcome is an external advisory with a
-user-owned rerun method. If `requires=[]`, fail closed as a declaration or
-contract defect and do not offer a waiver. Offer the waiver only when
-`requires=[io]` and that blocking local conformance command is genuinely
-impossible to run in the environment. A waiver requires user approval and a
-verbatim reason. Neither the AI lead nor a worker creates a self-exemption.
-The resulting blocking/advisory policy is enforced by
-`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
-`validators/validate-run.py::_validate_conformance`; the picker restriction is
-defined by `prompts/host-orchestration/implementation.md` Step 5.1 (the
-`okstra-run` skill body carries a generated copy).
-
-When chosen, add it to `render-bundle` only.
-
-```bash
---qa-waiver "<stageKey>:<reason>"
-```
-
-Omit the flag entirely when there is no value.
-
-## concurrent-run branch
-
-If `render-bundle` stdout carries `okstra concurrent-run stages:`, the no-team background gate is already reflected in the prompt.
-
-Give the user three options.
-
-1. Proceed as no-team background.
-2. Wait — hold the dispatch, preserve the stage worktree·run context. After the occupying run finishes, print the resume command (`okstra-inspect` history → resume) so the user can resume the same stage.
-3. Enter directly.
-
-This picker is authored by the skill, so it is separate from the wizard-option-abbreviation ban.
-
-## stale git SHA recovery
-
-When a `PrepareError` such as `Recorded stage SHAs no longer match the git history` appears, do not fix the registry/consumers by hand.
-
-1. Run the `okstra git-reconcile ... --check --text` printed in the error message verbatim.
-2. For each confirm item, ask the user for the current branch tip, a different ref, or abort.
-3. Run `okstra git-reconcile ... --apply --stage <N> --use-ref <ref>` with the chosen ref.
-4. Retry the failed render-bundle with the same arguments.
-
-If the anchor is unresolvable, run `--reset-anchor <ref>` after user confirmation.
-
-## PR template persistence
-
-In release-handoff, when `outcome.persistActions[]` returns a `config.set` / `pr-template-path` action, save the config before render-bundle.
-
-```bash
-# action.scope == "project"
-okstra config set pr-template-path "<path>" --scope project
-# action.scope == "global"
-okstra config set pr-template-path "<path>" --scope global
-```
-
-Read the scope and path from the persist action of `okstra wizard outcome`, not from the wizard state file. Do not read the raw state file directly.
-
-## Okstra lead takeover
-
-After render-bundle, read the run manifest's `resources.leadExecutionPromptPath` (project-relative, under `runs/<task-type>/prompts/`), read that file verbatim, and proceed from Phase 1 in that prompt's order. Before any in-run approval or clarification question, follow the lead contract "User confirmation before an approval blocker": read cited plan items, worker findings, and files, then ask in the user's language with each option's outcome.
-
-Inform the user on one line.
-
-```text
-Took over as Okstra lead (`<host-runtime>`) for `<taskKey>` (`<task-type>`). Run dir: `<RUN_DIR_RELATIVE_PATH>`. Beginning Phase 1 (context loading).
-```
-
-For a single-element chain, the end of Step 6 is the end of the run. Step 7 below applies only when the `chain-stages` CSV has 2 or more elements. When the run is over, close with the user's next action — one command they can run now. A prohibition is not a next action. Take it from the `report-finalize` result: `nextCommand` (`{command, note}`) is the table below already applied, and `nextRecommendedPhase` (`phase`, `status`, `rationale`) is what it was applied to — do not re-derive either from the report, and treat `nextRecommendedPhaseError` as "pointer unreadable", said in one line before the `validate-run` branch. After `implementation-planning`: open approval blockers → `/okstra-user-response`; a recorded `accept-risk` / `select` / `answer` is not an open blocker; no open approval blocker → `/okstra-run` → `implementation` or `--approve` (do not start another planning run; do not say `/okstra-inspect`). For every other task type: pointer `ready` → `/okstra-run` for that phase; `validate-run` failed → one-line cause then `/okstra-run`; otherwise `/okstra-inspect status`.
-
-## implementation unattended chaining (chain-stages)
-
-When `task-type == implementation` and the render-args `chain-stages` CSV has 2 or more elements, the current session acts as the orchestrator and runs the stages as an unattended chain in dependency order. Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`. For each stage `N` in the queue, in order:
-
-1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
-2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
-3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary. A `status:"failed"` row in place of `done` means the stage ended `FAIL` — stop the queue per the FAIL branch below.
-4. One-line report at each stage start/finish: `stage N start` / `stage N done → next K`.
-
-Once the whole queue is consumed, end the chain and report completion.
-
-- **Next stage not yet ready — normal termination:** When a stage in the queue is occupied by another implementation run as started/reserved and render-bundle is rejected with `--stage N already in progress or reserved by another run` (StageTargetError), this is not an exception — **terminate the chain normally** and report the remaining queue (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`).
-- **Stage ended FAIL — stop the queue and report:** When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row instead of `done`. **Stop the queue there** and report the failed stage, its report path, and the remaining queue. Do not continue to the next stage even when it is dependency-independent — later work must not be stacked on a confirmed regression. The `failed` row frees the occupancy, so `--stage <N>` re-enters that stage on its preserved worktree and branch.
-- **Exception gate during chaining:** If render-bundle raises a concurrent-run conflict or git stale-SHA reconciliation, **stop the chain at that stage** and present the gate to the user per the Step 5 procedure. Once the user resolves it, resume the remaining queue in place. Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining.
-
-## Forbidden patterns
-
-- Changing the question order the wizard emitted.
-- Hiding wizard options or keeping only the recommendations.
-- Turning a `text` prompt into a picker.
-- Dropping the `--answer` flag on an empty answer.
-- Bypassing the wizard/render-bundle path by calling `okstra.sh`.
-- Calling render-args on a state the user aborted before render-bundle.
-- Starting phase work arbitrarily before reading the Okstra lead prompt.

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

@@ -1,240 +0,0 @@
-# okstra-schedule-gen AI Manual
-
-## 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)
-- 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 and invocation
-
-`okstra-schedule-gen` gathers non-done tasks in a task group and produces one client-facing work schedule from user-selected unfinished implementation stages.
-
-Public invocation:
-
-```text
-/okstra-schedule-gen [task-group]
-```
-
-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.
-
-Output location:
-
-```text
-<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
-```
-
-Do not use it for single-task status analysis or phase execution. Use `okstra-inspect status` and `okstra-run` for those jobs.
-
-## Preflight and task-group resolution
-
-Run one literal-token preflight call:
-
-```bash
-okstra preflight --runtime claude-code
-```
-
-On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On
-`Okstra preflight: ready`, carry the fixed `Project root` line. Resolve an
-explicit task-group from the invocation or host request. If none is unambiguous,
-run `okstra model-io task-selection-input --project-root <projectRoot>` and ask
-the user to choose from the fixed `Task` rows; never guess. Then run
-`okstra model-io schedule-input --project-root <projectRoot> --task-group <group>`
-and use only its fixed task metadata rows.
-
-On zero matches, report that the task group was not found and do not create a file.
-
-## Candidate filter
-
-`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 resolved `done` tasks.
-- Include every other resolved state.
-- If no task remains, report that all tasks are done and do not create a file.
-
-Do not render `workStatus` as the detailed task status. The per-task `Status` value is `<taskType> / <currentPhase>`.
-
-## Source-aware Stage Map resolution
-
-For every candidate task, call:
-
-```bash
-okstra stage-map <task-key> --text
-```
-
-The successful fixed response carries `Status`, `Task key`, `Task root`, `State`,
-`Source plan path`, and lossless numbered `Stages`, `Done stages`, and `Planning`
-count/name/value rows.
-
-Handle each result explicitly:
-
-- `Status: ready`, `State: ready`: use exactly `Source plan path`; do not pick a report by mtime or `latestReportRecordPath`. Select only stages not present in the done-stage rows.
-- `Status: ready`, `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.
-- `Status: error` or another state: stop before drafting and report `Failure stage` and `Failure reason`. A corrupt or conflicting source must never fall back to a guessed 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.
-
-If a ready task has no unfinished stages, render `_Complete — no remaining stage_` and omit forward effort.
-
-## Stage selection
-
-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.
-
-Skip the picker when the remaining work has only one possible bundle and use all unfinished stages. Record the final stage numbers as `selectedStages`.
-
-## Temporary selection contract
-
-Write a paired draft and selection input with one timestamp:
-
-```text
-.okstra/tasks/<task-group-segment>/schedule/.draft/<timestamp>.md
-.okstra/tasks/<task-group-segment>/schedule/.draft/<timestamp>.selection.json
-```
-
-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.data.json",
-      "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
-        }
-      ]
-    }
-  ]
-}
-```
-
-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
-
-Only these canonical categories are valid:
-
-| workCategory | Default phase |
-|---|---|
-| `bugfix` | Phase 1 for High or Med-High risk; otherwise Phase 2 |
-| `feature` | Phase 2 |
-| `improvement` | Phase 2 |
-| `refactor` | Phase 3 |
-| `ops` | Phase 3 |
-
-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.
-
-## Template contract
-
-Follow `schedule.template.md` exactly. The required top-level order is:
-
-1. `## At a Glance`
-2. `## Executive Summary`
-3. `## Task Dependency Graph`
-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`
-
-Keep an empty required section and render `_none_`. Headings and field labels stay as English template literals; body prose is Korean.
-
-Each scheduled task uses this stage-level Work Breakdown shape:
-
-```markdown
-| 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 |
-```
-
-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.
-
-An unrepresentable half-day allocation is a validation error. Do not substitute a fallback allocation algorithm; revise the task sizing or selected-stage scope.
-
-## Gantt contract
-
-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:
-
-```text
-DEV-1 Stage 2  ████      days=2.0~3.0
-DEV-1 Stage 3      ████  days=1.0~2.0
-```
-
-A row is labelled `Stage <n>` when exactly one task is scheduled and `<TASK-ID> Stage <n>` when more than one is; the annotation is `days=<lower>~<upper>`. Spell the stage out — `S1` is an opaque code that costs the reader a lookup and saves five characters. Do not emit a row for a completed, unselected, missing, or unknown stage. Bar length is arithmetic: one column is half a day, so a bar runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5` open cells `░`.
-
-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.
-
-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.
-
-## Client-facing boundary
-
-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.
-
-Resolve opaque source-report codes inline or in the optional final Glossary. Decision-item codes do not belong in the schedule.
-
-## Two validation gates
-
-Run both gates against the same draft and temporary selection contract.
-
-1. Deterministic gate:
-
-   ```bash
-   python3 ~/.okstra/lib/validators/validate-schedule.py <draft> --selection-json <selection>
-   ```
-
-2. Only after that command passes, create a new `.okstra/agent-invocations/schedule-verification/<invocation-id>.instructions.md` with the draft, selection JSON, and checks, but not the lead's reasoning. Run `okstra agent-prompt materialize --purpose schedule-verification --audience schedule-verifier ...` and verify the returned metadata before dispatch. A native host call uses the verified prompt body plus `hostModelValue`; a deterministic provider process uses `okstra worker-dispatch`, the prompt path, and `modelExecutionValue`. The verifier checks narrative coherence, phase rationale, executable order, engineering-only scope, and contradictions with the structured rows.
-
-Capture the raw verifier return under the purpose directory's `.tmp/`, then run `okstra agent-prompt materialize-result`, `complete`, and `verify-completion` in order. Parse only the verified `returnedBody`; an inline or unverified response cannot pass the narrative gate.
-
-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.
-
-After both gates pass:
-
-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
-
-- 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 Gantt row without its `Stage <n>` label and `days=` range, or abbreviating that label to `S<n>`.
-- Drawing stage order in `## Task Dependency Graph` — that graph carries cross-task edges only; stage order lives in the Work Breakdown's `Depends On` column.
-- 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/for-ai/skills/okstra-setup.md

@@ -1,167 +0,0 @@
-# okstra-setup AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-setup/SKILL.md`](../../../skills/okstra-setup/SKILL.md)
-- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
-- project registration impl: `src/commands/lifecycle/setup.mjs`
-- install/ensure-installed impl: `src/commands/lifecycle/install.mjs`
-
-## Purpose
-
-`okstra-setup` handles two things.
-
-1. Machine-level runtime install: `~/.okstra/`, `~/.claude/skills/`, `~/.claude/agents/`
-2. Project-level registration: `<PROJECT_ROOT>/.okstra/project.json`
-
-It is not a day-to-day task-running skill. If a task is already prepared, route to `okstra-run` or `okstra-inspect`.
-
-## When to use
-
-Use it when:
-
-- The user asks for "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time setup".
-- `~/.okstra/version` is missing or looks stale.
-- The current project has no `.okstra/project.json`.
-
-Do not use it when:
-
-- The user wants to start a task run. Use `okstra-run` instead.
-- The user wants to view status/history/report. Use `okstra-inspect` instead.
-- `.okstra/project.json` already exists and only day-to-day usage is needed.
-
-## Pre-run checks
-
-Tell the user that Node 18+ and Python 3.10+ are required. If it is unclear whether the current working directory is inside the project that will host the okstra metadata, confirm the project root first.
-
-Install command:
-
-```bash
-npx -y okstra@latest install --runtime claude-code
-```
-
-Treat this command as idempotent. Even if already installed, re-run it to align the runtime, skill, and agent payload with the current package version (agent payload = the `~/.claude/agents/<worker>.md` worker definitions + the `~/.okstra/installed-agents.json` manifest). If it fails, show the stderr to the user verbatim. Do not fall back to the legacy `okstra-install.sh`.
-
-## Command invocation rule
-
-After `okstra install`, every subsequent command must begin with the literal `okstra` token.
-
-Allowed forms:
-
-```bash
-okstra preflight
-okstra setup --yes --project-root /abs/project --project-id my-project
-okstra doctor --runtime claude-code
-```
-
-Forms to avoid:
-
-- `export PYTHONPATH=...`
-- `eval "$(okstra paths --shell)"`
-- shell variables like `$PROJECT_ROOT`
-- `$(...)` command substitution
-- okstra calls wrapped in `if`, `&&`, `||`
-
-Because `okstra <subcmd>` bootstraps its own Python path, do not use `okstra paths --shell` in this skill. If you need the okstra home, run `okstra paths --field home` as a separate call and carry the printed path.
-
-## Project root resolution
-
-Run first:
-
-```bash
-okstra preflight
-```
-
-Handle the result:
-
-- `Okstra preflight: ready`: already a registered project. Show `Project root`, `Project JSON`, and `Project ID` to the user and confirm whether to keep it.
-- `Okstra preflight: failed` with `Stage: resolve`: get an absolute project root from the user and re-run `okstra preflight --cwd /abs/path`.
-- `Okstra preflight: failed` with `Stage: project_json_missing`: proceed with the normal create path.
-- any other failure stage: show `Reason` verbatim and follow `Recovery`.
-
-## Create or keep project.json
-
-If `<PROJECT_ROOT>/.okstra/project.json` exists, show `projectId` and `projectRoot` and confirm whether to keep or overwrite. The default is keep. Changing the existing `projectId` requires deleting the file, so do not overwrite automatically.
-
-If the file does not exist, ask for a project id. The answer must be non-empty and contain at least one alphanumeric character. Calling `okstra setup --yes` with an empty value fails, so re-ask.
-
-Create command:
-
-```bash
-okstra setup --yes --project-root /abs/project --project-id my-project
-```
-
-`okstra setup` also refreshes the okstra-managed citation-guidance block in
-`<PROJECT_ROOT>/CLAUDE.md` and `AGENTS.md` when those files already exist (it never
-creates them). The block tells agents not to carry okstra-internal references — report
-section numbers, `C-NNN` clarification ids, run/stage ids, `.okstra/...` paths — into
-writing that is not an okstra report, where the reader cannot resolve them. The command
-reports the files it touched in its JSON `citationGuidance` array; a failure there is a
-`warning:` line, not a non-zero exit. Tell the user which guidance files were updated so
-they can review the appended block.
-
-## Optional configuration
-
-Per the source, Step 3.5 is optional configuration performed only when the user explicitly wants it — read `references/project-config.md` in the skill directory for the detailed procedure. If the defaults are enough, skip it and go to doctor.
-
-Optional settings:
-
-- `worktreeSyncDirs`: a list of project-relative directories to symlink into the task worktree. The default is `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
-- `qaCommands`: check-only lint/format/typecheck/test commands the implementation verifier runs.
-- `qaEnv`: the replica/test DB, local app URL, env file, and surface patterns
-  Okstra uses to attempt Tier 3 automatically; real DB/API verification remains
-  a user-owned advisory when the environment is unavailable or the result is
-  non-PASS.
-- PR body template: `okstra config set pr-template-path "<path>" --scope project|global`
-- final report language: `okstra config set report-language <language-tag> --scope project` (`en`, `ko`, `fr`, `pt-BR`, …; default `en`)
-- `architecture.style`: the project's declared architecture — `hexagonal`,
-  `layered`, or `none` (default `none` when absent, unrecognized, or
-  unreadable). `okstra setup` never writes it; hand-add it to `project.json`
-  and the upsert preserves it. Declaring a style promotes that architecture's
-  placement rules from advisory to a binding planning + verification
-  constraint — under `hexagonal` an extracted variation point must be a port,
-  under `layered` the dependency direction is worker-judged with no machine
-  check. See section F of `references/project-config.md`.
-- `reviewRulePacks`: absolute paths to the project's own review rule packs (a
-  team PR-review skill's `SKILL.md`). Without a declaration a pack applies only
-  when the task brief cites its exact path; declared here it applies to every
-  run, and the two channels are a union. Read by `implementation-planning`, the
-  executor preflight, the implementation verifier, and `final-verification`.
-  `okstra setup` never writes it. `okstra doctor --phase <phase>` fails when a
-  declared path is not readable. See section G of
-  `references/project-config.md`.
-
-If `qaCommands.cmd` contains a token implying mutation, the verifier refuses it. The actual authority for the deny-list is `scripts/okstra_ctl/qa_commands.py`.
-
-## Automatic Claude settings symlink
-
-`okstra setup` provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to `~/.okstra/templates/settings.local.json`. If an existing regular file is present, it backs it up as `.bak.<timestamp>` and then places the symlink. If a failure message appears, the user must manually merge the existing project-specific rules.
-
-## Verify
-
-Run last:
-
-```bash
-okstra doctor --runtime claude-code
-```
-
-If every check is OK, report setup complete. If any check fails, show the output verbatim and let the user decide whether to reinstall or skip.
-
-## Completion message
-
-Keep it short and include the following.
-
-- runtime location: `~/.okstra` (also show the `version stamp: x.y.z` line from the install summary)
-- project metadata: `<PROJECT_ROOT>/.okstra/project.json`
-- `projectId`
-- next step: `/okstra-run`
-
-## Common failure handling
-
-| Symptom | Handling |
-|---|---|
-| `command not found: npx` | Point to installing Node 18+ |
-| `--project-id is required` | Re-ask for the project id and re-run with a non-empty value |
-| `projectId mismatch` | Confirm with the user which id is canonical. Do not delete automatically |
-| `.okstra/` write EACCES | Explain the ownership/writability problem |
-| `.claude/settings.local.json` symlink warning | Show the backup file and symlink state to the user and guide a manual merge |