pi-maestro-flow 0.2.0

package/skills/maestro-update/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: maestro-update
+description: "Detect version, preview changes, apply workflow upgrades Arguments: [--dry-run] [--force] [--setup-only]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Detect current version, run schema migration to latest, then follow the version-specific upgrade workflow.
+Schema migrations are handled by `maestro update --migrate`; workflow docs (`~/.maestro/workflows/updates/`) handle setup.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--dry-run` -- Preview migration plan without executing
+- `--force` -- Skip confirmation prompts (intended for CI/automated contexts). Migration diff is still displayed even with `--force` to maintain audit visibility.
+- `--setup-only` -- Skip schema migration, run only the setup for current version
+
+**Version source:** `.workflow/state.json` → `version` field
+
+**Workflow docs:** `~/.maestro/workflows/updates/`
+- `update-v{TO}-setup.md` — post-migration setup for version {TO}
+
+**Schema registry:** `maestro update --migrate` — handles all intermediate version bumps automatically
+
+**Output boundary**: ALL file writes MUST target `.workflow/state.json` (version bump), `.workflow/state.json.backup-*` (backup), and `.workflow/` config files touched by version-specific setup. NEVER modify source code or `src/migrations/` files.
+</context>
+
+<invariants>
+1. **Backup before migration** — a timestamped backup of `.workflow/state.json` MUST be created before any schema migration runs; NEVER execute migration without backup
+2. **Idempotent** — running update when already on latest version MUST be a no-op (display "up to date"); NEVER re-apply migrations
+3. **Confirmation before execute** — migration diff MUST be displayed and user MUST confirm via AskUserQuestion before execution (unless `--force`); NEVER silently apply schema changes
+4. **Migration diff always visible** — even with `--force`, the migration diff MUST be displayed for audit visibility; NEVER skip diff display
+5. **Restore path on failure** — if migration fails, the backup restore command MUST be displayed; NEVER leave user without recovery instructions
+6. **Sequential migration** — all intermediate version steps MUST be applied in order by the schema registry; NEVER skip intermediate versions
+</invariants>
+
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Detect → Check**
+- REQUIRED: Current version read from `.workflow/state.json`.
+- BLOCKED if: state.json missing or unreadable (E001).
+
+**GATE 2: Check → Execute**
+- REQUIRED: Dry-run migration check completed; target version identified.
+- REQUIRED: User confirmation via AskUserQuestion (unless `--force`).
+- BLOCKED if: already up to date (display message and exit) or user cancels.
+
+**GATE 3: Execute → Summary**
+- REQUIRED: Backup created at `.workflow/state.json.backup-v{current}-{timestamp}`.
+- REQUIRED: Schema migration completed successfully.
+- REQUIRED: Version-specific setup doc followed (if exists).
+- BLOCKED if: migration failed — display restore command and exit.
+
+### Step 1: Detect Version
+
+```
+1. Read .workflow/state.json → extract version (default "1.0" if missing)
+2. Display:
+   === Maestro Update ===
+   Current version: v{version}
+```
+
+IF `--setup-only`:
+  → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+  → IF exists: follow that document completely, then EXIT
+  → IF not exists: display "No setup script for v{version}" → EXIT
+
+### Step 2: Check for Updates
+
+```
+1. Run: maestro update --migrate "$(pwd)" --dry-run --json
+2. Parse JSON output
+3. IF status = "up-to-date":
+     Display "Already up to date (v{version})"
+     → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+     → IF exists: AskUserQuestion "Run setup for v{version}?" → load and follow
+     → EXIT
+
+4. Display target:
+   Update available: v{current} → v{target}
+   Schema migrations: {N} step(s) (handled automatically)
+```
+
+IF `--dry-run` → display info and EXIT.
+
+### Step 3: Execute
+
+```
+1. Display migration diff (always — even with --force):
+   Show schema changes that will be applied.
+
+2. Confirm (unless --force):
+   AskUserQuestion: "Upgrade v{current} → v{target}?"
+   Options: [执行 / 取消]
+
+3. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
+
+4. Run schema migration (handles all intermediate steps automatically):
+   Bash: maestro update --migrate "$(pwd)" --json
+   Parse result, display changes.
+
+5. IF failed → display backup restore command → EXIT
+
+6. Load version-specific setup:
+   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
+   IF exists → follow completely (hooks, deps, knowledge system config)
+
+7. Display: "v{current} → v{target}: done"
+```
+
+### Step 4: Summary
+
+```
+=== Update Complete ===
+Version: v{current} → v{target}
+Backup:  .workflow/state.json.backup-v{current}-{timestamp}
+
+Next steps:
+  /manage-status  -- Verify project state
+  /maestro        -- Continue workflow
+```
+
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/state.json` not found or unreadable | Run `/maestro-init` first |
+| E002 | error | Schema migration failed (npx tsx returned error) | Display backup restore command: `cp .workflow/state.json.backup-* .workflow/state.json` |
+| E003 | error | Version-specific setup doc failed to execute | Manual setup: read `~/.maestro/workflows/updates/update-v{target}-setup.md` |
+| W001 | warning | No version-specific setup doc found for target version | Proceed without setup; schema migration alone is sufficient |
+| W002 | warning | `--setup-only` but no setup script exists for current version | Display message and exit |
+</error_codes>
+
+<success_criteria>
+- [ ] Current version detected from state.json
+- [ ] Schema migrations run automatically (no manual intermediate steps)
+- [ ] Backup created before migration
+- [ ] Version-specific setup doc loaded and followed (if exists)
+- [ ] --setup-only runs only setup for current version
+- [ ] --dry-run previews without executing
+- [ ] Summary shows version change and backup path
+</success_criteria>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Update complete | `/manage-status` to verify project state |
+| Want to continue workflow | `/maestro` |
+</completion>

