okstra 0.1.0

package/runtime/templates/reports/schedule.template.md

@@ -0,0 +1,168 @@
+# <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)
+
+---
+
+## 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>)
+
+---
+
+## Executive Summary
+
+<2~4 문장 — Phase 분류 요약 + 진행 전략>
+
+- **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 - |
+
+---
+
+## Task Dependency Graph
+
+<!-- Use ONE of:
+     (A) literal `_의존 정보 없음_` when no edges exist;
+     (B) plain ``` fenced adjacency-list block — see SKILL §"Section: Task Dependency Graph".
+     Example (B):
+     ```
+     DEV-1 -> DEV-2, DEV-3
+     DEV-2 -> DEV-4
+     ```
+     Mermaid / PlantUML / Graphviz / Unicode '→' are all forbidden. -->
+_의존 정보 없음_
+
+---
+
+## Gantt Chart
+
+<!-- OPTIONAL: include only when per-task day estimates are available.
+     If included, MUST use this exact heading literal `## Gantt Chart`.
+     Render as ASCII inside a fenced ``` block with NO language tag.
+     Mermaid / PlantUML / Graphviz are forbidden — see SKILL §"ASCII Gantt format".
+     The axis is RELATIVE DAY-COUNTS (Day 1 / J1, …) — never calendar dates. -->
+
+```
+Day:            1    5    10   15   20   25   30
+                |    |    |    |    |    |    |
+Phase 1
+  <TASK-ID> (<size>)           ██████          ! crit
+  <TASK-ID> (<size>)                 ████████
+Phase 2
+  <TASK-ID> (<size>)                         ██████░░  est
+Phase 3
+  <TASK-ID> (<size>)                                  ████  (after <TASK-ID>)
+```
+
+> 가로축은 **상대 일수** (Day 1 시작 = Phase 1 시작). 오늘 날짜·요일·달력일자 사용 금지.
+> 임계 경로(critical path) 항목은 `! crit` 주석, 추정 배분은 `est` 주석으로 표기.
+> 막대는 `█`(확정) + `░`(상한/불확실) 조합. 단일 mid-point bar 도 허용.
+> 데이터가 없어 이 섹션을 생략할 때는, `## Gantt Chart` 헤딩과 ASCII 블록 전체를
+> 다음 한 줄 blockquote로 대체한다 (SKILL §"MUST — emit a skip-reason note" 참조):
+> `> _Gantt Chart 생략: <구체 사유 — 예: "단일 task (DEV-9187) + XL effort 5–15d 범위로 정밀 day 추정 부재."_`
+
+---
+
+## Phase 1: Critical Fixes
+
+### 1-1. <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**: <…>
+
+---
+
+## Phase 2: Enhancements
+
+_없음_ <!-- or repeat per-task block -->
+
+---
+
+## Phase 3: Architecture
+
+_없음_ <!-- or repeat per-task block -->
+
+---
+
+## Execution Priority Matrix
+
+| Priority | Task | Effort | Risk | Next Action |
+|----------|------|--------|------|-------------|
+
+---
+
+## Cross-Task Dependencies & Shared Concerns
+
+<free-form prose — inter-task overlap, shared packages, release order>
+
+---
+
+## Risk Mitigation Strategy
+
+1. <…>
+2. <…>
+
+---
+
+## Recommended Immediate Actions
+
+- <action>
+- <action>
+
+<!-- OPTIONAL: ## Glossary
+     Include ONLY when the body uses opaque codes (FC-N, UC-N, M-N, ...).
+     Header literal `| Code | Description |` is required. Every code in body
+     MUST have a row. Decision-item letters (A1, B2, C3, D4) are forbidden
+     even with a glossary entry — they belong only in internal reports.
+
+## Glossary
+
+| Code | Description |
+|------|-------------|
+| FC-5 | 결제 게이트웨이 타임아웃 처리 누락 |
+-->
+

package/runtime/templates/reports/settings.template.json

