okstra 0.111.0 → 0.112.0

package/runtime/skills/okstra-schedule/SKILL.md

@@ -6,168 +6,118 @@ model: opus
 
 # OKSTRA Schedule
 
-## Overview
-
-Generate a consolidated work schedule for all non-done tasks in a given `task-group`. The skill reads each task's `task-manifest.json` and `latestReport`, classifies tasks into phases by priority and risk, and writes a single Markdown plan file under `.okstra/tasks/<task-group>/schedule/`.
-
-The skill runs as a single Claude lead synthesis (lightweight mode). A `--cross-verify` multi-agent variant was previously sketched here but never specified end-to-end; it has been dropped pre-1.0 and is tracked as a follow-up if multi-agent schedule verification is needed later.
+Generate a consolidated work schedule for all non-done tasks in a given `task-group`. The skill reads each task's `task-manifest.json` and `latestReport`, classifies tasks into phases by priority and risk, and writes a single Markdown plan file under `.okstra/tasks/<task-group>/schedule/`. It runs as a single Claude lead synthesis (lightweight mode); the frontmatter `model: opus` switches supporting harnesses to Opus-class for the turn — cross-task synthesis needs that reasoning depth.
 
 ## When to Use
 
 - User asks to generate a work schedule / plan / "일정" for an entire `task-group`
 - User wants a single document that summarizes all non-done tasks with effort, risk, and dependencies
-- A `task-group` exists in `.okstra/discovery/task-catalog.json` with at least one task whose `workStatus` is not `done`
 
-**Do NOT use** for single-task analysis (use `okstra-inspect status` instead) or when the user wants to actually execute one task (use the parent `okstra` skill).
+**Do NOT use** for single-task analysis (use `okstra-inspect status`) or to execute one task (use `okstra-run`).
 
-## Trigger Patterns (recognize both)
+Explicit command form: `okstra schedule <task-group> [--title "<custom title>"] [--directive-file <abs-path>]`. If `--title` is omitted, derive a default from `task-group` (e.g. `uploadFont` → `uploadFont — Work Schedule`).
 
-**Natural language (Korean / English)**:
-- "uploadFont 작업 일정 만들어줘"
-- "uploadFont schedule 생성"
-- "uploadFont 일정 계획표"
-- "Generate schedule for uploadFont"
+## Step 0: Preflight
 
-**Explicit command**:
-- `okstra schedule <task-group>`
-- `okstra schedule <task-group> --title "<custom title>"`
-- `okstra schedule <task-group> --directive-file <abs-path>` (optional; see "Directive override" below)
+Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
+
+```bash
+okstra preflight --runtime claude-code --json
+```
 
-If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadFont` → `uploadFont — Work Schedule`).
+Parse the stdout JSON. `ok: true` → carry `projectRoot` as a literal string and use it to locate `.okstra/discovery/task-catalog.json` and the task-group directory. `ok: false` → tell the user to run `/okstra-setup` first, then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
 
-## Preflight: Verify okstra runtime + project setup
+## Audience & authority (READ FIRST — drives everything below)
 
-Before anything else in this skill, run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
+**The schedule is a client-facing work plan.** It assumes the team has all permissions and can proceed without further approval. Even when the underlying per-task reports flag blocking items, missing approvals, or "사용자 확인 필요 항목", **the schedule MUST NOT surface them** — those belong in the internal report. Never emit a decision checklist, a `#### 사용자 확인 필요 항목` sub-section, `Done`/`Ready?`/`Blocking Decisions` columns, or checkbox lists; "Status" reflects work phase only.
 
-1. `okstra ensure-installed --runtime claude-code`
-   If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
+**Assume the user and their team hold full authority and every permission required.** External approvals, access grants, sign-off, and vendor coordination are treated as already satisfied unless a report names a concrete external dependency outside the user's control. Concretely:
 
-2. `okstra check-project --json`
-   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
+- **Effort sizing & day totals** count engineering work only — strip approval-waiting / coordination buffers from source sizings (note the adjustment in `## Executive Summary` if material).
+- **Gantt bars** represent engineering duration only; no dead-time gaps for approval cycles. `(after <TASK-ID>)` marks genuine engineering dependencies only.
+- **Risk Mitigation Strategy** lists real engineering risks (data loss, regression surface, rollback path) — permission/coordination items are dropped.
+- **Recommended Immediate Actions / Next Action** are concrete engineering steps; "권한 확인", "승인 요청", "이해관계자 정렬" 류는 출력 금지.
+- **Cross-Task Dependencies** covers engineering coupling only (shared modules, release order, package versions).
 
-   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.okstra/discovery/task-catalog.json` and the task-group directory.
+**The schedule must be self-contained.** Opaque codes pulled from internal reports (`FC-5`, `UC-12`, `M1`, decision-item letters, …) must not appear unresolved. Choose one per identifier: **Form A** (≤3 codes) — replace the code inline with a 5–20자 one-line description of the item; **Form B** (≥4 recurring codes) — keep the codes and emit a `## Glossary` table as the last section resolving every one. Decision-item letters (`A1`, `B2`, …) are approval items and may not appear at all. TASK-IDs listed in `## At a Glance` need neither.
 
-Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
+## Contract SSOT — template + validator
 