package/skills/manage-codebase-rebuild/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: manage-codebase-rebuild
+description: "Rebuild all codebase documentation from scratch Arguments: [--focus <area>] [--force] [--skip-commit]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Full rebuild of `.workflow/codebase/` docs: 4 parallel mapper agents → tech-stack, architecture, features, concerns. Destructive — overwrites existing docs.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-rebuild.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
+- `--force` -- Skip confirmation prompt and proceed directly
+- `--skip-commit` -- Do not auto-commit after rebuild
+
+**Confirmation gate:** Unless `--force` is set, prompt the user (AskUserQuestion) before executing git commit. Show the list of changed files and proposed commit message. If `--skip-commit` is set, skip the commit entirely.
+
+**Mapper agent assignments (when `--focus` omitted):**
+| Agent | Focus | Output file |
+|-------|-------|-------------|
+| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
+| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
+| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
+
+**State files:**
+- `.workflow/` -- must be initialized (project.md, state.json exist)
+- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
+- `.workflow/codebase/doc-index.json` -- generated documentation index
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `.workflow/project.md` (Tech Stack section only). NEVER modify source code or files outside these paths.
+</context>
+
+<invariants>
+1. **Destructive with confirmation** — rebuild clears `.workflow/codebase/` entirely; MUST confirm with user unless `--force` is set
+2. **Commit confirmation** — git commit MUST be confirmed by user unless `--force` is set; `--skip-commit` bypasses commit entirely
+3. **Partial failure tolerance** — if 1-3 mapper agents fail, proceed with partial results (W001); only abort if all 4 fail (E002)
+4. **Focus scoping** — when `--focus <area>` is set, MUST only regenerate docs relevant to that scope; leave unrelated docs untouched
+5. **State update** — MUST update state.json with rebuild timestamp on completion
+6. **KG pipeline mandatory** — MUST run `maestro kg index` after doc regeneration; KG validation failure is non-fatal (W003)
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
+
+**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Confirmation → Mapping** (Pre-flight → Agent spawn)
+- REQUIRED: `.workflow/` initialized (E001 if missing).
+- REQUIRED: User confirmed rebuild (or `--force` set). W002 if existing docs found.
+- BLOCKED if user declines confirmation.
+
+**GATE 2: Mapping → KG Pipeline** (Agent results → Knowledge Graph)
+- REQUIRED: At least 1 of 4 mapper agents returned valid results.
+- REQUIRED: All output files written to `.workflow/codebase/`.
+- REQUIRED: doc-index.json generated and valid.
+- BLOCKED if all 4 mapper agents failed (E002).
+
+**GATE 3: KG Pipeline → Commit** (Knowledge Graph → Git)
+- REQUIRED: `maestro kg index` executed (W003 if validation fails — non-blocking).
+- REQUIRED: state.json updated with rebuild timestamp.
+- REQUIRED: If not `--skip-commit`: user confirmed git commit (or `--force` set).
+- BLOCKED if state.json update fails.
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| View updated state | `/manage-status` |
+| Incremental updates later | `/quality-sync` |
+| Verify KG stats | `maestro kg stats` |
+| Future change impact | `maestro kg diff-wiki` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| E002 | error | All 4 mapper agents failed | Abort rebuild; check agent configuration and retry |
+| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
+| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
+| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
+</error_codes>
+
+<success_criteria>
+- [ ] User confirmed rebuild (or --force used)
+- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
+- [ ] All 4 mapper agents spawned (all-fail → E002; partial fail → W001)
+- [ ] If not --skip-commit: user confirmed git commit (or --force used) before committing
+- [ ] doc-index.json generated and valid
+- [ ] All documentation files regenerated
+- [ ] state.json updated with rebuild timestamp
+- [ ] project.md Tech Stack section updated if changes detected
+- [ ] KG pipeline executed (`maestro kg index`)
+- [ ] knowledge-graph.json generated in .workflow/codebase/
+- [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
+- [ ] Next step routed
+</success_criteria>

package/skills/manage-drift-realign/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: manage-drift-realign
+description: "Detect and realign .workflow/ artifact drift against code reality after refactoring Arguments: [--scope <roadmap|spec|codebase|state|issue|knowhow|project|all>] [--since YYYY-MM-DD|commit|HEAD~N] [--depth shallow|deep] [--dry-run] [--report] [--auto-archive] [--interactive]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+检测代码重构/增量变更后，代码现实与 .workflow/ 文档之间的漂移。互补于 `manage-knowledge-audit`（检测知识存储内部矛盾）。本命令通过 git 时间线 + session 历史检测 code↔document 漂移。
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/drift-realign.md
+</required_reading>
+
+<deferred_reading>
+- ~/.maestro/workflows/knowledge-audit.md (交叉引用已有审计发现)
+- ~/.maestro/workflows/sync.md (codebase 文档严重漂移时自动触发)
+- ~/.maestro/workflows/codebase-rebuild.md (sync 不足时的回退方案)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope：** `roadmap` | `spec` | `codebase` | `state` | `issue` | `knowhow` | `project` | `all`（默认 `all`）
+
+**`--since`：** 分析起始点。支持日期（`YYYY-MM-DD`）、commit ref（`abc1234`）、相对引用（`HEAD~N`）。默认自动检测：优先读 `state.json` 的 `last_drift_realign` 或 `last_pruned` 时间戳，回退 90 天。
+
+**`--depth`：** `shallow`（mtime + 引用检查）vs `deep`（LLM 语义分析）。默认 `shallow`。
+
+**`--dry-run`：** 预览模式，不执行任何写入。
+
+**`--report`：** 仅生成报告，不进入交互分诊。
+
+**`--auto-archive`：** 自动归档陈旧项，跳过逐项确认。
+
+**`--interactive`：** 逐项交互分诊（默认）。
+
+**互斥规则：**
+- `--report` 覆盖 `--interactive`
+- `--auto-archive` 覆盖 `--interactive`
+- `--report` 与 `--auto-archive` 互斥（同时传入 → E006）
+
+**状态文件读取：**
+- `.workflow/state.json`
+- `.workflow/roadmap.md`
+- `.workflow/specs/*.md`
+- `.workflow/codebase/*.md`
+- `.workflow/issues/issues.jsonl`
+- `.workflow/knowhow/*.md`
+- `.workflow/project.md`
+
+使用 `maestro timeline` CLI 构建统一的 git+session 时间线。
+
+**Output boundary**: ALL file writes MUST target `.workflow/` metadata files (specs, codebase docs, roadmap.md, state.json, issues.jsonl) or `.workflow/.trash/drift-realign-{timestamp}/` (backups) or `.workflow/.drift-realign/` (session details). NEVER modify source code files.
+</context>
+
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；当文档说 X 但代码做 Y 时，文档漂移，NEVER 反向修改代码来匹配文档
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Never modify source code** — drift-realign only updates `.workflow/` metadata; source code files are read-only
+4. **Mutual exclusion** — `--report` 与 `--auto-archive` 互斥；同时传入 MUST trigger E006
+5. **Auto-depth escalation** — `drift_window` > 180 天 MUST auto-upgrade to `--depth deep` with W002 warning
+6. **Audit trail** — every triage decision MUST be logged in `drift-log.jsonl` with finding ID, action, and timestamp
+7. **Rebuild trigger** — codebase scope 的 3+ P0 finding MUST auto-trigger `/quality-sync --full` after triage
+</invariants>
+
+<execution>
+Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Timeline** (Stages 1-2)
+- REQUIRED: `.workflow/` 存在，scope 解析通过，`--since` 已解析。
+- REQUIRED: `maestro timeline --since <date> --json` 产出有效时间线。
+- BLOCKED if `.workflow/` 缺失 (E001)、scope 非法 (E002)、git 不可用 (E003)。
+
+**GATE 2: Timeline → Scan** (Stages 2-3 → Stage 4)
+- REQUIRED: `timeline.json` 已生成且包含事件。
+- REQUIRED: `drift_score` 已计算（LOW/MODERATE/SEVERE）。
+- REQUIRED: 若 SEVERE 且 `--depth shallow`，发出 W002 建议 `--depth deep`。
+- BLOCKED if 时间线为空（`--since` 之后无变更）。
+
+**GATE 3: Scan → Triage** (Stage 4 → Stages 5-6)
+- REQUIRED: 4 个并行漂移扫描 agent 全部返回结果（或 W003 部分覆盖）。
+- REQUIRED: `DriftFinding[]` 已合并、去重、按严重度排序。
+- BLOCKED if 所有 agent 均失败。
+
+**GATE 4: Triage → Apply** (Stages 6-7 → Stage 8)
+- REQUIRED: 备份 tarball 生成于 `.workflow/.trash/drift-realign-{timestamp}/`。
+- REQUIRED: 所有用户决策已记录（或 `--auto-archive`/`--report` 已生效）。
+- REQUIRED: codebase scope 的 rebuild 动作自动触发 `/quality-sync --full`。
+- BLOCKED if 备份失败 (E005)。
+
+### Execution Constraints
+
+- **Code-as-Truth**: 代码是唯一真理源。当文档说 X 但代码做 Y 时，文档漂移。
+- **Parallel scan**: Stage 4 在单条消息中派发 4 个 agent（roadmap-scanner、spec-scanner、codebase-scanner、artifact-scanner）。
+- **Auto-rebuild**: 当 codebase-scanner 检测到严重漂移（3+ P0 finding）时，分诊后自动触发 `/quality-sync --full`。若 sync 报告重大结构变更，建议 `/manage-codebase-rebuild`。
+- **Long gap handling**: 当 `drift_window` > 180 天时，自动升级为 `--depth deep` 并警告用户 (W002)。
+
+### Platform Inquiry（Stage 2a，交互式）
+
+当 `session_summary.by_platform` 包含多个平台且 session 总量 > 20 时，使用 AskUserQuestion 询问用户修改主要在哪个平台进行。用户选择后以 `--platform` 参数重新获取 timeline，缩小后续分析范围。
+
+### Session 详情加载策略（Stage 2b）
+
+`maestro timeline` 每条 session 事件已包含：`summary`（用户提问摘要）、`edited_files`、`code_paths`、`platform`。这些信息在 `--depth shallow` 模式下足以支撑漂移检测。
+
+当 `--depth deep` 时，对与 cold_workflow_files 有 edited_files 交集的 session，通过 `maestro load --type session --id <id> --json` 按需加载完整 body 和 related 字段：
+- 仅加载 edited_files 与 cold_workflow_files 有交集的 session
+- 最多加载 10 个（按交集文件数降序排序）
+- 结果写入 `.workflow/.drift-realign/session-details-{date}.json`
+- scanner agent 在 deep 模式下同时接收 timeline.json + session-details.json
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| codebase 文档已重建 | `/manage-status` |
+| spec 标记待更新 | 手动编辑标记的 spec 文件 |
+| roadmap 已过时 | `/maestro-roadmap` 重新生成 |
+| state.json 需清理 | `/manage-knowledge-audit --scope artifact` |
+| 需要完整同步 | `/quality-sync --full` |
+| project.md 已过时 | 编辑 `.workflow/project.md` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` 未初始化 | 先跑 `/maestro-init` |
+| E002 | error | `--scope` 非法 | 提供有效 scope: roadmap/spec/codebase/state/issue/knowhow/project/all |
+| E003 | error | git 不可用（非 git 仓库） | 初始化 git |
+| E004 | error | `--since` 无法解析 | 检查日期格式或 commit ref |
+| E005 | error | 备份失败 | 检查磁盘空间 |
+| E006 | error | `--report` 与 `--auto-archive` 同时传入 | 二选一：`--report` 仅生成报告，`--auto-archive` 执行归档 |
+| W001 | warning | session 历史不可用（wiki 未索引） | 运行 `maestro wiki rebuild` |
+| W002 | warning | `drift_window` > 180 天 | 建议使用 `--depth deep` |
+| W003 | warning | 部分 scanner agent 失败 | 以部分覆盖继续 |
+| W004 | warning | git log > 1000 commits | 自动截断至最近 1000 条 |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope 正确解析，互斥标志校验通过
+- [ ] `maestro timeline` 已调用，`timeline.json` 已生成
+- [ ] `drift_score` 已计算（LOW/MODERATE/SEVERE 已展示）
+- [ ] 4 个并行 scanner agent 已派发
+- [ ] `DriftFinding[]` 已合并并按 P0 > P1 > P2 排序
+- [ ] 如 `--interactive`：用户已分诊所有 finding
+- [ ] 变更前备份 tarball 已生成
+- [ ] archive 动作已将文件移入 `.trash/`
+- [ ] update 动作已注入 TODO 标记及提示
+- [ ] rebuild 动作已自动触发 `/quality-sync --full`
+- [ ] `state.json` 已更新 `last_drift_realign` 时间戳
+- [ ] `drift-report-{date}.md` 已生成
+- [ ] `drift-log.jsonl` 已追加
+- [ ] 摘要展示及下一步路由已输出
+</success_criteria>

package/skills/manage-harvest/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: manage-harvest
+description: "Extract knowledge from artifacts into wiki/spec/issues Arguments: [<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Extract knowledge from workflow artifacts → route to wiki/spec/issue stores. Works on any artifact (vs retrospective which is phase-scoped).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected):**
+- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
+- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
+- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
+
+**Flags:**
+- `-y` / `--yes` — Skip confirmation prompts for all write operations (artifact selection, routing decisions, store writes). Useful for CI or batch harvesting.
+
+Additional flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/`, `.workflow/specs/`, `.workflow/issues/`, `.workflow/wiki/`, `.workflow/harvest/`, or `.workflow/state.json` only. NEVER modify source code, source artifacts, or files outside these paths.
+</context>
+
+<invariants>
+1. **Read-only until routing** — extraction and classification happen in-memory; no files written until Stage 6
+2. **Never modify source artifacts** — harvest is purely extractive; source files remain untouched
+3. **Dedup before write** — MUST check harvest-log.jsonl and existing stores before each write to prevent duplicates
+4. **Source tagging** — MUST set `source: "harvest"` on every issues.jsonl row so concurrent writers can be distinguished
+5. **Relationship pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category. Classify the relationship: **supersede** (new replaces old) → attach `supersedes = <old-sid>`, after add run `maestro spec supersede`; **conflict** (genuine dispute) → set `confidence="low"` and log conflict note; **independent** → no metadata
+6. **Provenance tracking** — every routed item MUST be logged in harvest-log.jsonl with fragment ID, target store, and timestamp
+7. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview only
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Discovery → Extraction** (Stages 1-3 → Stage 4)
+- REQUIRED: Source artifacts discovered and mode resolved (scan/session/path).
+- REQUIRED: User selected artifact(s) to harvest (or auto-selected via session/path mode, or `-y`).
+- BLOCKED if no harvestable artifacts found (W001) or invalid source (E004/E005).
+
+**GATE 2: Extraction → Routing** (Stage 4 → Stage 5-6)
+- REQUIRED: All files in selected artifacts loaded and parsed.
+- REQUIRED: Knowledge fragments extracted with category, confidence, and tags.
+- REQUIRED: Fragments filtered by `--min-confidence`.
+- BLOCKED if extraction produces zero fragments.
+
+**GATE 3: Routing → Write** (Stage 6 → Stage 7-8)
+- REQUIRED: Routing classification applied (auto or forced by `--to`).
+- REQUIRED: Dedup check passed against harvest-log.jsonl and existing stores.
+- REQUIRED: If `--dry-run`: preview displayed, no files written — GATE blocks further writes.
+- BLOCKED if dedup check fails or store paths unresolvable.
+
+Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Wiki entries created | `maestro wiki list --type note` |
+| Wiki graph needs linking | `/manage-wiki connect --fix` |
+| Issues created | `/manage-issue list --source harvest` |
+| Specs extracted | `maestro load --type spec` |
+| Specs extracted (审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾或替代 |
+| 查看演化链 | `maestro spec history <sid>` — 确认 supersede 链完整 |
+| Spec 冲突标记已存在 | `maestro spec conflict list` — 查看当前冲突状态 |
+| 知识健康检查 | `maestro spec health` — 悬空/循环 supersedes 校验 |
+| Full phase retrospective | `/quality-retrospective` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
+| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
+| E003 | error | Invalid `--source` type | Display valid source types from registry |
+| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
+| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
+| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
+| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
+| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
+| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / session / path)
+- [ ] Source artifacts discovered and listed with metadata
+- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
+- [ ] All files in selected artifacts loaded and parsed
+- [ ] Knowledge fragments extracted with category, confidence, tags
+- [ ] Fragments filtered by `--min-confidence`
+- [ ] Routing classification applied (auto or forced by `--to`)
+- [ ] Dedup check passed against harvest-log.jsonl and existing stores
+- [ ] If `--dry-run`: preview displayed, no files written
+- [ ] If not dry-run: all routed items written to target stores
+- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
+- [ ] Spec entries added via `spec-add` mechanism
+- [ ] Issue entries appended to `issues.jsonl` with canonical schema
+- [ ] `harvest-log.jsonl` updated with provenance for each routed item
+- [ ] `harvest-report-{date}.md` written with full summary
+- [ ] No source artifacts modified
+- [ ] Summary displayed with counts and next-step routing
+</success_criteria>

package/skills/manage-issue/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: manage-issue
+description: "Create, query, update, close, and link issues Arguments: <subcommand: create|list|status|update|close|link> [--title text] [--severity S] [--status S] [--resolution text]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Issue lifecycle management: create, list, status, update, close, link. Stored in `.workflow/issues/issues.jsonl`. For automated discovery, use `/manage-issue-discover`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating or updating issue records (create, update, close)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- subcommand + options. Parse first token as subcommand.
+
+**Valid subcommands:**
+- `create` -- create a new issue (--title, --severity, --source, --phase, --description)
+- `list` -- list issues with optional filters (--status, --phase, --severity, --source)
+- `status` -- show full detail for a specific issue (ISS-XXXXXXXX-NNN)
+- `update` -- update issue fields (ISS-XXXXXXXX-NNN --status, --priority, --severity, --tags, ...)
+- `close` -- close an issue with resolution (ISS-XXXXXXXX-NNN --resolution)
+- `link` -- link issue to a task (ISS-XXXXXXXX-NNN --task TASK-NNN)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
+- `.workflow/issues/issue-history.jsonl` -- archived/closed issues
+
+**Output boundary**: ALL file writes MUST target `.workflow/issues/issues.jsonl`, `.workflow/issues/issue-history.jsonl`, or `.workflow/issues/` directory only. NEVER modify source code or files outside these paths.
+</context>
+
+<invariants>
+1. **Schema compliance** — every issue record MUST conform to the canonical issue.json template schema
+2. **ID uniqueness** — issue IDs (ISS-XXXXXXXX-NNN) MUST be unique across issues.jsonl and issue-history.jsonl
+3. **Close moves to history** — `close` subcommand MUST move the record from issues.jsonl to issue-history.jsonl, NEVER delete without archiving
+4. **Bidirectional links** — `link` subcommand MUST create references in both the issue and the linked task
+5. **Confirmation on destructive ops** — `close` and bulk `update` MUST require user confirmation unless `-y` flag is set
+6. **Append-only audit** — NEVER overwrite existing issue records; updates MUST preserve all prior fields and add `updated_at` timestamp
+</invariants>
+
+<execution>
+Parse subcommand from first token of $ARGUMENTS.
+Follow '~/.maestro/workflows/issue.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Execute** (Subcommand routing)
+- REQUIRED: Subcommand parsed and validated against valid set (create/list/status/update/close/link).
+- REQUIRED: `.workflow/issues/` directory exists (auto-create with empty issues.jsonl if missing).
+- BLOCKED if E_NO_SUBCOMMAND or E_INVALID_SUBCOMMAND.
+
+**GATE 2: Execute → Write** (For mutating subcommands: create/update/close/link)
+- REQUIRED: Issue data validated against issue.json template schema.
+- REQUIRED: For `close`: resolution text provided.
+- REQUIRED: For `link`: target task ID resolved and exists.
+- BLOCKED if schema validation fails or target references unresolvable.
+</execution>
+
+<completion>
+### Next-step routing
+
+| Subcommand | Suggestion |
+|-----------|-----------|
+| create | `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps` |
+| list | `/maestro-analyze --gaps <ISS-ID>` for open issues |
+| close | `/manage-status` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_SUBCOMMAND | error | No subcommand provided in $ARGUMENTS | Display valid subcommands, prompt user to select |
+| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand | Display valid subcommands with usage hints |
+| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` directory does not exist | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed and routed to correct handler
+- [ ] Issue data read/written to correct JSONL file
+- [ ] Output displayed in appropriate format (table for list, detail for status)
+- [ ] Cross-references maintained (link creates bidirectional references)
+- [ ] Next step routed by subcommand
+</success_criteria>