@@ -0,0 +1,101 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "LS",
+      "NotebookRead",
+      "NotebookEdit",
+      "Edit",
+      "Write",
+      "WebFetch",
+      "WebSearch",
+      "TodoWrite",
+      "Bash(git:*)",
+      "Bash(gh:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(jq:*)",
+      "Bash(yq:*)",
+      "Bash(rg:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(rm:*)",
+      "Bash(diff:*)",
+      "Bash(awk:*)",
+      "Bash(sed:*)",
+      "Bash(tr:*)",
+      "Bash(sort:*)",
+      "Bash(uniq:*)",
+      "Bash(xargs:*)",
+      "Bash(python3:*)",
+      "Bash(python:*)",
+      "Bash(pip3:*)",
+      "Bash(pip:*)",
+      "Bash(uv:*)",
+      "Bash(poetry:*)",
+      "Bash(pytest:*)",
+      "Bash(bash:*)",
+      "Bash(sh:*)",
+      "Bash(printf:*)",
+      "Bash(echo:*)",
+      "Bash(export:*)",
+      "Bash(env:*)",
+      "Bash(test:*)",
+      "Bash(true:*)",
+      "Bash(false:*)",
+      "Bash(true)",
+      "Bash(false)",
+      "Bash(codex:*)",
+      "Bash(codex exec:*)",
+      "Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)",
+      "Bash(gemini:*)",
+      "Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)",
+      "Bash(claude:*)",
+      "Bash(chmod:*)",
+      "Bash(node:*)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(pnpm:*)",
+      "Bash(yarn:*)",
+      "Bash(tsc:*)",
+      "Bash(go:*)",
+      "Bash(cargo:*)",
+      "Bash(rustc:*)",
+      "Bash(java:*)",
+      "Bash(javac:*)",
+      "Bash(mvn:*)",
+      "Bash(gradle:*)",
+      "Bash(./gradlew:*)",
+      "Bash(make:*)",
+      "Bash(docker:*)",
+      "Bash(docker compose:*)",
+      "Bash(docker-compose:*)",
+      "Bash(kubectl:*)",
+      "Bash(helm:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "mcp__test-context7__resolve-library-id",
+      "mcp__test-context7__query-docs",
+      "mcp__mysql-fontsninja-common__mysql_list_tables",
+      "mcp__mysql-fontsninja-common__mysql_describe_table",
+      "mcp__mysql-fontsninja-common__mysql_select_data",
+      "mcp__mysql-fontsninja-fontradar__mysql_list_tables",
+      "mcp__mysql-fontsninja-fontradar__mysql_describe_table",
+      "mcp__mysql-fontsninja-fontradar__mysql_select_data",
+      "mcp__mysql-fontsninja-fontsninja__mysql_list_tables",
+      "mcp__mysql-fontsninja-fontsninja__mysql_describe_table",
+      "mcp__mysql-fontsninja-fontsninja__mysql_select_data",
+      "mcp__mysql-fontsninja-fonthelper__mysql_list_tables",
+      "mcp__mysql-fontsninja-fonthelper__mysql_describe_table",
+      "mcp__mysql-fontsninja-fonthelper__mysql_select_data"
+    ]
+  }
+}

package/runtime/templates/reports/task-brief.template.md