-## Process Procedure
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, `█`/`░`/`! crit`/`est` legend), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_없음_` — never delete or reorder headings. Never emit mermaid or any graph DSL.
 
-### Step 0: Verify model (권장 게이트)
+`~/.okstra/lib/validators/validate-schedule.py` is the enforcement for all of the above (heading order, field labels, controlled vocabulary — e.g. `Med-High` is the canonical risk form — forbidden translations, checkbox bans, Gantt fence rules, unresolved-code detection). The Step 4 ambiguous-classification rationale line is the one rule the validator does not yet enforce — emit it yourself.
 
-This skill performs cross-task synthesis (multi-task classification, dependency reasoning, phase placement, Gantt/timeline assembly) which benefits substantially from Opus-class reasoning. The frontmatter `model: opus` field above instructs supporting Claude Code harness versions to switch automatically; if the harness ignores it, this gate catches the case explicitly.
+Two computation rules the template scaffold cannot carry inline:
 
-1. Inspect the active session model. The model is shown in the status line, accessible via `/model`, and embedded in the runtime context as the model name (e.g. `claude-fable-5`, `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5-*`).
-2. If the active model is **Opus-class or above** (`claude-opus-*`, `claude-fable-*`): proceed to Step 1.
-3. If the active model is **Sonnet or Haiku-class**: STOP and output the following message verbatim, then wait for user response:
-   ```
-   okstra-schedule는 Opus-class 모델에서 실행하는 것을 권장합니다 (현재: <active-model>).
-   /model opus 로 전환 후 다시 호출하시거나, 'sonnet으로 진행' 이라고 명시하시면 그대로 실행합니다.
-   ```
-4. If the user explicitly insists on the lower model ("sonnet으로 진행", "그대로 진행", "force", or similar): proceed to Step 1, but prepend a single-line warning at the top of the generated schedule file: `> ⚠️ Generated with <model> (not Opus). Cross-task synthesis quality may be reduced.`
+- **Effort-to-Day mapping**: day ranges per size are defined once in the template's `### Effort Sizing 기준` table. For the At a Glance totals line, sum that table's lower bounds across in-scope tasks for the lower total and upper bounds for the upper total.
+- **`[NEEDS-OKSTRA-RUN]` / `[PARSE-ERROR: <section>]` placement**: put the marker immediately under the per-task heading inside its Phase section and fill only the available fields — never relocate it to a sibling section.
 
-This is a recommendation gate, not a blocking mechanism — the override path in step 4 always lets the run proceed.
+## Procedure
 
 ### Step 1: Resolve task-group and collect tasks
 
 1. Read `.okstra/discovery/task-catalog.json`.
-2. **Normalise the user-supplied `<task-group>` argument:** lowercase it, then strip every character that is not `[a-z0-9]` (drop spaces, hyphens, underscores, dots, etc.). Apply the same transform to each entry's `taskGroupPathSegment`. Match when the two normalised forms are equal. This is the single comparison rule — do NOT also fall back to the raw `taskGroup` field.
+2. **Normalise the user-supplied `<task-group>` argument:** lowercase it, then strip every character that is not `[a-z0-9]`. Apply the same transform to each entry's `taskGroupPathSegment`. Match on equality — this is the single comparison rule; do NOT also fall back to the raw `taskGroup` field.
 3. If no tasks found, output `해당 task-group을 찾을 수 없습니다.` and stop.
 4. For each matched task, read `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json` directly. Catalog data may be stale; the manifest is authoritative.
-5. **Derive `<project-id>`** for the schedule header: prefer `task-catalog.json`'s top-level `projectId` field if present, otherwise use the first matched manifest's `projectId` field. Do not invent a value.
+5. **Derive `<project-id>`** for the header: prefer `task-catalog.json`'s top-level `projectId`, otherwise the first matched manifest's `projectId`. Do not invent a value.
 
 ### Step 2: Filter by workStatus
 
-`workStatus` is also surfaced directly inside each catalog entry, but Step 1 still re-reads each `task-manifest.json` because the manifest is authoritative — no extra fetch is needed beyond that.
+For inference when `workStatus` is missing or empty, defer to the inference table in `skills/okstra-inspect/SKILL.md` (`status.4` → "Default value convention") — do not duplicate it here. Then filter: resolved `done` → exclude; everything else (`todo` / `in-progress` / `blocked` / `phase-done` / inferred non-done) → include.
 
-For inference rules when `workStatus` is missing or empty, **defer to the inference table in `skills/okstra-inspect/SKILL.md` (`status.4` → "Default value convention")** instead of duplicating it here. Apply that table to derive a working value, then filter:
-
-- If the resolved value is `done` (set by the user OR inferred via `currentStatus == "completed"` + terminal next-phase) → exclude.
-- Otherwise (`todo` / `in-progress` / `blocked` / `phase-done` / explicit user value / inferred non-done) → include.
-
-If after filtering 0 tasks remain, output:
-```
-해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.
-```
-Then stop without creating a file.
+If 0 tasks remain, output `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.` and stop **without creating a file**.
 
 ### Step 3: Per-task data extraction
 
-For each included task, gather:
-
-**From `task-manifest.json`**:
-- `taskId`, `taskGroup`, `taskKey`
-- `workCategory`
-- `workflow.currentPhase`, `workflow.currentPhaseState`
-- `taskType`
-- `workStatus`
-- `latestReportPath`
-
-**From the report file (`latestReportPath`)**, parse:
-- Title / Problem statement
-- Solution / Architecture
-- Work Breakdown (table)
-- Verification Commands
-- Rollback strategy
-- Effort, Risk, Priority, Scope, Repos
-
-Note: per-task reports may include "사용자 확인 필요 항목" / blocking items / approval requests. **Do not extract or surface these in the schedule** — the schedule is a client-facing work plan. Internal blockers stay in the source report.
+From `task-manifest.json`: `taskId`, `taskGroup`, `taskKey`, `workCategory`, `workflow.currentPhase`, `workflow.currentPhaseState`, `taskType`, `workStatus`, `latestReportPath`.
 
