okstra 0.2.0 → 0.4.0

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

@@ -0,0 +1,627 @@
+---
+name: okstra-schedule
+description: Use when the user asks for a task-group work schedule, a consolidated implementation plan across multiple tasks in a task-group, or wants to generate a "schedule" / "일정" / "작업 계획표" for non-done tasks. Trigger words include "okstra schedule", "<task-group> 일정 만들어", "<task-group> schedule 생성", "task-group 작업 계획".
+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 `.project-docs/okstra/tasks/<task-group>/schedule/`.
+
+The default mode is lightweight (single Claude lead synthesis). The `--cross-verify` option triggers the full okstra multi-agent flow on the schedule itself.
+
+## 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 `.project-docs/okstra/discovery/task-catalog.json` with at least one task whose `workStatus` is not `done`
+
+**Do NOT use** for single-task analysis (use `okstra-status` instead) or when the user wants to actually execute one task (use the parent `okstra` skill).
+
+## Trigger Patterns (recognize both)
+
+**Natural language (Korean / English)**:
+- "uploadFont 작업 일정 만들어줘"
+- "uploadFont schedule 생성"
+- "uploadFont 일정 계획표"
+- "Generate schedule for uploadFont"
+
+**Explicit command**:
+- `okstra schedule <task-group>`
+- `okstra schedule <task-group> --cross-verify`
+- `okstra schedule <task-group> --title "<custom title>"`
+
+If `--title` is omitted, derive a default title from `task-group` (e.g. `uploadFont` → `uploadFont — Work Schedule`).
+
+## Step 0: Verify okstra runtime + project setup
+
+Run before anything else in this skill:
+
+```bash
+npx -y okstra@latest ensure-installed >/dev/null 2>&1 || {
+  echo "FAIL: okstra not installed; tell the user to run: npx okstra@latest install" >&2
+  exit 1
+}
+eval "$(npx -y okstra@latest paths --shell)"
+export PYTHONPATH="$OKSTRA_PYTHONPATH"
+OKSTRA_PROJECT_INFO="$(npx -y okstra@latest check-project --json)" || {
+  echo "FAIL: this project has no okstra setup. Tell the user to run /okstra-setup first." >&2
+  echo "$OKSTRA_PROJECT_INFO" >&2
+  exit 1
+}
+```
+
+`$OKSTRA_PROJECT_INFO` is JSON `{ok, projectRoot, projectJsonPath, projectId}` —
+use `projectRoot` to locate `.project-docs/okstra/discovery/task-catalog.json`
+and the task-group directory.
+
+## Process Procedure
+
+### Step 0: Verify model (HARD GATE)
+
+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.
+
+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-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5-*`).
+2. If the active model is **Opus-class** (`claude-opus-*`): 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.`
+5. Skip this gate ONLY when the harness has clearly enforced `model: opus` from the frontmatter — verifiable by the active model already being Opus-class without manual switching.
+
+### Step 1: Resolve task-group and collect tasks
+
+1. Read `.project-docs/okstra/discovery/task-catalog.json`.
+2. Filter entries where `taskGroupPathSegment == <task-group lowercased>` OR `taskGroup == <task-group>` (case-insensitive match).
+3. If no tasks found, output `해당 task-group을 찾을 수 없습니다.` and stop.
+4. For each matched task, read `.project-docs/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.
+
+### Step 2: Filter by workStatus
+
+For each task-manifest:
+- If `workStatus` field is missing or empty → treat as `in-progress` (include).
+- If `workStatus == "done"` → exclude.
+- Otherwise (`todo` / `in-progress` / `blocked`) → include.
+
+If after filtering 0 tasks remain, output:
+```
+해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.
+```
+Then 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.
+
+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.
+
+If parsing fails for a specific section:
+- Mark the entry with `[PARSE-ERROR: <section>]` and continue.
+
+### Step 4: Mode branching
+
+- **Default (lightweight)**: Claude lead synthesizes the schedule directly using collected data. Proceed to Step 5.
+- **`--cross-verify`**: Invoke the parent `okstra` skill flow with the schedule synthesis itself as the analysis target. The schedule generation becomes the cross-verified deliverable.
+
+### Step 5: Phase classification heuristic
+
+Classify each task into one of three phases based on report data:
+
+- **Phase 1 (안정성/Critical)**: priority `P0`, OR `workCategory == "bugfix"` with high risk
+- **Phase 2 (개선/기능)**: priority `P1` or `P2`, `workCategory in {"improvement", "feature"}`
+- **Phase 3 (확장/아키텍처)**: priority `P3`, OR multi-repo + infrastructure scope
+
+When the classification is ambiguous, place the task in the closest phase and add a one-line rationale at the top of that phase section.
+
+### Step 6: Write the schedule file
+
+Output path:
+```
+.project-docs/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.
+
+### Step 7: Completion message (Korean)
+
+After writing the file, reply briefly:
+
+```
+✓ Schedule 생성 완료: <relative-path>
+- 포함 task: N개
+- 제외(done) task: M개
+- 예상 소요: X.X ~ Y.Y days (Effort 합산)
+- 모드: lightweight | cross-verify
+```
+
+## 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 (HARD RULE — 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 hard-rejects any of these patterns.
+
+## Section Contract (HARD RULES — non-negotiable)
+
+The canonical template lives at `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 `instruction-set/analysis-material.md` for a `## Directive` section** (sourced from the `--directive` CLI flag). If that section is present and expresses any directive 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.
+
+`## Gantt Chart` is the only `##` section that MAY be added beyond the 11 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 hard 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 11 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 |
+
+## 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 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 `validators/validate-schedule.py` is not present in the repo, fall back to a manual checklist: confirm each of the 11 mandatory headings appears in the file with the exact spelling above, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
+
+## Schedule Document Template
+
+The generated Markdown file MUST follow this structure exactly, mirroring `templates/reports/schedule.template.md`. Do not omit sections; if data is unavailable for a section, include the section with the placeholder `_없음_` rather than skipping it.
+
+### Required Top Header
+
+```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)
+
+---
+```
+
+### Section: At a Glance (FIRST content section after header)
+
+This section gives the reader the entire schedule scope at a single screen.
+
+```markdown
+## At a Glance
+
+**총 <N>개 task / 예상 소요: <X.X> ~ <Y.Y> days (Effort 합산)**
+
+| # | Task ID | Title | Category | Priority | Effort | Days | taskType | Risk | Phase |
+|---|---------|-------|----------|----------|--------|------|----------|------|-------|
+| 1 | <TASK-ID> | <Title> | <category> | <P0~P3> | <S/M/L/XL> | <range> | <taskType> | <risk> | <1/2/3> |
+| ... |
+
+**Effort 분포**: S × <n> / M × <n> / L × <n> / XL × <n>
+**Risk 분포**: Very Low × <n> / Low × <n> / Medium × <n> / Med-High × <n> / High × <n>
+**Repo별 영향**: <repo1> (<n>) / <repo2> (<n>) / ...
+
+---
+```
+
+Effort-to-Day mapping (used to compute the total day range):
+
+| Size | Day(s)   |
+|------|----------|
+| S    | 0.5 - 1  |
+| M    | 2 - 3    |
+| L    | 3 - 5    |
+| XL   | 5 - 10   |
+| XXL  | 10 -     |
+Sum the lower bounds for the lower total and the upper bounds for the upper total.
+
+### Section: Executive Summary
+
+```markdown
+## Executive Summary
+
+<Phase 분류 요약 + 진행 전략 — 2~4문장>
+
+- **Phase 1 (Critical Fixes)**: <n>개 task — <summary>
+- **Phase 2 (Enhancements)**: <n>개 task — <summary>
+- **Phase 3 (Architecture)**: <n>개 task — <summary>
+
+### Effort Sizing 기준
+
+| Size | 기준 | Day(s) |
+|------|------|--------|
+| **S** | 1-2 files, 1 repo, 테스트 수정만, DB 변경 없음 | 0.5 - 1 |
+| **M** | 3-5 files, 1 repo, 신규 테스트 포함, DB 변경 없음 | 2 - 3 |
+| **L** | 5-15 files, 2-3 repos, 순차 배포, 패키지 릴리스 포함 가능 | 3 - 5 |
+| **XL** | 15+ files, 3+ repos + infra, frontend 동시 변경, 아키텍처 전환 | 5 - 10 |
+| **XXL** | 작업 더 세분화 필요 | 10 - |
+
+---
+```
+
+### Section: Task Dependency Graph
+
+This section MUST follow ONE of two exact shapes — free-form ASCII art, mermaid, PlantUML, or Graphviz are all forbidden.
+
+**Shape A — no dependency data.** Single italicized blockquote-line under the heading, literal Korean:
+
+```
+_의존 정보 없음_
+```
+
+**Shape B — adjacency-list inside a plain fence.** When dependency edges are extracted from per-task reports, emit them as a fenced block with NO language tag. Each non-empty line is one of:
+
+- An adjacency line: `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*`
+- A comment line starting with `#` (free prose, max one per group)
+- A blank line (group separator)
+
+```
+DEV-1 -> DEV-2, DEV-3
+DEV-2 -> DEV-4
+# Phase 3 fan-out
+DEV-5 -> DEV-6
+```
+
+Rules:
+- Use ASCII arrow `->` only. Unicode `→` is rejected so downstream tooling does not have to handle both.
+- Both endpoints MUST be `TASK-ID` literals (the same identifiers used in the At a Glance table). Free text is forbidden.
+- Fence MUST be plain ` ``` ` with no language tag. ` ```mermaid `, ` ```plantuml `, ` ```graphviz `, ` ```dot ` are all rejected.
+- If only one task is in scope (no dependencies), use Shape A — do NOT emit an empty fence.
+
+### Section: Phase 1 / Phase 2 / Phase 3
+
+For each phase, repeat the per-task block:
+
+````markdown
+## Phase <N>: <Name>
+
+### <N>-<i>. <TASK-ID> — <Title>
+
+| Item | Detail |
+|------|--------|
+| **Category** | <category> |
+| **Priority** | <P0~P3> |
+| **Effort** | **<S/M/L/XL>** (<scope summary>) |
+| **Status** | <workStatus + currentPhase summary> |
+| **Risk** | <risk> |
+| **Scope** | <files / repos summary> |
+| **Repo** | <repos> |
+
+**Problem**: <…>
+
+**Solution**: <…>
+
+**Work Breakdown**:
+
+| Step | File | Action | Detail |
+|------|------|--------|--------|
+| 1 | <path> | CREATE/MODIFY/VERIFY | <detail> |
+| ... |
+
+**Verification Commands**:
+```bash
+<commands>
+```
+
+**Rollback**: <…>
+
+---
+````
+
+If a task entry is `[NEEDS-OKSTRA-RUN]` or `[PARSE-ERROR: <section>]`, place the marker immediately under the task heading and fill only the available fields.
+
+### Section: Execution Priority Matrix
+
+```markdown
+## Execution Priority Matrix
+
+| Priority | Task | Effort | Risk | Next Action |
+|----------|------|--------|------|-------------|
+```
+
+Each row summarizes the next concrete engineering action per task in priority order. No `Done` / `Ready?` / `Blocking Decisions` columns — schedule is a client-facing plan, not an internal todo board.
+
+### Section: Cross-Task Dependencies & Shared Concerns
+
+Free-form prose listing inter-task overlaps, shared packages, release order, etc.
+
+### Section: Risk Mitigation Strategy
+
+Enumerate phase-level risk strategies as numbered list.
+
+### Section: Recommended Immediate Actions
+
+Markdown bullet list of next concrete engineering actions, one item per line: `- <action>`. Numbered lists (`1. …`) and checkbox lists (`- [ ] …`) are both forbidden — the schedule is a client-facing plan, not an internal todo.
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| `workStatus` field absent or empty | Treat as `in-progress` → include in schedule |
+| 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 |
+| Catalog and manifest disagree on `workStatus` | Manifest wins (catalog may be stale) |
+| Multiple `task-group` casings | Match case-insensitively; use the manifest's `taskGroupPathSegment` for path output |
+
+## Output Rules
+
+- All user-facing messages in Korean.
+- Schedule file body uses Korean for prose, English for technical identifiers.
+- 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 |