okstra 0.122.0 → 0.124.0

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

@@ -1,320 +0,0 @@
-# okstra-schedule AI Manual
-
-## 원천
-
-- 스킬 원문: [`skills/okstra-schedule/SKILL.md`](../../../skills/okstra-schedule/SKILL.md)
-- schedule 템플릿: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
-- schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
-- workStatus inference 참조: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
-
-## 목적
-
-`okstra-schedule`은 task-group 안의 non-done task들을 모아 클라이언트용 작업 일정 Markdown을 만든다. 실행 task를 시작하는 스킬이 아니며, 단일 task 분석도 아니다.
-
-출력 위치:
-
-```text
-<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
-```
-
-## 사용 조건
-
-사용한다:
-
-- 사용자가 task-group 전체의 "일정", "schedule", "작업 계획표"를 요청한다.
-- `.okstra/discovery/task-catalog.json`에 해당 task-group이 있고, `done`이 아닌 task가 하나 이상 있다.
-
-사용하지 않는다:
-
-- 단일 task 상태/분석: `okstra-inspect status`
-- 실제 phase 실행: `okstra-run`
-- 이미 완료된 task-group: 파일을 만들지 않고 모든 task가 done이라고 말한다.
-
-## Preflight
-
-단일 Bash 호출:
-
-```bash
-okstra preflight --runtime claude-code --json
-```
-
-runtime이나 project setup이 없으면 `/okstra-setup` 안내 후 멈춘다.
-
-## task-group 해석
-
-1. `.okstra/discovery/task-catalog.json`을 읽는다.
-2. 사용자 입력 task-group을 lowercase하고 `[a-z0-9]` 외 문자를 제거한다.
-3. catalog entry의 `taskGroupPathSegment`에도 같은 변환을 적용해 비교한다.
-4. raw `taskGroup` fallback은 쓰지 않는다.
-5. 매칭된 각 task의 `task-manifest.json`을 직접 읽는다. catalog는 stale일 수 있고 manifest가 authoritative다.
-
-0개 매칭이면 `해당 task-group을 찾을 수 없습니다.`를 출력하고 멈춘다.
-
-## workStatus filter
-
-각 manifest에서 workStatus를 확인한다. 없거나 비어 있으면 `okstra-inspect`의 `status.4` inference table을 적용한다.
-
-제외:
-
-- explicit `done`
-- inferred `done`
-
-포함:
-
-- `todo`
-- `in-progress`
-- `blocked`
-- `phase-done`
-- 그 밖의 non-done inferred/display 상태
-
-필터 후 0개면 schedule file을 만들지 않고 `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.`를 출력한다.
-
-## per-task data extraction
-
-manifest에서 읽는다:
-
-- `taskId`, `taskGroup`, `taskKey`
-- `workCategory`
-- `workflow.currentPhase`
-- `workflow.currentPhaseState`
-- `taskType`
-- `workStatus`
-- `latestReportPath`
-
-report에서 파싱한다:
-
-- Title / Problem statement
-- Solution / Architecture
-- Work Breakdown
-- Verification Commands
-- Rollback strategy
-- Effort, Risk, Priority, Scope, Repos
-
-report가 없거나 manifest pointer가 stale이면 fallback:
-
-1. `taskRootPath`를 기준으로 `runs/<taskType>/reports/final-report-*.md`에서 mtime이 최신인 파일을 찾는다.
-2. 없으면 `runs/*/reports/final-report-*.md`도 본다.
-3. 찾으면 parse하고 schedule task block에 fallback note를 넣는다.
-4. 끝까지 없으면 `[NEEDS-OKSTRA-RUN]`으로 표시하고 manifest metadata만 사용한다.
-
-특정 section parse 실패는 `[PARSE-ERROR: <section>]`으로 표시하고 계속한다.
-
-## client-facing audience rule
-
-schedule은 클라이언트용 작업 계획이다. 내부 report의 approval, blocking decision, 사용자 확인 필요 항목을 schedule에 노출하지 않는다.
-
-출력에서 제거한다:
-
-- permission/authority 확인 step
-- approval waiting buffer
-- stakeholder coordination
-- 법무/조직 sign-off
-- `Consolidated User Decision Checklist`
-- `#### 사용자 확인 필요 항목`
-- `Done`, `Ready?`, `Blocking Decisions` column
-- checkbox list/cell
-
-effort와 Gantt는 engineering duration만 반영한다.
-
-## phase classification
-
-기본 mapping:
-
-| workCategory | phase |
-|---|---|
-| `bugfix` | High/Med-High risk이면 Phase 1, 아니면 Phase 2 |
-| `feature` | Phase 2 |
-| `improvement` | Phase 2 |
-| `refactor` | Phase 3 |
-| `ops` | Phase 3 |
-| `docs` / `doc` | Phase 2 |
-| `unknown` 또는 미정의 | Phase 2, rationale note 추가 |
-
-priority override:
-
-- `P0`: Phase 1
-- `P1`, `P2`: Phase 2
-- `P3`: Phase 3
-
-ambiguous하면 가장 가까운 phase에 두고 rationale을 phase section 상단에 쓴다. 이 rationale은 현재 validator gap으로 문서에서 책임진다.
-
-## section contract
-
-템플릿의 heading 순서와 spelling을 따른다. `validate-schedule.py`가 section order, title suffix, metadata, field labels, enum, Gantt axis 등을 검사한다.
-
-top-level 계약 sections:
-
-1. `## At a Glance`
-2. `## Executive Summary` (필수 subsection `### Effort Sizing 기준` 포함 — `validate-schedule.py`가 검사)
-3. `## Task Dependency Graph`
-4. `## Phase 1: Critical Fixes`
-5. `## Phase 2: Enhancements`
-6. `## Phase 3: Architecture`
-7. `## Execution Priority Matrix`
-8. `## Cross-Task Dependencies & Shared Concerns`
-9. `## Risk Mitigation Strategy`
-10. `## Recommended Immediate Actions`
-
-optional sections:
-
-- `## Gantt Chart`: `Task Dependency Graph`와 `Phase 1` 사이.
-- `## Glossary`: 마지막 section. opaque code가 본문에 남을 때만 사용.
-
-phase에 task가 없어도 heading을 유지하고 `_없음_`을 쓴다.
-
-## 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)
-```
-
-title suffix `— Work Schedule`은 validator가 검사한다. `<project-id>`는 `task-catalog.json` 최상위 `projectId`를 우선 쓰고, 없으면 첫 매칭 manifest의 `projectId`를 쓴다. 임의 값 생성 금지.
-
-## At a Glance
-
-다음 totals line이 정확히 있어야 한다.
-
-```markdown
-**총 <N>개 task / 예상 소요: <X.X> ~ <Y.Y> days (Effort 합산)**
-```
-
-Effort-to-day mapping은 template의 `### Effort Sizing 기준` table이 SSOT다. lower/upper 합산으로 total day range를 만든다.
-
-enum 값:
-
-| Field | 값 |
-|---|---|
-| Effort | `S`, `M`, `L`, `XL`, `XXL` |
-| Priority | `P0`, `P1`, `P2`, `P3` |
-| Risk | `Very Low`, `Low`, `Medium`, `Med-High`, `High` |
-| Phase | `1`, `2`, `3` |
-
-`Med-High`가 canonical이다.
-
-## per-task block
-
-모든 task block은 `| Item | Detail |` table을 가진다. field row 순서:
-
-1. `**Category**`
-2. `**Priority**`
-3. `**Effort**`
-4. `**Status**`
-5. `**Risk**`
-6. `**Scope**`
-7. `**Repo**`
-
-그 뒤 subsection 순서:
-
-1. `**Problem**:`
-2. `**Solution**:`
-3. `**Work Breakdown**:` — 뒤에 `| Step | File | Action | Detail |` table
-4. `**Verification Commands**:` — 뒤에 ` ```bash ` fenced block
-5. `**Rollback**:`
-
-`[NEEDS-OKSTRA-RUN]` 또는 `[PARSE-ERROR: <section>]` task는 가능한 field만 채우되 marker를 task heading 바로 아래 둔다.
-
-## Task Dependency Graph
-
-dependency가 없으면 literal:
-
-```markdown
-_의존 정보 없음_
-```
-
-dependency가 있으면 plain fenced block을 사용한다. language tag를 붙이지 않는다.
-
-````
-```
-DEV-1 -> DEV-2, DEV-3
-DEV-2 -> DEV-4
-```
-````
-
-arrow는 ASCII `->`만 사용한다.
-
-## Gantt Chart
-
-**directive override (최우선):** 아래 휴리스틱 적용 전 directive source의 `## Directive` section을 먼저 확인한다. 해석 순서(first hit): (1) `--directive-file <abs-path>` 인자, (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`, (3) 없으면 휴리스틱 그대로(정상 경로 — 경고·중단 없음). directive가 Gantt 렌더/생략을 지시하면 휴리스틱·skip 규칙을 덮어쓰고, 해당 section에 `> _Per Directive directive: <verbatim 발췌>._` 한 줄을 남긴다. directive가 day allocation·phase weight·sub-task 분해를 주면 bar 길이에 verbatim 반영한다.
-
-기본은 렌더한다. day signal이 하나라도 있으면 rough estimate라도 chart를 만든다.
-
-렌더 조건 예:
-
-- 2개 이상 task에 effort sizing이 있다.
-- 1개 task라도 effort range가 있다.
-- source report에 Part/Phase/Step decomposition이 있다.
-- total effort가 3 days 이상이다.
-
-skip은 모든 task가 XXL이고 decomposition이 없거나, 모든 task에 effort와 decomposition이 없을 때만 한다. skip하면 `Gantt Chart` 위치에 다음 blockquote를 둔다.
-
-```markdown
-> _Gantt Chart 생략: <actual data를 근거로 한 이유>._
-```
-
-Gantt는 plain fenced ASCII다. Mermaid, PlantUML, Graphviz, date axis를 쓰지 않는다.
-
-````
-```
-Day:            1    5    10   15   20
-                |    |    |    |    |
-Phase 1
-  DEV-1 (M)          ██████          ! crit
-Phase 2
-  DEV-2 (L)                ██████░░  est
-```
-````
-
-axis는 relative day count만 사용한다. calendar date, weekday, "오늘 + N"을 넣지 않는다.
-
-## opaque code 처리
-
-내부 report code(`FC-5`, `UC-3`, `M2` 등)는 그대로 노출하지 않는다.
-
-선택 A: 짧은 설명으로 inline replacement.
-
-선택 B: 반복되는 code가 많으면 마지막 `## Glossary`에 모든 code를 해석한다. glossary table header는 정확히 `| Code | Description |`(영문 literal — validator가 검사). milestone code(`M1`, `M2` …)도 `FC-N`과 동일하게 glossary 미해석 시 validator fail.
-
-decision-item letter code(`A1`, `B2`, `C3`, `D4`)는 schedule에 넣지 않는다.
-
-## validation
-
-작성 후 완료 메시지 전에 다시 읽고 validator를 실행한다.
-
-```bash
-python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
-```
-
-설치본 validator가 없으면 repo validator를 쓴다.
-
-```bash
-python3 validators/validate-schedule.py <output-path>
-```
-
-실패하면 파일을 고치고 재검증한다. validator가 없을 때만 manual checklist로 대체한다.
-
-## 완료 메시지
-
-```text
-Schedule 생성 완료: <relative-path>
-- 포함 task: N개
-- 제외(done) task: M개
-- 예상 소요: X.X ~ Y.Y days (Effort 합산)
-- 모드: lightweight
-```
-
-## 금지 패턴
-
-- heading을 한국어/프랑스어 등으로 번역하기.
-- `## Cumulative Timeline` 추가.
-- `## Effort-to-Day 매핑` 같은 extra top-level section 추가.
-- Gantt를 mermaid로 렌더하기.
-- Gantt axis에 calendar date를 넣기.
-- checkbox, Done, Ready, Blocking Decisions column 만들기.
-- internal approval/blocker/user-decision 항목을 클라이언트 schedule에 노출하기.
-- report가 없다고 task를 제외하기. `[NEEDS-OKSTRA-RUN]`으로 포함한다.
-- timestamp collision 시 기존 파일을 덮어쓰기. `-2`, `-3` suffix를 붙인다.