@@ -0,0 +1,165 @@
+# OKSTRA Task Brief
+
+## Identity
+
+- Brief Title:
+- Project ID:
+- Task Group:
+- Task ID:
+- Task Key: `<project-id>:<task-group>:<task-id>`
+- Related Tasks:
+- Issue / Ticket:
+- Task Type:
+- Requested Outcome:
+- Owner:
+
+## Request Summary
+
+- What is being requested or changed?
+- Why is this work being started now?
+- Is this a new task, a continuation, or a reopened task?
+- What decision should this run help make?
+
+## Current Context
+
+- Current behavior or state:
+- Desired behavior or outcome:
+- Existing related implementation:
+- Related code paths:
+- Existing documents, tickets, or prior reports:
+
+## Evidence and Source Materials
+
+- Primary problem statement:
+- Existing analysis or notes:
+- Related raw samples or logs:
+- Screenshots or reports:
+- Previous reports in the same task history:
+
+## Task-Type Focus
+
+- If `Task Type` is `requirements-discovery`:
+  - What classification or routing uncertainty must be resolved?
+  - Why might this be a bugfix, feature, refactor, or ops task?
+  - What evidence still blocks confident phase selection?
+- If `Task Type` is `error-analysis`:
+  - What is the visible symptom?
+  - What are the expected vs actual results?
+  - What are the current hypotheses and missing evidence?
+- If `Task Type` is `implementation-planning`:
+  - What implementation options are under consideration?
+  - What trade-offs, dependencies, or migrations matter?
+  - What validation and rollback approach is expected?
+- If `Task Type` is `implementation`:
+  - Which approved `implementation-planning` final report authorises this run, and where is the explicit user-approval marker quoted?
+  - What is the authoritative file list and step order copied from that plan?
+  - Which validation, TDD, and rollback commands must be executed and recorded with actual output?
+- If `Task Type` is `final-verification`:
+  - What was delivered?
+  - What acceptance criteria must pass?
+  - What residual risks or blockers remain?
+
+## Constraints and Risks
+
+- Business constraints:
+- Technical constraints:
+- Delivery constraints:
+- Approval or review checkpoints:
+- Known risks:
+- Things that are still uncertain:
+
+## Out of Scope
+
+- Adjacent areas deliberately excluded from this run:
+- Items that look related but must be handled in a separate task:
+- Reason for exclusion (deadline, risk, separate owner, distinct decision):
+
+> Workers MUST NOT expand into items listed here. If a worker believes an excluded item must be addressed to satisfy the requirement, the worker records it as a recommended follow-up task in the final report and stops — it does not silently include the work. If this section is left empty, workers treat any change beyond what `Request Summary` and `Current Context` explicitly demand as out of scope by default.
+
+## Configuration References and Expected Values
+
+- Which config files matter for this task?
+- Which current or observed values should be checked?
+- Which expected values or invariants must hold for this task?
+- Which values are still uncertain and must be confirmed?
+
+## Deployment Manifests and Expected Values
+
+- Which deployment manifests matter for this task?
+- Which expected image / env / resource / routing values must hold?
+- Which rollout or deployment invariants must be preserved?
+- Which deployment-side values are still uncertain and must be confirmed?
+
+## Questions for Workers
+
+1.
+2.
+3.
+
+### Standing Scope-Discipline Questions (always answered by every worker)
+
+- Which adjacent changes did you consider and **deliberately exclude** from this run? List each with a one-line reason.
+- Did any part of your output go beyond what `Request Summary` and `Out of Scope` define for this run? If yes, move it to a `Recommended Follow-up Tasks` section and remove it from the main answer.
+
+## Expected Outputs
+
+- Root cause candidates / plan options / final blockers:
+- Missing information:
+- Risks:
+- Recommended next actions:
+
+## Task Continuity Notes
+
+- Should the same task key continue to be used after this run?
+- What is the likely work category for this task right now?
+- Which lifecycle phase should probably happen next after this run?
+- What prior decision or report should Claude compare against?
+- What related tasks should Claude keep in mind but not merge with this task?
+- Which config files and deployment manifests carry the expected state for this task?
+
+## Phase Boundary
+
+- This okstra run executes the lifecycle phase named in `Task Type` and stops there. Outputs that belong to any other phase MUST NOT be produced inside this run.
+- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`agents/SKILL.md`). The lead and every worker stay inside that boundary.
+- "다음 단계 진행해" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
+- For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
+- For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or has no explicit user-approval marker. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
+
+## Available MCP Servers
+
+The following MCP servers are registered at the user scope and may be invoked **as needed** during this run by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding this section verbatim into the worker prompts (Phase 2) so workers know they are allowed to call these tools.
+
+| Server | Backing data | Mode | Typical use |
+|--------|--------------|------|-------------|
+| `mcp__mysql-fontsninja-common` | local Docker MySQL `common` schema | read-only | shared lookups, code list, reference data |
+| `mcp__mysql-fontsninja-fontradar` | local Docker MySQL `fontradar` schema | read-only | fontradar service data inspection |
+| `mcp__mysql-fontsninja-fontsninja` | local Docker MySQL `fontsninja` schema | read-only | fontsninja service data inspection |
+| `mcp__mysql-fontsninja-fonthelper` | local Docker MySQL `fonthelper` schema | read-only | fonthelper service data inspection |
+
+Available tools per server (all read-only — write tools are disabled at the server):
+
+- `mysql_list_tables`
+- `mysql_describe_table`
+- `mysql_select_data`
+
+How to invoke (worker-by-worker):
+
+- **Claude lead / Claude worker / Report writer worker**: invoke the MCP tool **directly by its tool name** (e.g. `mcp__mysql-fontsninja-fontsninja__mysql_list_tables`) through the host's tool interface. **Do NOT call it via `Bash`** — these names are MCP tools, not shell commands; running them in a shell will always fail with `command not found` regardless of permission settings.
+- **Codex worker / Gemini worker**: invoke through the external CLI's own MCP transport (e.g. `codex mcp call <server> <tool> <args>` for Codex CLI; the equivalent Gemini CLI MCP invocation for Gemini). If the worker's CLI has no matching MCP config, treat the server as unavailable for this run and record `MCP not available in this CLI` in `Missing Information or Assumptions` — do **not** attempt a shell fallback such as `mysql -h ...` or piping a tool name into `bash`.
+- All workers: cite the exact server, tool, and SELECT (or `WHERE` filters) used in the result file. Tool-call failures must be logged in the worker's `*-errors.json` (commandKind `mcp_call`) so the lead can decide whether to retry under a different worker.
+
+Usage policy:
+
+- **Allowed phases**: `requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`. Use only when local schema/data evidence improves the answer. Always cite the server, table, and the SELECT used as evidence in worker output.
+- **`implementation` phase**: read-only MCP queries are permitted as cross-checks; MCP MUST NOT be used as a write path even if a write tool becomes available — schema/data mutations belong in the codebase migration files reviewed by humans.
+- **External CLI workers (Codex, Gemini)**: can use these MCP servers ONLY if their CLI's own MCP configuration is set up to mirror the same servers. If not configured, the worker should record `MCP not available in this CLI` in `Missing Information or Assumptions` rather than guessing.
+- **Forbidden**: connecting to non-listed databases, running anything that mutates state (server is read-only — flagged write attempts are a contract violation), persisting query results outside the run's own artifact directories.
+- **Limits**: `maxRows: 1000` per query (server-enforced). For larger scans, page via `WHERE` predicates and document the strategy.
+
+If MCP evidence contradicts a claim sourced from documentation, code, or prior reports, flag the conflict explicitly in the final report and prefer the live MCP evidence unless the brief says otherwise.
+
+## Notes for Main Claude
+
+- Which workers should be used?
+- Should all workers receive the same brief or different emphasis?
+- What should the final synthesis optimize for?

package/runtime/validators/lib/common.sh

@@ -0,0 +1,44 @@
+# shellcheck shell=bash
+
+step() {
+  printf '\n[STEP] %s\n' "$1"
+}
+
+pass() {
+  printf '[PASS] %s\n' "$1"
+}
+
+fail() {
+  printf '[FAIL] %s\n' "$1" >&2
+  exit 1
+}
+
+on_error() {
+  fail "Unexpected error at line $1"
+}
+
+require_file() {
+  local target_path="$1"
+
+  if [[ ! -f "$target_path" ]]; then
+    fail "Expected file not found: $target_path"
+  fi
+}
+
+assert_contains() {
+  local target_path="$1"
+  local expected_text="$2"
+
+  if ! grep -F -- "$expected_text" "$target_path" >/dev/null 2>&1; then
+    fail "Expected to find [$expected_text] in $target_path"
+  fi
+}
+
+assert_not_contains() {
+  local target_path="$1"
+  local unexpected_text="$2"
+
+  if grep -F -- "$unexpected_text" "$target_path" >/dev/null 2>&1; then
+    fail "Did not expect to find [$unexpected_text] in $target_path"
+  fi
+}