pi-maestro-flow 0.2.0

package/skills/manage-issue-discover/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: manage-issue-discover
+description: "Discover issues via multi-perspective analysis Arguments: [multi-perspective | by-prompt <prompt>] [-y] [--scope <glob>] [--depth standard|deep]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Automated issue discovery: multi-perspective (8 perspectives) or prompt-driven. Deduplicates and records to `issues.jsonl`. For CRUD operations, use `/manage-issue`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue-discover.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating issue records from findings (Step 6/11)
+- [search-tools](~/.maestro/templates/search-tools.md) — search tool priority, passed to agents via workflow
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- optional. Parse first token to determine mode.
+
+**Modes:**
+- _(empty)_ -- interactive mode selection (AskUserQuestion)
+- `multi-perspective` -- 8-perspective parallel agent scan
+- `by-prompt "..."` -- prompt-driven iterative agent exploration (CLI-planned)
+
+**Flags:**
+- `-y` / `--yes` -- auto mode, skip confirmations
+- `--scope=<pattern>` -- file scope (default: `**/*`)
+- `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- issues appended here (set `source: "discover"` on each row so concurrent writers like `manage-harvest` with `source: "harvest"` can be distinguished and deduplicated)
+- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
+
+### Pre-load specs
+1. **Debug specs**: Run `maestro load --type spec --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
+2. Optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `.workflow/issues/issues.jsonl` or `.workflow/issues/discoveries/{SESSION_ID}/` only. NEVER modify source code or files outside these paths.
+</context>
+
+<invariants>
+1. **Read-only analysis** — discovery agents MUST NOT modify source code; only `.workflow/issues/` is writable
+2. **Source tagging** — MUST set `source: "discover"` on every issues.jsonl row so concurrent writers (e.g. `manage-harvest`) can be distinguished and deduplicated
+3. **Dedup before write** — MUST check existing issues.jsonl for duplicates before appending new findings
+4. **Session traceability** — every discovery run MUST produce a session directory under `.workflow/issues/discoveries/` with full agent outputs
+5. **Schema compliance** — every issue row MUST conform to the canonical issue.json template schema
+6. **Idempotent re-run** — repeated execution with same scope and prompt MUST NOT create duplicate issues
+</invariants>
+
+<execution>
+Determine mode from $ARGUMENTS:
+- No arguments or empty → interactive selection via AskUserQuestion
+- First token is `multi-perspective` → multi-perspective mode
+- First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
+
+Follow '~/.maestro/workflows/issue-discover.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Mode Selection → Analysis** (Steps 1-2 → Steps 3-8)
+- REQUIRED: Mode correctly determined from arguments (multi-perspective or by-prompt).
+- REQUIRED: `.workflow/issues/` directory exists (auto-create if missing).
+- BLOCKED if E_NO_PROJECT (`.workflow/` missing) or E_EMPTY_PROMPT (by-prompt without text).
+
+**GATE 2: Analysis → Issue Creation** (Steps 8-9 → Steps 10-11)
+- REQUIRED: All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt).
+- REQUIRED: Findings deduplicated against existing issues.jsonl.
+- BLOCKED if E_DISCOVERY_FAILED (all agents returned no results).
+
+**GATE 3: Issue Creation → Completion** (Steps 11-12)
+- REQUIRED: Issues appended to issues.jsonl with correct schema and `source: "discover"`.
+- REQUIRED: Discovery session directory created with full agent outputs.
+- BLOCKED if schema validation fails on any issue record.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_PROJECT | error | `.workflow/` does not exist | Prompt user to run `/maestro-init` first |
+| E_DISCOVERY_FAILED | error | CLI analysis returned no results | Retry with different tool or report partial findings |
+| E_EMPTY_PROMPT | warning | `by-prompt` used without prompt text | Interactive prompt with suggested options |
+</error_codes>
+
+<success_criteria>
+- [ ] Discovery mode correctly determined from arguments
+- [ ] All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt)
+- [ ] Findings deduplicated before issue creation
+- [ ] Issues appended to issues.jsonl with correct schema
+- [ ] Discovery session fully traceable via session directory
+- [ ] Next step routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Issues discovered | `/manage-issue list` to review |
+| Need root cause analysis | `/maestro-analyze --gaps <ISS-ID>` |
+| Want to plan fixes | `/maestro-plan --gaps` |
+</completion>