-If the report file does not exist or cannot be parsed:
-- **Before tagging `[NEEDS-OKSTRA-RUN]`, attempt the manifest-staleness fallback** (manifest pointer can become stale when an interleaved `--render-only` prep run advances `latestReportPath` to a path that will never be written):
-  1. Resolve `<task-root>` from `task-manifest.json` → `taskRootPath`.
-  2. List `<task-root>/runs/<taskType>/reports/final-report-*.md` and pick the **newest existing file by mtime** (NOT by filename timestamp — render-only prep can create entries whose timestamp is later than the last completed run's report). If none exists, also try `<task-root>/runs/*/reports/final-report-*.md` across all task-types as a last-resort.
-  3. If a candidate is found, parse it and proceed normally. Append a one-line note at the top of that task's per-task block in the schedule output:
-     `> _Report fallback: manifest pointed at non-existent <pointed-name>, used <actual-name> (mtime <ts>) instead. Manifest may be stale due to a render-only prep — see Phase 6 of okstra contract._`
-  4. If no candidate file exists either, only then fall through to `[NEEDS-OKSTRA-RUN]`.
-- If still unresolvable: use only manifest metadata, mark the task entry with `[NEEDS-OKSTRA-RUN]`, and do not abort — continue with remaining tasks.
+From the report file (`latestReportPath`): Title / Problem statement, Solution / Architecture, Work Breakdown table, Verification Commands, Rollback strategy, Effort, Risk, Priority, Scope, Repos. Blocking items / approval requests in the report are **not** extracted (see Audience).
 
-If parsing fails for a specific section:
-- Mark the entry with `[PARSE-ERROR: <section>]` and continue.
+If the report file does not exist or cannot be parsed, attempt the **manifest-staleness fallback** before tagging (`latestReportPath` can go stale when an interleaved `--render-only` prep advances it to a path that is never written):
 
-### Step 4: Synthesis
+1. Resolve `<task-root>` from the manifest's `taskRootPath`.
+2. List `<task-root>/runs/<taskType>/reports/final-report-*.md` and pick the **newest existing file by mtime** (NOT by filename timestamp). If none, try `<task-root>/runs/*/reports/final-report-*.md` across all task-types.
+3. If found, parse it and add one line at the top of that task's block: `> _Report fallback: manifest pointed at non-existent <pointed-name>, used <actual-name> (mtime <ts>) instead._`
+4. Only if no candidate exists, tag the entry `[NEEDS-OKSTRA-RUN]`, use manifest metadata only, and continue with the remaining tasks. If parsing fails for one section, tag `[PARSE-ERROR: <section>]` and continue.
 
-Claude lead synthesises the schedule directly using collected data. Proceed to Step 5.
+### Step 4: Phase classification
 
-### Step 5: Phase classification heuristic
-
-Classify each task into one of three phases based on report data.
-
-**`workCategory` accepted values** — the category keys come from `scripts/okstra_ctl/worktree.py::_WORK_CATEGORY_PREFIX` (code source), plus the `unknown` fallback emitted by `render.py`. The phase mapping below is layered on top: when a category is added to `worktree.py`, add a row here too — otherwise the new category falls through to `unknown` → Phase 2.
+`workCategory` keys come from `scripts/okstra_ctl/worktree.py::_WORK_CATEGORY_PREFIX` (code source) plus the `unknown` fallback from `render.py`. When a category is added there, add a row here — otherwise it falls through to `unknown` → Phase 2.
 
 | workCategory | Default phase |
 |--------------|---------------|
-| `bugfix` | Phase 1 (when risk is High/Med-High); otherwise Phase 2 |
-| `feature` | Phase 2 |
-| `improvement` | Phase 2 |
-| `refactor` | Phase 3 |
-| `ops` | Phase 3 |
-| `docs` / `doc` | Phase 2 |
-| `unknown` (or unmatched / missing) | **Phase 2**, with a one-line rationale `> _workCategory '<raw-value>' 미정의 — Phase 2로 기본 분류._` at the top of that phase section |
+| `bugfix` | Phase 1 when risk is High/Med-High; otherwise Phase 2 |
+| `feature` / `improvement` / `docs` / `doc` | Phase 2 |
+| `refactor` / `ops` | Phase 3 |
+| `unknown` (or unmatched / missing) | Phase 2, with rationale `> _workCategory '<raw-value>' 미정의 — Phase 2로 기본 분류._` at the top of that phase section |
+
+Priority overrides category: `P0` → Phase 1; `P1`/`P2` → Phase 2; `P3` or multi-repo + infrastructure scope → Phase 3. When still ambiguous, place the task in the closest phase and add a one-line rationale at the top of that phase section (not validator-enforced — emit it yourself).
 
-Priority overrides category:
+### Step 5: Gantt decision (render by default)
 
-- **Phase 1 (안정성/Critical)**: priority `P0`, OR `workCategory == "bugfix"` with High / Med-High risk
-- **Phase 2 (개선/기능)**: priority `P1` or `P2`, OR `workCategory in {"feature", "improvement", "docs", "doc"}`, OR fallback per the table above
-- **Phase 3 (확장/아키텍처)**: priority `P3`, OR `workCategory in {"refactor", "ops"}`, OR multi-repo + infrastructure scope
+`## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every task is effort=XXL with no visible decomposition, or all tasks lack both effort sizing and decomposition). Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> 일별 배분은 추정치이며 차단 항목 해소 후 갱신 권장.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
 
-When the classification is genuinely ambiguous after applying the table + priority override, place the task in the closest phase and add a one-line rationale at the top of that phase section.
+When you do skip, insert in the section's position exactly: `> _Gantt Chart 생략: <concrete reason referencing the actual data>._`
 
-> Note: enum codification (turning this de-facto list into a `validators/`-enforced contract) is out of scope for this skill — file as a follow-up if needed.
+**Directive override (highest priority).** Before applying the heuristic, check for a `## Directive` section, first hit wins: (1) the `--directive-file <abs-path>` argument; (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`; (3) none → apply the default heuristic silently. A found directive overrides the render/skip heuristic for the affected section — note it inline as `> _Per Directive directive: <verbatim short excerpt>._` — and its pre-supplied day allocations / phase weights are used verbatim as bar lengths. A directive file without a `## Directive` heading counts as "no directive".
 
 ### Step 6: Write the schedule file
 
-Output path:
 ```
 .okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
 ```
 
-- `<task-group-segment>`: from manifest's `taskGroupPathSegment` (lowercase, hyphenated).
-- Timestamp: current local time at generation, format `YYYY-MM-DD_HH-MM-SS`.
-- Auto-create the parent directory if it does not exist.
+`<task-group-segment>` comes from the manifest's `taskGroupPathSegment` verbatim. Timestamp is current local time. Auto-create the parent directory. Never overwrite an existing file — on a same-second collision append `-2`, `-3`, ….
 
-### Step 7: Completion message (Korean)
+### Step 7: Self-validate before reporting completion
 
-After writing the file, reply briefly:
+1. Re-read the file you just wrote.
+2. Run `python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>`.
+3. If it exits non-zero, fix the file and re-validate. Do not print the Step 8 message until it passes.
+4. If the validator is not installed, fall back to a manual check against the template: every template `##` heading present with exact spelling, title ends with `— Work Schedule`, `> Generated:` block present.
+
+### Step 8: Completion message (Korean)
 
 ```
 ✓ Schedule 생성 완료: <relative-path>
@@ -177,325 +127,20 @@ After writing the file, reply briefly:
 - 모드: lightweight
 ```
 
-## Audience (READ FIRST — drives everything below)
-
-**The schedule is a client-facing work plan.** It assumes the team has all permissions and can proceed without further approval. Even when the underlying per-task reports flag blocking items, missing approvals, or "사용자 확인 필요 항목", **the schedule MUST NOT surface them**. Those concerns belong in the internal report, not the deliverable.
-
-### Authority & permissions assumption (schedule sizing)
-
-**Assume the user (and their team) holds full authority and every permission required for every included task.** External approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps are treated as already satisfied unless the source per-task report explicitly identifies a concrete external dependency outside the user's control.
-
-Concretely, when computing this schedule:
-
-- **Effort sizing & day totals**: Count engineering work only. Do NOT inflate `S/M/L/XL` or the `<X.X> ~ <Y.Y> days` total for permission-checking, approval-waiting, stakeholder-coordination, or "권한 확인" buffer time. If a per-task report's effort sizing already bakes in such buffers, strip them when synthesising the schedule total and note the adjustment inside `## Executive Summary` if material.
-- **Gantt Chart**: Bars represent engineering duration only. Do not insert dead-time gaps for approval cycles or coordination wait. Sequential `(after <TASK-ID>)` annotations remain valid only for genuine engineering dependencies.
-- **Risk Mitigation Strategy**: Permission/authority/external-coordination items are NOT acceptable risk strategies — drop them. Real risks (data loss, regression surface, rollback path, performance regression, etc.) only.
-- **Recommended Immediate Actions** and **Execution Priority Matrix → Next Action**: Every action is a concrete engineering step (write test, modify file, run command). "권한 확인", "승인 요청", "이해관계자 정렬" 같은 항목은 출력 금지.
-- **Cross-Task Dependencies & Shared Concerns**: Only engineering coupling (shared modules, release order, package versions). Cross-team coordination notes inherited from per-task reports MUST be filtered out.
-
-This rule is independent of the existing client-facing audience rule — even if a future variant of this skill chose to surface decision items, the authority assumption still suppresses external-permission accounting.
-
-Concretely:
-- No "Consolidated User Decision Checklist" section.
-- No per-task "사용자 확인 필요 항목" sub-section.
-- No `Done` / `Ready?` / `Blocking Decisions` columns anywhere.
-- No checkboxes (`[ ]` / `[x]`) — bullet lists only.
-- "Status" field reflects work phase only; never bubble up "blocked" rationale prose.
-
-**The schedule must be self-contained.** Every identifier the client reads must be resolvable from the schedule itself. Cross-document opaque codes pulled from internal reports — `FC-5`, `UC-12`, `TC-3`, `RC-2`, `M1`, `A1`, `B2`, `C3`, decision-item letters, finding codes, milestone codes — **MUST NOT appear unresolved**. The client cannot look them up against the source report, and a bare code adds zero value to a delivery plan.
-
-**Two acceptable forms — choose one per identifier:**
-
-**Form A — inline replacement (preferred for ≤3 codes).** Replace the identifier with a brief description of that item's content (한 줄 요약, 5–20자 내외). Drop the code entirely; do not write code-and-content together.
-
-| Source report | ❌ Forbidden | ✅ Form A |
-|---------------|--------------|-----------|
-| `FC-5: 결제 게이트웨이 타임아웃 처리 누락` | `FC-5 수정` / `FC-5 (결제 타임아웃)` | `결제 게이트웨이 타임아웃 처리` |
-| `M2: 1차 베타 배포` | `M2 도달` | `1차 베타 배포` |
-| `UC-3: 폰트 업로드 흐름` | `UC-3 검증` | `폰트 업로드 흐름 검증` |
-
-**Form B — `## Glossary` at document bottom (preferred when ≥4 codes recur).** Keep the bare identifier in the body **only if** the document also emits a `## Glossary` section as the last `##` section (after `## Recommended Immediate Actions`). The glossary MUST resolve every opaque code that appears in the body. Format:
-
-```markdown
-## Glossary
-
-| Code | Description |
-|------|-------------|
-| FC-5 | 결제 게이트웨이 타임아웃 처리 누락 |
-| M2   | 1차 베타 배포 |
-| UC-3 | 폰트 업로드 흐름 |
-```
-
-Rules for Form B:
-- Header literal `| Code | Description |` is required.
-- Every opaque code referenced anywhere in the body MUST have a glossary row. The validator flags any unresolved code.
-- Decision-item letters (`A1`, `B2`, `C3`, `D4`) — these are blocking/approval items that MUST NOT appear in the schedule at all (see "client-facing" rule above). The glossary cannot whitewash them.
-
-The only cross-reference that needs neither inlining nor a glossary entry is a TASK-ID that itself appears in the `## At a Glance` table.
-
-The validator rejects any of these patterns.
-
-## Section Contract (required)
-
-The canonical template lives at `~/.okstra/templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
-
-### MUST — exact ordered heading list
-
-The output file MUST contain exactly these top-level (`##`) sections, in this order, with these exact English headings (verbatim, no translation, no rewording, no extra punctuation):
-
-1. `## At a Glance`
-2. `## Executive Summary`  (with subsection `### Effort Sizing 기준`)
-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** (allowed at fixed positions only):
-- `## Gantt Chart` — between `## Task Dependency Graph` and `## Phase 1: Critical Fixes`.
-- `## Glossary` — last `##` section, after `## Recommended Immediate Actions`. Required when the body contains any opaque code (FC-N, UC-N, M-N, …) using Form B; forbidden in any other position.
-
-If a phase has zero tasks, keep its heading and write `_없음_` underneath. **Never delete a heading.** **Never reorder.**
-
-### SHOULD — graphic section (English heading only)
-
-The following section is the only graphic output and MUST appear in this position (between `## Task Dependency Graph` and `## Phase 1: Critical Fixes`), with this exact English heading literal:
-
-- `## Gantt Chart` — render as a fenced **ASCII** chart inside a plain ```` ``` ```` block (no language tag, no `mermaid`). See "ASCII Gantt format" below.
-
-#### ASCII Gantt format (REQUIRED — mermaid is forbidden)
-
-Render the chart as a monospace text block. **The horizontal axis MUST be a relative day count starting at Day 1 (or J1) — never calendar dates from "today" or any other absolute date.** The schedule describes effort/duration in days, not a wall-clock plan; rendering `2026-05-04`, `Mon May 4`, etc. is a contract violation. Use this structure exactly:
-
-````
-```
-Day:            1    5    10   15   20   25   30
-                |    |    |    |    |    |    |
-Phase 1
-  <TASK-ID> (<S/M/L/XL>)       ██████          ! crit
-  <TASK-ID> (<S/M/L/XL>)             ████████
-Phase 2
-  <TASK-ID> (<S/M/L/XL>)                     ██████░░  est
-Phase 3
-  <TASK-ID> (<S/M/L/XL>)                              ████
-```
-````
-
-Rules:
-- Fence the block with plain ```` ``` ```` (NOT ```` ```mermaid ````, NOT ```` ```gantt ````, NOT ```` ```text ````). The fence MUST have no language hint so downstream validators can detect the format.
-- The first line is a `Day:` axis with **relative day numbers only** (1, 2, 3, … or J1, J2, J3, …). Do NOT substitute calendar dates, weekdays, ISO timestamps, or "today + N" labels — even if the user's environment shows today's date. Choose a tick interval (1, 2, or 5 days) so the axis fits within ~80 columns; align tick labels with `|` markers on the second line.
-- Day 1 is the start of Phase 1 (the first scheduled task). Subsequent task start columns are computed from cumulative durations, NOT from any external calendar.
-- Group bars under `Phase 1` / `Phase 2` / `Phase 3` headings (omit a phase if it has no tasks — but keep the order). Indent task rows by two spaces.
-- Each task row is `  <TASK-ID> (<size>)` left-aligned in a fixed-width label column (pad with spaces so all bars start in the same column), followed by spaces to position the bar at its start day, then the bar.
-- Use `█` for solid (committed) duration and `░` for the upper-bound / uncertainty tail when the effort sizing has a range. A single bar at mid-point is also acceptable.
-- Append annotations after the bar separated by spaces:
-  - `! crit` for critical-path items (replaces mermaid's `:crit,`).
-  - `est` when day allocations are estimated (replaces `:est,`).
-  - `(after <TASK-ID>)` to mark a sequential dependency when not visually obvious.
-- Keep total width ≤ 100 columns. If span exceeds the axis, increase the tick interval rather than wrapping.
-- When effort is XXL ("세분화 필요") and no decomposition exists, follow the skip-reason rule instead of inventing bars.
-
-#### Render-by-default rule (REVERSED from prior contract)
-
-These sections are **rendered by default**. Skip them ONLY when literally no usable day data exists anywhere in the source. Specifically:
-
-**`## Gantt Chart` — render whenever ANY of these hold:**
-- 2+ tasks with any effort sizing (S/M/L/XL — all map to day ranges via the Effort Sizing 기준 table)
-- 1 task whose Effort sizing yields any range (use range mid-point as a single bar, or render two bars `lo` and `hi` for visible uncertainty)
-- 1 task with explicit Part/Phase/Step decomposition in the source report (look for headings like "Part 1", "Phase 1", "Step N", "Quick Wins + CDN Architecture" etc.) — render bars at the **decomposition unit** level, even if internal day allocations are estimates
-- Any case where total estimated effort is ≥ 3 days
-
-When per-decomposition day allocations aren't crisply itemized, **estimate them yourself by splitting the parent effort range across the visible decomposition units** and append the `est` annotation after the bar (see ASCII Gantt format below) or add a one-line note `> 일별 배분은 추정치이며 차단 항목 해소 후 갱신 권장.` The reader benefits more from a rough visual than from no visual.
-
-**Skip is permitted ONLY when:**
-- Every task has effort=XXL ("세분화 필요") AND no decomposition is visible in the source — i.e. there is genuinely no day signal to plot
-- All included tasks lack BOTH effort sizing AND any decomposition
-
-When skipping, follow the skip-reason note rule below — but the skip should be rare. "Range is wide" or "user decisions pending" or "single task" are NOT acceptable skip reasons by themselves; render an estimate-tagged chart instead.
-
-#### Directive override (highest priority)
-
-Before applying the heuristics above, **check the schedule-level directive source** for a `## Directive` section.
-
-**Resolution order (first hit wins):**
-
-1. Absolute path passed via the `--directive-file <abs-path>` argument when invoking the skill.
-2. `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md` (the canonical schedule-level instruction-set location — okstra writes here when a schedule run is dispatched with `--directive`).
-3. **No directive file** — fall through and apply the default heuristic without any override. This is the normal case; do not warn, do not block.
-
-If a directive source is found and contains a `## Directive` section that affects Gantt rendering — e.g. "render a Gantt even with single XL task", "no Gantt needed" — that directive **overrides the heuristic and the skip-reason rule** for the affected section. When following a Directive override that contradicts the default heuristic, append a one-line note inside the rendered (or skipped) section: `> _Per Directive directive: <verbatim short excerpt>._` so the reader can trace why the section appeared/disappeared against the default. The Directive may also pre-supply day allocations, phase weights, or sub-task decompositions — use those verbatim as bar lengths in the Gantt.
-
-A directive file that exists but contains no `## Directive` heading is treated as "no directive" — fall through to the heuristic, no warning required.
-
-`## Gantt Chart` is the only `##` section that MAY be added beyond the 10 mandatory ones. Any other extra `##` heading is forbidden.
-
-#### MUST — emit a skip-reason note when omitting Gantt Chart (rare case)
-
-Skipping should be **rare** under the render-by-default rule above. When you do skip — only when the strict skip-permitted conditions hold — insert a one-line blockquote in the section's position (between `## Task Dependency Graph` and `## Phase 1: Critical Fixes`), in this exact shape:
-
-```
-> _Gantt Chart 생략: <concrete reason referencing the actual data>._
-```
-
-The reason MUST reference the actual data and must be one of the legitimate skip cases. Acceptable example:
-
-- `> _Gantt Chart 생략: 모든 task가 effort=XXL (세분화 필요), day 추정 산출 불가._`
-
-**NOT acceptable as skip reasons** (these mean you should render an estimate-tagged chart instead):
-- "단일 task" — render with the task's effort range as bars
-- "effort range가 넓음 (XL 5-15d)" — render mid-point or `lo`/`hi` two-bar form
-- "사용자 결정 전 확정 불가" — render with `est` annotation and a `> 일별 배분은 추정치` note
-- "Part/Phase 내부 day 배분 미정" — split the parent range across visible decomposition units
-
-This rule exists because rendering an estimated chart with a clear "estimate" tag is **always** more useful than no chart at all.
-
-### MUST — top header (verbatim 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 title suffix MUST be `— Work Schedule` (em dash, English). Korean titles like `작업 일정 계획서` are forbidden.
-
-### MUST — per-task block field set
-
-Every per-task block MUST include the `Item / Detail` table with these field rows in this order: `**Category**`, `**Priority**`, `**Effort**`, `**Status**`, `**Risk**`, `**Scope**`, `**Repo**`. None may be omitted, renamed, or translated.
-
-### MUST — per-task block sub-section order
-
-After the `Item / Detail` table, every per-task block MUST emit these sub-sections in this exact order — no insertions, no reordering, no omissions (unless the block is tagged `[NEEDS-OKSTRA-RUN]` / `[PARSE-ERROR: …]`):
-
-1. `**Problem**:`
-2. `**Solution**:`
-3. `**Work Breakdown**:` (followed by the `| Step | File | Action | Detail |` table)
-4. `**Verification Commands**:` (followed by a fenced ` ```bash ` block)
-5. `**Rollback**:`
-
-The validator enforces order by scanning each `### N-i.` block. A missing section or an out-of-order section is a contract violation. **Never emit `#### 사용자 확인 필요 항목`** — this is a client-facing schedule (see "Audience" above).
-
-### MUST — controlled vocabulary (enums)
-
-The following columns/labels accept ONLY the listed values — anywhere they appear (At a Glance table, per-task `Item / Detail` table, Execution Priority Matrix). Free-text is forbidden; if the source data is missing, leave the cell empty (`–` is also accepted by the validator only inside per-task `Item / Detail`, not in `## At a Glance`).
-
-| Field | Allowed values |
-|-------|----------------|
-| **Effort** | `S`, `M`, `L`, `XL`, `XXL` (leading token only — trailing scope hint like `L (5-15 files)` is allowed inside parens) |
-| **Priority** | `P0`, `P1`, `P2`, `P3` |
-| **Risk** | `Very Low`, `Low`, `Medium`, `Med-High`, `High` |
-| **Phase** | `1`, `2`, `3` |
-
-`Med-High` (hyphenated) is the canonical form — `Medium-High` / `중상` / `Moyen-Élevé` are all rejected.
-
-### MUST — At a Glance totals line
-
-The At a Glance section MUST contain exactly one totals line in this shape (single line, all bold):
-
-```
-**총 <N>개 task / 예상 소요: <X.X> ~ <Y.Y> days (Effort 합산)**
-```
-
-`<N>` is the included-task count, `<X.X>` and `<Y.Y>` are the lower/upper sums of the Effort-to-Day mapping. The validator checks the literal pattern.
-
-### MUST — table & list shapes (no checkboxes anywhere)
-
-The schedule is a client-facing deliverable, not an internal todo board. **No table or list may contain `[ ]` / `[x]` checkbox cells, and no `Done` / `Ready?` / `Blocking Decisions` columns are permitted.**
-
-Required shapes:
-
-- `## Execution Priority Matrix` — header `| Priority | Task | Effort | Risk | Next Action |`. No leading `Done` column, no `Ready?`, no `Blocking Decisions`.
-- `## Recommended Immediate Actions` — markdown bullet list (`- <action>`). Numbered lists and checkbox lists are both rejected.
-- `## Risk Mitigation Strategy` — numbered list (it states *strategies*, not actions to tick off).
-
-### MUST NOT — forbidden patterns
-
-| Pattern | Why forbidden |
-|---------|---------------|
-| Translating any `##` heading to Korean (`전체 개요`, `요약`, `위험 완화 전략`, `즉시 권장 액션`, etc.) or any other language | Heading literals are stable identifiers used by the validator and downstream tooling |
-| Adding sections not in the contract (`## Effort-to-Day 매핑`, `## Référentiel …`, etc. — anything beyond the 10 mandatory + the 1 optional `## Gantt Chart`) | Sizing tables belong inside `### Effort Sizing 기준` (Executive Summary). All other graphic detail belongs inside per-phase prose |
-| Translating the optional graphic section (`## Gantt 다이어그램`, `## Diagramme de Gantt`) | Use `## Gantt Chart` literally — translation is forbidden |
-| Adding `## Cumulative Timeline` (or any translated form: `## 누적 일정표`, `## Calendrier Cumulé`) | The Cumulative Timeline section has been removed from the contract — never emit it |
-| Using calendar dates / weekdays / "today + N" labels in the Gantt axis (e.g. `2026-05-04`, `Mon May 4`, `오늘 + 3일`) | The axis MUST be relative day-counts (`Day 1`, `J1`, …) — the schedule describes effort, not a wall-clock plan |
-| Using French (`Charge estimée`, `Détail`, `Catégorie`, `Priorité`, `Risque`, `Dépôt`, `Vue d'Ensemble`, `Résumé Exécutif`, etc.) anywhere in headings or field labels | Body prose is Korean, identifiers/headings/field labels are English literals. No third language anywhere structural |
-| **Mirroring the source-report language into headings** — e.g. source analyse-report is in French → headings become French; source is heavily Korean → headings become Korean | Body prose may match the source language (the SKILL allows Korean prose), but the 10 mandatory + 1 optional `##` heading literals and the 7 per-task field labels remain English ALWAYS, regardless of source-report language |
-| Translating per-task field labels (`출처`, `상세`, `위험`, `Repo별 영향` already-translated label OK only as table column header in `At a Glance` rows) | Field labels are part of the contract |
-| Emitting `## Consolidated User Decision Checklist` or `#### 사용자 확인 필요 항목` | Forbidden — schedule is a client-facing deliverable; blocking/approval/decision items belong in the internal report |
-| Adding `Done` / `Ready?` / `Blocking Decisions` columns to any table, or `[ ]` / `[x]` checkbox cells in any list | Forbidden for the same reason — see "Audience" section |
-| Replacing `Item / Detail` per-task table headers with translated versions | The literal `Item / Detail` is required |
-| Silently omitting `## Gantt Chart` without inserting the `> _Gantt Chart 생략: …_` blockquote in its position | Without the skip-reason line the reader cannot tell whether the section was forgotten, suppressed by a bug, or correctly skipped — every output must either render the chart or explicitly account for the skip |
-| Skipping `## Gantt Chart` because the data is "wide range / single task / part-day allocation pending" | Per the render-by-default rule, these are reasons to render an **estimate-tagged** chart, not to skip. Skip is only legitimate when day data literally does not exist (all-XXL or no effort sizing anywhere) |
-| Rendering Gantt as a mermaid (`` ```mermaid `` / `gantt` block) or any other graph DSL (PlantUML, Graphviz, etc.) | This skill renders ASCII only. Mermaid output is forbidden — use the ASCII Gantt format described above. Validators may reject mermaid blocks under this heading |
-
-## Known Validator Gaps (out of scope here)
-
-- The ambiguous-classification rationale required by Step 5 (`> _workCategory '<raw>' 미정의 …_` / nearest-phase rationale) is **not** currently enforced by `validators/validate-schedule.py`. The skill is responsible for emitting it; closing the validator gap requires a validator change and is tracked as a follow-up.
-
-## Self-Validation Before Reporting Completion
-
-After writing the file and before printing the completion message in Step 7, you MUST:
-
-1. **Re-read the file** you just wrote.
-2. **Run the validator**:
-   ```bash
-   python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
-   ```
-3. If the validator exits non-zero, **fix the file and re-validate**. Do not print the completion message until the validator passes.
-4. If `~/.okstra/lib/validators/validate-schedule.py` is not present, fall back to a manual checklist: confirm each of the 10 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
-
-## Schedule Document Template
-
-The installed template `~/.okstra/templates/reports/schedule.template.md` is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
-
-The two rules below complement the template — they encode COMPUTATION that the template scaffold cannot carry inline.
-
-### Effort-to-Day mapping (At a Glance total)
-
-Day-range values per size are defined once in the template's `### Effort Sizing 기준` table (`~/.okstra/templates/reports/schedule.template.md`) — that table is the SSOT. To compute the At a Glance total, read its `Day(s)` column and sum the lower bounds across all in-scope tasks for the lower total, the upper bounds for the upper total.
-
-### `[NEEDS-OKSTRA-RUN]` / `[PARSE-ERROR: <section>]` placement
-
-When a task entry is tagged with one of these markers, place the marker immediately under the per-task heading inside the corresponding Phase section and fill only the available fields. Do NOT relocate it to a sibling section.
-
 ## Edge Cases
 
 | Case | Handling |
 |------|----------|
-| `workStatus` field absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless the resolved value is `done` |
+| `workStatus` absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless resolved `done` |
 | Filtered task count is 0 | Emit "모든 task가 done" message; do NOT create a file |
-| `latestReportPath` missing or unreadable | Tag entry with `[NEEDS-OKSTRA-RUN]`; include manifest metadata only |
-| Report parsing fails for a specific section | Tag with `[PARSE-ERROR: <section>]`; continue with the rest |
-| `task-group` argument matches no tasks | Output "해당 task-group을 찾을 수 없습니다." and stop |
+| `latestReportPath` missing or unreadable | Staleness fallback, then `[NEEDS-OKSTRA-RUN]` with manifest metadata only |
+| Report parsing fails for one section | `[PARSE-ERROR: <section>]`; continue with the rest |
+| `task-group` matches no tasks | "해당 task-group을 찾을 수 없습니다." and stop |
 | Catalog and manifest disagree on `workStatus` | Manifest wins (catalog may be stale) |
-| Multiple `task-group` casings / punctuation variants | Normalise both sides (lowercase + strip non-`[a-z0-9]`) then compare against `taskGroupPathSegment` only. Use the manifest's `taskGroupPathSegment` verbatim for path output. |
+| task-group casing / punctuation variants | Normalise both sides (lowercase + strip non-`[a-z0-9]`), compare against `taskGroupPathSegment` only; use the manifest's segment verbatim for path output |
 
 ## Output Rules
 
-- All user-facing messages in Korean.
-- Schedule file body uses Korean for prose, English for technical identifiers.
+- All user-facing messages in Korean; schedule body prose Korean, identifiers/headings/field labels English (template literals).
 - Use project-relative paths in completion messages.
-- Never overwrite an existing schedule file: if the timestamped target somehow exists (collision in same second), append `-2`, `-3`, etc.
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Reading only `task-catalog.json` (stale data) | Always re-read each `task-manifest.json` directly |
-| Skipping a task because its report cannot be parsed | Tag it `[NEEDS-OKSTRA-RUN]` or `[PARSE-ERROR]` and continue |
-| Omitting the At a Glance section | This section is mandatory; place it immediately after the header |
-| Using `workStatus` for the At a Glance status column | Use `taskType` instead — it carries lifecycle phase information |
-| Creating a file when 0 tasks are included | Do not create any file in this case; just print the message |
-| Skipping the Effort-to-Day total computation | Always compute and surface `<X.X> ~ <Y.Y> days` |
-| Translating `## Risk Mitigation Strategy` → `## 위험 완화 전략` / `## Stratégie de Mitigation des Risques` (or similar) | Heading literals are part of the Section Contract — keep English |
-| Translating the optional Gantt heading (`## Gantt 다이어그램`, `## Diagramme de Gantt`) | Use `## Gantt Chart` literally |
-| Adding `## Cumulative Timeline` (or any translated form) | Removed from the contract — do not emit |
-| Inventing extra top-level sections (`## Effort-to-Day 매핑`, `## Référentiel …`) when source data is rich | Sizing tables belong in `### Effort Sizing 기준`; `## Gantt Chart` is the only allowed extra `##` section (English heading) |
-| Rendering the Gantt axis with calendar dates / today-anchored labels | Axis MUST be relative day-counts (`Day 1`, `J1`, …); never `2026-05-04` or `오늘 + 3일` |
-| Mixing French (`Charge estimée`, `Catégorie`, `Risque`, `Dépôt`) into per-task blocks | Use `**Category**`/`**Risk**`/`**Repo**` etc. — English field labels only |
-| Mirroring source-report language into headings (French source → French headings, Korean source → Korean headings) | Headings + per-task field labels are English literals regardless of source language |
-| Emitting a Consolidated User Decision Checklist or per-task 사용자 확인 필요 항목 from old templates | Forbidden — schedule is client-facing; surface those items only in internal reports |
-| Title written as `작업 일정 계획서` instead of `— Work Schedule` | The English suffix is part of the contract — fix and re-run validator |
+- Use `taskType` (not `workStatus`) for the At a Glance status column — it carries lifecycle phase information.