package/skills/manage-kg-extractors/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: manage-kg-extractors
+description: "Analyze codebase patterns and generate .workflow/kg/extractors.yaml for custom symbol extraction Arguments: [--scan-only] [--append] [--language <lang>] [--min-count <n>]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Analyze current repository's code patterns to auto-generate `.workflow/kg/extractors.yaml` — a declarative config that teaches MaestroGraph's codegraph extractor to recognize project-specific symbols beyond standard function/class/method declarations.
+</purpose>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--scan-only` — Only report detected patterns, don't write extractors.yaml
+- `--append` — Append new rules to existing extractors.yaml (default: overwrite)
+- `--language <lang>` — Limit analysis to specific language (python, typescript, java, etc.)
+- `--min-count <n>` — Minimum occurrences to include a pattern (default: 3). Use `--min-count 1` to include rare patterns.
+
+**Analysis targets (per language):**
+
+| Language | Pattern Types |
+|----------|--------------|
+| Python | `define_*()` builder APIs, ALL_CAPS constants, `Final[...]` annotations, dataclass/pydantic fields |
+| TypeScript | const enum, namespace exports, decorator factories, config objects |
+| Java | static final constants, @Bean/@Component annotations, builder patterns |
+| Go | exported constants (const blocks), interface registrations |
+| All | Custom factory/builder call patterns with string-literal first args |
+
+**Output:** `.workflow/kg/extractors.yaml` — declarative rules for PluginEngine.
+
+**Output boundary**: ALL file writes MUST target `.workflow/kg/extractors.yaml` only. NEVER modify source code or files outside this path. `--scan-only` MUST NOT write any files.
+
+**Rule format:**
+```yaml
+version: 1
+defaults:
+  onError: warn
+  conflictPolicy: merge-metadata
+plugins:
+  - id: <project>.<pattern>
+    languages: [<lang>]
+    mode: declarative
+    declarative:
+      rules:
+        - id: <rule-id>
+          match:
+            type: call | assignment | regex
+            pattern: "<pattern>"
+            nameRegex: "<optional filter>"
+            scope: module | class | any
+          extract:
+            kind: constant | variable | property | field
+            decorators: ["<semantic_tag>"]
+            metadata:
+              semanticKind: "<domain_kind>"
+```
+</context>
+
+<execution>
+
+<invariants>
+1. **Read-only source code** — agents MUST only read source files for pattern discovery; NEVER modify source code
+2. **Scan-only safety** — `--scan-only` MUST stop after Phase 2 summary; NEVER write extractors.yaml
+3. **Append preservation** — `--append` MUST preserve existing rules in extractors.yaml; default (overwrite) MUST warn (W003) if file exists
+4. **Min-count threshold** — patterns with fewer occurrences than `--min-count` MUST be excluded unless explicitly overridden
+5. **User confirmation** — each pattern group MUST be confirmed/edited/skipped by user before writing (Phase 3, Step 2)
+6. **Schema compliance** — generated extractors.yaml MUST conform to version 1 PluginEngine schema with required fields (id, languages, mode, rules)
+7. **Validation mandatory** — MUST run `maestro kg index` after writing to verify new symbols are extractable
+</invariants>
+
+### Phase 1: Discover patterns
+
+Spawn **3 parallel agents** to scan the codebase:
+
+| Agent | Focus | Method |
+|-------|-------|--------|
+| Agent 1 | **Builder/factory calls** | Grep for patterns like `define_*("`, `register_*("`, `add_*("` where first arg is a string literal |
+| Agent 2 | **Constants & annotations** | Grep for ALL_CAPS assignments, Final[], static final, const enum, exported const |
+| Agent 3 | **Framework patterns** | Detect framework (from package.json/setup.py/go.mod) → grep framework-specific registration patterns |
+
+Each agent returns: `[{pattern_type, regex_evidence, file_count, sample_matches: [{file, line, code}]}]`
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Discovery → Generation** (Phase 1 → Phase 2)
+- REQUIRED: At least 1 of 3 agents returned valid pattern results.
+- BLOCKED if all 3 agents return empty results (E002).
+
+**GATE 2: Generation → Write** (Phase 2 → Phase 3)
+- REQUIRED: At least 1 pattern meets `--min-count` threshold.
+- REQUIRED: User confirmed pattern groups via AskUserQuestion.
+- BLOCKED if `--scan-only` is set — stop after summary.
+
+**GATE 3: Write → Validation** (Phase 3 → KG Index)
+- REQUIRED: extractors.yaml written with valid schema.
+- REQUIRED: `maestro kg index` executed to verify extraction.
+- BLOCKED if schema validation fails on generated YAML.
+
+### Phase 2: Generate rules
+
+For each discovered pattern with ≥3 occurrences:
+1. Determine match type (call/assignment/regex)
+2. Build pattern string and optional nameRegex
+3. Assign appropriate kind and semanticKind
+4. Generate rule entry
+
+### Phase 3: Validate & write
+
+1. Show discovered patterns summary to user
+2. AskUserQuestion: confirm/edit/skip each pattern group
+3. Write `.workflow/kg/extractors.yaml`
+4. Run `maestro kg index` to verify new symbols are extracted
+
+If `--scan-only`: stop after Phase 2 summary.
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify new symbols | `maestro search --kg "<pattern_name>"` |
+| Re-index after changes | `maestro kg index` |
+| View KG stats | `maestro kg stats` |
+| Edit rules manually | Edit `.workflow/kg/extractors.yaml` |
+| Add script plugin | Create `.workflow/kg/extractors/<name>.mjs` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first |
+| E002 | error | All 3 Phase 1 agents failed — zero patterns discovered | Check codebase language detection; retry with `--language` |
+| W001 | warning | No patterns detected for language | Try broader scan or different language |
+| W002 | warning | Pattern has < 3 occurrences | Skipped by default, include with --min-count 1 |
+| W003 | warning | Existing extractors.yaml will be overwritten | Use --append to preserve |
+</error_codes>
+
+<success_criteria>
+- [ ] At least 1 pattern detected in the codebase
+- [ ] extractors.yaml generated with valid rules
+- [ ] Each rule has match.type, match.pattern, extract.kind
+- [ ] Re-index succeeds with new extractors.yaml active
+- [ ] New symbols searchable via `maestro search --kg`
+</success_criteria>

package/skills/manage-knowhow/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: manage-knowhow
+description: "Manage knowhow entries (workflow and system) Arguments: <subcommand: list|search|view|edit|delete|prune> [query|id] [--store workflow|system|all] [--tag <tag>] [--type compact|tip]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Manage knowhow across two stores: workflow (`.workflow/knowhow/`) and system memory (`~/.claude/projects/*/memory/`). Operations: list, search, view, edit, delete, prune.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
+
+**Output boundary**: Workflow store writes MUST target `.workflow/knowhow/` only. System store writes MUST target `~/.claude/projects/*/memory/` only. NEVER modify source code or files outside these paths.
+
+**Subcommands:**
+- `list` — List entries from both stores (default if no arguments)
+- `search <query>` — Full-text search across both stores
+- `view <id|file>` — Display a workflow entry by ID or system file by name
+- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
+- `delete <id|file>` — Remove an entry/file (with confirmation)
+- `prune` — Bulk cleanup by criteria
+
+**Flags:**
+- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
+- `--tag <tag>` — Filter by tag (workflow store)
+- `--type <compact|tip>` — Filter by entry type (workflow store)
+- `--before <YYYY-MM-DD>` — Entries before date
+- `--after <YYYY-MM-DD>` — Entries after date
+- `--dry-run` — Preview destructive ops without executing
+- `--confirm` — Skip confirmation prompt
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Execute** (Subcommand routing)
+- REQUIRED: Subcommand parsed from first token (list/search/view/edit/delete/prune).
+- REQUIRED: Both store paths resolved (workflow + system).
+- BLOCKED if E001 (no memory stores found) or invalid subcommand.
+
+**GATE 2: Execute → Mutate** (For destructive subcommands: delete/prune/edit)
+- REQUIRED: Target entry/file resolved and exists (E002 if not found).
+- REQUIRED: MEMORY.md protected from deletion (E004 — use `edit` instead).
+- REQUIRED: For `prune`: at least one filter provided (E003).
+- REQUIRED: User confirmation before delete/prune unless `--confirm` flag set.
+- BLOCKED if target unresolvable or confirmation denied.
+</execution>
+
+<invariants>
+1. **MEMORY.md protected** — NEVER delete MEMORY.md; only editable via `edit` subcommand
+2. **MEMORY.md line limit** — MUST warn (W003) when MEMORY.md exceeds 200 lines; content beyond 200 lines will be truncated at load
+3. **Confirmation on destructive ops** — `delete` and `prune` MUST require user confirmation unless `--confirm` flag is set
+4. **Store isolation** — `prune` operates on workflow store only; NEVER prune system memory files
+5. **Reference integrity** — `delete` MUST check for references from other entries before removing; warn if orphaned references would result
+6. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview destructive operations only
+7. **Index consistency** — after delete/prune, workflow index MUST be updated to reflect removals
+</invariants>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
+| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
+| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
+| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
+| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
+| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
+</error_codes>
+
+<success_criteria>
+- [ ] Both store paths correctly resolved
+- [ ] Subcommand correctly detected from arguments
+- [ ] Store auto-detected from argument format (KNW-*/TIP-* vs filename)
+- [ ] List: both stores displayed with appropriate formatting
+- [ ] Search: results from both stores, ranked by relevance
+- [ ] View: correct store selected, full content displayed
+- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
+- [ ] Delete: MEMORY.md protected, confirmation required, references checked
+- [ ] Prune: workflow-only, filters validated, index updated
+- [ ] Integrity check catches orphans and broken links
+- [ ] Next step routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Want to capture new knowhow | `/manage-knowhow-capture` |
+| View project state | `/manage-status` |
+| Prune stale entries | `/manage-knowledge-audit --scope knowhow` |
+</completion>

package/skills/manage-knowhow-capture/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: manage-knowhow-capture
+description: "Capture reusable knowledge as templates, recipes, or tips Arguments: [<type>] [<description>] [--lang <lang>] [--source <url>] [--tag t1,t2]"
+allowed-tools: Read Write Edit Bash Glob Grep WebFetch AskUserQuestion
+---
+
+<purpose>
+Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
+Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --type knowhow`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+$ARGUMENTS — type token + description + optional flags.
+
+**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--description <desc>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+
+**Type routing** (first token match):
+
+| Token | Type | Prefix | Key fields |
+|-------|------|--------|------------|
+| `compact`/`session`/`压缩`/`保存` | compact | KNW- | objective, files, decisions, plan, pending |
+| `template`/`tpl`/`模板` | template | TPL- | language, code block, usage, parameters |
+| `recipe`/`rcp`/`配方`/`步骤` | recipe | RCP- | prerequisites, steps, expected outcome, pitfalls |
+| `reference`/`ref`/`参考`/`引用` | reference | REF- | source URL, key points, scenarios, examples |
+| `decision`/`dcs`/`决策`/`adr` | decision | DCS- | context, alternatives table, rationale, consequences |
+| `tip`/`note`/`记录`/`快速` | tip | TIP- | content, tags |
+| `asset`/`ast`/`资产`/`契约` | asset | AST- | assetType, codePaths, category |
+| `blueprint`/`blp`/`蓝图` | blueprint | BLP- | codePaths, category |
+| `document`/`doc`/`文档` | document | DOC- | (general fallback) |
+| `insight`/`ins`/`洞察`/`经验` | insight | INS- | content, tags, phase (replaces former manage-learn) |
+| Short text + `--tag` | tip | TIP- | — |
+| No args | — | — | AskUserQuestion (10 options) |
+
+**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/` only. NEVER modify source code or files outside this path.
+</context>
+
+<invariants>
+1. **Description required** — every entry MUST have a `description` field in frontmatter (under 120 chars) for search indexing
+2. **Tags language match** — tags MUST match content language (Chinese content → Chinese tags, English → English)
+3. **ID uniqueness** — generated file names ({PREFIX}-{YYYYMMDD}-{slug}.md) MUST be unique; NEVER overwrite existing entries
+4. **Frontmatter completeness** — YAML frontmatter MUST include: title, description, type, category, created, tags, status
+5. **Type-specific validation** — each type MUST populate all its required fields before writing (template needs code block, recipe needs steps, etc.)
+6. **Idempotent naming** — same content captured twice MUST produce same slug, enabling dedup detection
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/knowhow.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Type Detection → Content Collection** (Type routing → Content extraction)
+- REQUIRED: Type detected from first token or selected via AskUserQuestion.
+- REQUIRED: Type maps to a valid prefix (KNW-/TPL-/RCP-/REF-/DCS-/TIP-/AST-/BLP-/DOC-/INS-).
+- BLOCKED if type unresolvable after interactive prompt.
+
+**GATE 2: Content Collection → Write** (Content extraction → File write)
+- REQUIRED: All type-specific required fields populated (e.g., template needs code block, recipe needs steps).
+- REQUIRED: `description` field generated or provided (under 120 chars).
+- REQUIRED: Tags generated in correct language matching content.
+- BLOCKED if required fields missing after user prompt (E002/E003).
+
+**Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
+
+**Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.
+
+**Type-specific content rules**:
+
+| Type | Content extraction |
+|------|-------------------|
+| compact | Extract from conversation: session ID, objective, execution plan (verbatim), working files (3-8), decisions, constraints, pending. Plan priority: workflow IMPL_PLAN.md > TodoWrite > user-stated > inferred. |
+| template | Ask for: language, code block, parameters (placeholders), usage context, dependencies |
+| recipe | Ask for: goal, prerequisites, numbered steps, expected outcome, common pitfalls |
+| reference | From --source URL or ask. Key points, applicable scenarios, quick examples. Offer WebFetch if URL provided. |
+| decision | Context, alternatives (table: alt/pros/cons/rejected-because), rationale, consequences. Status: proposed/accepted/superseded. |
+| tip | Content = everything after type token. Auto-detect context from recent files. |
+| asset | assetType (api-contract/data-model/prompt/config), codePaths, category for agent discovery |
+| blueprint | Architecture design with codePaths and category |
+</execution>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Template: no code provided after prompt | Ask again or cancel |
+| E003 | Recipe: no steps provided after prompt | Ask again or cancel |
+| W001 | No active workflow session (compact) | Captures conversation only |
+| W002 | Plan detection found no explicit plan (compact) | Uses inferred plan |
+</error_codes>
+
+<success_criteria>
+- [ ] Type detected or selected, all type-specific fields populated
+- [ ] File written to .workflow/knowhow/ with correct prefix and YAML frontmatter
+- [ ] Confirmation displayed with ID, type, path
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Entry captured | `/manage-knowhow list` to view library |
+| Want to connect entries | `/manage-wiki connect` |
+| Want to bridge to specs | `/spec-add <category>` with `--spec-category` |
+</completion>

package/skills/manage-knowledge-audit/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: manage-knowledge-audit
+description: "Audit and prune knowledge across spec / knowhow / artifact stores Arguments: --scope <spec|knowhow|artifact|all> [--level P0|P1|P2] [--timeline T1..T6] [--since YYYY-MM-DD] [--milestone <name>] [--include-archive] [--interactive] [--mark|--delete|--purge] [--dry-run] [--report]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+审查 spec/knowhow/artifact 存储，识别矛盾/失效/孤儿，通过 keep/deprecate/delete 三态清理。对称于 `manage-harvest`（写入入口）。
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowledge-audit.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/harvest.md (audit 检测的 artifact 是 harvest 的产物源)
+- @~/.maestro/workflows/specs-add.md (deprecate 操作所需的 `<spec-entry>` 变形)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope（必选）：** `spec` | `knowhow` | `artifact` | `all`
+
+**删除策略**默认 `--interactive`（三态面板逐项决策）；非交互模式 `--mark`（仅打标）/ `--delete`（软删到 `.trash/`）/ `--purge`（物理擦除，仅 artifact 且需双重确认）。
+
+**互斥规则：** `--interactive`、`--mark`、`--delete`、`--purge` 四选一，同时传入多个 → E006。
+
+Flag 全集、scope 对应的扫描路径、Stage 步骤、检测算法定义在 workflow knowledge-audit.md。
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/`, `.workflow/knowhow/`, `.workflow/.trash/knowledge-audit-{timestamp}/`, `.workflow/issues/`, or audit report files (`audit-report-*.md`, `audit-log.jsonl`). NEVER modify source code files.
+</context>
+
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；spec/knowhow 声明 MUST 与代码实际行为一致；每个 finding 的 evidence MUST 包含代码引用（文件:行号）
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Deprecate over delete** — 文本存储首选 `status="deprecated"` 保留历史；NEVER 物理删除 spec/knowhow 文件
+4. **Purge 仅 artifact** — `--purge` MUST NOT 作用于 spec/knowhow scope (E004)
+5. **Rescue before delete** — 未 harvest 的 artifact 删除前 MUST 强制提示先跑 `/manage-harvest` (W002)
+6. **Conflict marker sync** — deprecate/delete 执行时如果目标条目有 conflict-marker，MUST 同步调用 `maestro spec conflict clear` 清除标记
+7. **Mutual exclusion** — `--interactive`/`--mark`/`--delete`/`--purge` 四选一；同时传入多个 MUST trigger E006
+8. **Dry-run safety** — `--dry-run` MUST NOT write any files; `--purge` 与 `--dry-run` 互斥 (E003)
+</invariants>
+
+<execution>
+Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Load → Detect** (Stages 1-2 → Stage 4)
+- REQUIRED: Scope 解析通过，互斥标志校验完成。
+- REQUIRED: 三存储按 scope 加载完成。
+- REQUIRED: 加载已有冲突标记: `maestro spec conflict list` → 合并到 finding 池。
+- BLOCKED if scope 非法或存储不可读: E001/E002。
+
+**GATE 2: Detect → Decision** (Stage 4 → Stage 5)
+- REQUIRED: Finding 池按 P0/P1/P2 分级输出。
+- REQUIRED: 已标记 `contested` 的条目自动归入 P0 finding（来源: conflict-marker）。
+- REQUIRED: 未 harvest 的 artifact 删除前触发抢救确认（W002）。
+- BLOCKED if finding 为空: 无需淘汰，直接输出报告。
+
+**GATE 3: Decision → Mutate** (Stage 5 → Stage 6-7)
+- REQUIRED: Backup tarball 生成于 `.workflow/.trash/knowledge-audit-{timestamp}/`。
+- REQUIRED: 备份成功后方可执行变更。
+- REQUIRED: `--purge` 需双重确认（仅 artifact scope）。
+- BLOCKED if 备份失败: E005，禁止执行变更。
+
+### Execution Constraints
+
+- **Deprecate over delete**: 文本存储首选 `status="deprecated"`，保留历史。
+- **Purge 仅 artifact**: `--purge` 不作用于 spec/knowhow。
+- **Rescue before delete**: 未抽取 artifact 删除前强制提示先 `/manage-harvest`。
+
+### Conflict Resolution Integration
+
+五态决策（扩展自三态 keep/deprecate/delete）：
+
+| 动作 | 适用场景 | 执行 |
+|------|---------|------|
+| `keep` | 内容正确，无需变更 | 写 audit-log ignore 记录 |
+| `contest` | 矛盾真实存在，需进一步审查 | `maestro spec conflict mark <file> <line> --note "<evidence>"` |
+| `supersede` | 内容过时，已有更新版本替代 | `maestro spec supersede <old-sid> --by <new-sid>`（保留演化链） |
+| `deprecate` | 内容过时，无替代版本 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
+| `delete` | 内容明确错误 | 移除 entry + `maestro spec conflict clear <file> <line>` |
+
+**supersede vs deprecate**: supersede 用于有明确替代条目的场景（建立演化链），deprecate 用于无替代条目的场景。
+**关键**: deprecate/delete 执行时，如果目标条目有 conflict-marker，必须同步调用 `maestro spec conflict clear` 清除标记，避免悬空冲突。
+
+### Code-as-Truth 校验（审查核心原则）
+
+**代码是唯一真理源。** Spec/knowhow 中的任何声明，必须与代码实际行为一致。
+
+当 detector 发现 spec 条目声称某行为/规则时：
+1. **代码校验**: grep/read 代码中相关实现，确认 spec 声明是否与代码一致
+2. **不一致处理**:
+   - 代码正确、spec 过时 → `deprecate` 或 `delete` spec 条目
+   - 代码正确、spec 不完整 → `contest` 并建议补充
+   - 代码有 bug、spec 正确 → `keep` spec，生成 issue 修代码
+3. **禁止**: 仅凭 spec 文本判断正确性。每个 finding 的 evidence 必须包含代码引用（文件:行号）
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| 复审淘汰记录 | 查看 `audit-report-{date}.md` |
+| 抢救未抽取 artifact | `/manage-harvest <artifact-id>` |
+| 验证 spec 现状 | `maestro load --type spec` |
+| 查看冲突标记 | `maestro spec conflict list` |
+| 清除已解决冲突 | `maestro spec conflict clear-all <file>` |
+| 查看演化链 | `maestro spec history <sid>` |
+| 知识健康检查 | `maestro spec health` |
+| 回填存量 sid | `maestro spec backfill-sid` |
+| 周期巡检 | `--scope all --report` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` 未初始化 | 先跑 `/maestro-init` |
+| E002 | error | `--scope` 缺失或非法 | 提供 spec/knowhow/artifact/all |
+| E003 | error | `--purge` 与 `--dry-run` 同用 | 二选一 |
+| E004 | error | `--purge` 作用于非 artifact 范围 | purge 仅支持 artifact scope |
+| E005 | error | 备份失败（`.trash/` 写入异常） | 检查磁盘空间与权限，重试 |
+| E006 | error | `--interactive`/`--mark`/`--delete`/`--purge` 同时传入多个 | 四选一，默认 `--interactive` |
+| W001 | warning | 检出冲突但用户选择 keep | 记入 report，不阻断 |
+| W002 | warning | 待删 artifact 无 harvest-log 记录 | 提示先跑 manage-harvest |
+| W003 | warning | 循环 supersedes 链 | 自动断环或交互选保留节点 |
+| W004 | warning | 检测耗时 >120s（大规模 spec 库） | 建议加 `--scope` 收敛或 `--since` 增量 |
+| W005 | warning | LLM detector 不可用 | 降级到正则+图算法子集，跳过 B/G 类语义场景 |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope 正确解析，互斥标志校验通过
+- [ ] 三存储按 scope 加载完成，构建出统一 finding 池
+- [ ] Stage 3 时间线索引建立（mtime ↔ session/milestone 状态）
+- [ ] Stage 4 按 P0/P1/P2 输出 finding 列表
+- [ ] 如非 `--report`：用户对每项做出三态决策
+- [ ] 未 harvest 的 artifact 删除前触发抢救确认
+- [ ] Stage 6 backup tarball 生成于 `.workflow/.trash/`
+- [ ] `deprecate` 通过元数据注入完成（spec/knowhow 文件未被物理删除）
+- [ ] `delete` 移动至 `.trash/`，索引同步更新
+- [ ] `purge` 仅在双重确认通过后执行
+- [ ] `audit-report-{date}.md` + `audit-log.jsonl` 写入完成
+- [ ] 摘要展示三存储变更计数与下一步路由
+</success_criteria>