maestro-flow 0.5.2 → 0.5.31

package/.claude/skills/insight-challenge/specs/challenge-protocol.md

@@ -0,0 +1,154 @@
+# Challenge Protocol Specification
+
+## Overview
+
+This protocol defines the systematic approach to challenging code quality findings. The goal is to ensure findings are accurate before action is taken, reducing false positives and wasted effort.
+
+## Challenge Methodology
+
+### Step 1: Claim Decomposition
+
+Break the finding into atomic, verifiable claims:
+
+1. **Existence claims**: "X exists/does not exist in file Y"
+2. **Behavior claims**: "Function X does Y when Z"
+3. **Structure claims**: "Type X has N members"
+4. **Conformance claims**: "Implementation deviates from design by X"
+5. **Numeric claims**: "Missing N items (expected M, found K)"
+
+Each claim must be independently verifiable.
+
+### Step 2: Evidence Collection
+
+For each claim, collect:
+
+1. **Primary evidence**: Direct source code reading
+2. **Secondary evidence**: Related files, imports, type definitions
+3. **Design evidence**: Referenced design documents
+4. **Usage evidence**: How the code is actually used
+
+Evidence hierarchy:
+- Source code > Design docs > Comments > Assumptions
+
+### Step 3: Adversarial Analysis
+
+Apply these challenge strategies:
+
+#### Strategy A: Direct Verification
+Read the exact file and line referenced. Does the claim match reality?
+
+```
+Claim: "Line 58: type X is missing"
+Action: Read line 58 of the file
+Result: Line 58 shows type X IS present → claim overturned
+```
+
+#### Strategy B: Context Expansion
+The claim may be technically correct but misleadingly decontextualized.
+
+```
+Claim: "Function X has no error handling"
+Action: Read the full function and its callers
+Result: Error handling is done by callers → claim weakened
+```
+
+#### Strategy C: Scope Correction
+The claim may confuse different scopes or namespaces.
+
+```
+Claim: "28 edge types required, only 21 found"
+Action: Check what "28" refers to in design docs
+Result: 28 = language types, not edge types → claim overturned
+```
+
+#### Strategy D: Temporal Check
+The claim may reference outdated code.
+
+```
+Claim: "File X uses deprecated API Y"
+Action: Check git history and current code
+Result: API was updated last week → claim overturned
+```
+
+#### Strategy E: Completeness Check
+The claim may be partially correct but incomplete.
+
+```
+Claim: "Type X is missing from union"
+Action: Check all union members
+Result: X is present but Y is actually missing → claim weakened
+```
+
+### Step 4: Verdict Determination
+
+Use this decision tree:
+
+```
+Is the primary claim factually incorrect?
+  ├─ Yes → verdict = "overturned"
+  └─ No → Is the severity/scope overstated?
+       ├─ Yes → verdict = "weakened"
+       └─ No → Is the claim accurate?
+            ├─ Yes → verdict = "confirmed"
+            └─ Uncertain → verdict = "weakened" (lower confidence)
+```
+
+### Step 5: Confidence Scoring
+
+| Confidence | Meaning |
+|------------|---------|
+| 90-100% | Clear, unambiguous evidence |
+| 70-89% | Strong evidence with minor uncertainty |
+| 50-69% | Mixed evidence; judgment call |
+| Below 50% | Insufficient evidence; recommend further investigation |
+
+Factors affecting confidence:
+- Source code clarity
+- Design doc availability
+- Claim specificity
+- Evidence completeness
+
+## Anti-Patterns
+
+### 1. Confirmation Bias
+**Wrong**: Looking only for evidence that supports the finding
+**Right**: Actively seeking counter-evidence first
+
+### 2. Manufactured Doubt
+**Wrong**: Challenging findings without real counter-evidence
+**Right**: Only challenge when evidence genuinely contradicts
+
+### 3. Nitpicking
+**Wrong**: Challenging trivial details while ignoring core issues
+**Right**: Focus on claims that affect the finding's validity
+
+### 4. Scope Creep
+**Wrong**: Expanding the challenge beyond the finding's claims
+**Right**: Address only what the finding asserts
+
+## Output Quality Criteria
+
+A good challenge report:
+
+1. **Specific**: References exact file paths and line numbers
+2. **Verifiable**: Counter-evidence can be independently checked
+3. **Fair**: Acknowledges supporting evidence when present
+4. **Actionable**: Provides clear recommendation
+5. **Proportional**: Confidence matches evidence strength
+
+## Integration Points
+
+### With Quality Pipeline
+- Challenge can be triggered automatically for high-severity findings
+- Results feed back into finding confidence scores
+- Overturned findings are flagged for template improvement
+
+### With Knowledge System
+- Confirmed findings can be captured as knowhow
+- Challenge patterns can be codified as review specs
+- Common false-positive patterns become learning material
+
+### With Team Skills
+- Challenge can be delegated to specialized agents
+- Results inform team scoring and convergence
+- Adversarial patterns align with team-adversarial-swarm

package/.claude/skills/insight-challenge/specs/verdict-schema.md

@@ -0,0 +1,239 @@
+# Verdict Schema Specification
+
+## Overview
+
+This document defines the structured output format for insight challenge verdicts. The schema ensures consistent, machine-readable results that can be consumed by downstream systems.
+
+## Verdict JSON Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["finding_id", "challenge_result", "confidence", "reasoning"],
+  "properties": {
+    "finding_id": {
+      "type": "string",
+      "description": "Original finding identifier"
+    },
+    "challenge_result": {
+      "type": "string",
+      "enum": ["overturned", "weakened", "confirmed"],
+      "description": "Verdict of the challenge"
+    },
+    "confidence": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "Confidence score (0-100)"
+    },
+    "reasoning": {
+      "type": "string",
+      "description": "Detailed explanation of the verdict"
+    },
+    "counter_evidence": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Evidence that contradicts the finding"
+    },
+    "supporting_evidence": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Evidence that supports the finding"
+    },
+    "adjusted_severity": {
+      "type": "string",
+      "enum": ["none", "critical", "high", "medium", "low"],
+      "description": "Recommended severity after challenge"
+    },
+    "recommendation": {
+      "type": "string",
+      "description": "Recommended action"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "challenge_duration_ms": { "type": "integer" },
+        "files_reviewed": { "type": "array", "items": { "type": "string" } },
+        "design_docs_checked": { "type": "array", "items": { "type": "string" } },
+        "challenge_strategies_applied": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}
+```
+
+## Field Definitions
+
+### finding_id
+- **Type**: string
+- **Required**: yes
+- **Description**: The original finding identifier (e.g., "HIGH-01", "CRIT-03")
+- **Example**: "HIGH-01"
+
+### challenge_result
+- **Type**: string (enum)
+- **Required**: yes
+- **Values**:
+  - `overturned`: Finding is factually incorrect; source code directly contradicts claims
+  - `weakened`: Finding is partially correct but overstated, misscoped, or missing context
+  - `confirmed`: Finding is accurate; source code supports all claims
+
+### confidence
+- **Type**: integer (0-100)
+- **Required**: yes
+- **Description**: How confident the challenger is in the verdict
+- **Scale**:
+  - 90-100: Clear, unambiguous evidence
+  - 70-89: Strong evidence with minor uncertainty
+  - 50-69: Mixed evidence; judgment call
+  - Below 50: Insufficient evidence
+
+### reasoning
+- **Type**: string
+- **Required**: yes
+- **Description**: Detailed explanation of why the verdict was reached
+- **Should include**:
+  - Summary of the original claim
+  - What evidence was found
+  - Why the evidence supports the verdict
+  - Any caveats or limitations
+
+### counter_evidence
+- **Type**: array of strings
+- **Required**: no (but expected for overturned/weakened)
+- **Description**: Specific evidence that contradicts the finding
+- **Format**: Each item should reference a specific file and line
+- **Example**: ["src/types.ts line 64: 'resolves' IS declared in KnowledgeEdgeKind"]
+
+### supporting_evidence
+- **Type**: array of strings
+- **Required**: no (but expected for confirmed)
+- **Description**: Specific evidence that supports the finding
+- **Format**: Same as counter_evidence
+
+### adjusted_severity
+- **Type**: string (enum)
+- **Required**: no
+- **Values**:
+  - `none`: Finding should be dismissed entirely
+  - `critical`, `high`, `medium`, `low`: Adjusted severity level
+- **Description**: Recommended severity after considering challenge evidence
+- **Default**: Original severity if not specified
+
+### recommendation
+- **Type**: string
+- **Required**: no
+- **Description**: Recommended next action
+- **Examples**:
+  - "Dismiss this finding; the claimed gap does not exist"
+  - "Downgrade to medium severity; the issue exists but is less critical than claimed"
+  - "Confirm and prioritize; the finding is accurate and important"
+
+### metadata
+- **Type**: object
+- **Required**: no
+- **Description**: Additional context about the challenge process
+- **Fields**:
+  - `challenge_duration_ms`: Time spent on the challenge
+  - `files_reviewed`: List of files examined
+  - `design_docs_checked`: Design documents consulted
+  - `challenge_strategies_applied`: Which challenge strategies were used
+
+## Example Verdicts
+
+### Overturned Finding
+
+```json
+{
+  "finding_id": "HIGH-01",
+  "challenge_result": "overturned",
+  "confidence": 97,
+  "reasoning": "The finding's central claim is factually incorrect. Both 'resolves' and 'documents' ARE declared in KnowledgeEdgeKind in types.ts (lines 64 and 61 respectively). The '28 edge types' design requirement is a misattribution -- the design doc specifies 12 CodeEdgeKind + 8 KnowledgeEdgeKind = 20, and the implementation has 21.",
+  "counter_evidence": [
+    "types.ts lines 58-67: KnowledgeEdgeKind explicitly declares all 9 types including 'resolves' (L64) and 'documents' (L61)",
+    "Design doc plan-maestrograph.md L1327: specifies '12 + 8 种知识关系' = 20 total, not 28",
+    "The '28' number in the finding matches LANGUAGES constant (L1344), not edge types"
+  ],
+  "supporting_evidence": [],
+  "adjusted_severity": "none",
+  "recommendation": "Dismiss this finding; the claimed type gap does not exist"
+}
+```
+
+### Weakened Finding
+
+```json
+{
+  "finding_id": "MED-02",
+  "challenge_result": "weakened",
+  "confidence": 75,
+  "reasoning": "The finding correctly identifies that function X lacks input validation, but overstates the severity. The function is only called internally with pre-validated data, reducing the actual risk.",
+  "counter_evidence": [
+    "src/service.ts: Function X is only called from Y() which validates inputs",
+    "No external API exposes this function directly"
+  ],
+  "supporting_evidence": [
+    "src/utils.ts line 45: Function X确实没有输入验证"
+  ],
+  "adjusted_severity": "low",
+  "recommendation": "Add defensive validation as a best practice, but do not prioritize as high severity"
+}
+```
+
+### Confirmed Finding
+
+```json
+{
+  "finding_id": "CRIT-03",
+  "challenge_result": "confirmed",
+  "confidence": 95,
+  "reasoning": "The finding accurately identifies a SQL injection vulnerability. User input is directly concatenated into the query string without parameterization.",
+  "counter_evidence": [],
+  "supporting_evidence": [
+    "src/db.ts line 78: query = 'SELECT * FROM users WHERE id = ' + userId",
+    "userId comes directly from req.params.id without sanitization"
+  ],
+  "adjusted_severity": "critical",
+  "recommendation": "Immediate fix required; use parameterized queries"
+}
+```
+
+## Batch Processing
+
+When processing multiple findings:
+
+```json
+{
+  "batch_id": "review-2026-06-12",
+  "total_findings": 5,
+  "verdicts": [
+    { "finding_id": "HIGH-01", "challenge_result": "overturned", ... },
+    { "finding_id": "HIGH-02", "challenge_result": "confirmed", ... },
+    { "finding_id": "MED-01", "challenge_result": "weakened", ... }
+  ],
+  "summary": {
+    "overturned": 1,
+    "weakened": 1,
+    "confirmed": 3,
+    "adjusted_effort_savings": "40% of original findings dismissed or downgraded"
+  }
+}
+```
+
+## Integration with Downstream Systems
+
+### Quality Dashboard
+- Verdicts update finding status in quality tracking
+- Confidence scores affect finding priority
+- Adjusted severities trigger appropriate workflows
+
+### Knowledge System
+- Confirmed findings become knowhow candidates
+- Challenge patterns become review specs
+- Overturned findings improve future detection
+
+### Team Skills
+- Verdicts feed into team scoring algorithms
+- Challenge results inform convergence criteria
+- Adversarial patterns enhance team review quality

package/.claude/skills/maestro-help/SKILL.md

@@ -291,7 +291,7 @@ Roadmap > Milestone > Phase > Task
 
 - **Slash 命令**: 56 个（7 个分类）
 - **CLI 命令**: 21 个
-- **Skills**: 10 个（3 个分类）
+- **Skills**: 11 个（4 个分类）
 - **Agents**: 22 个（5 个分类）
 - **Guide 文档**: 17 个
 - **工作流路径**: 6 个合法路径 (Path A-F) + 3 个辅助流程

package/.claude/skills/maestro-help/index/catalog.json

@@ -73,7 +73,8 @@
     {"name": "team-review", "category": "team", "description": "代码审查团队: 多维度扫描和漏洞审查", "source": "../team-review/SKILL.md"},
     {"name": "team-tech-debt", "category": "team", "description": "技术债务团队: 债务识别和清理", "source": "../team-tech-debt/SKILL.md"},
     {"name": "team-testing", "category": "team", "description": "测试团队: 测试规划和执行", "source": "../team-testing/SKILL.md"},
-    {"name": "codify-to-knowhow", "category": "knowledge", "description": "Manifest 驱动的知识资产生成器", "source": "../codify-to-knowhow/SKILL.md"}
+    {"name": "codify-to-knowhow", "category": "knowledge", "description": "Manifest 驱动的知识资产生成器", "source": "../codify-to-knowhow/SKILL.md"},
+    {"name": "insight-challenge", "category": "quality", "description": "对抗性审查 — 质疑发现、验证声明、产出结构化裁决", "source": "../insight-challenge/SKILL.md"}
   ],
   "agents": [
     {"name": "workflow-analyzer", "description": "多维度分析 — 证据评分和推荐", "category": "workflow"},
@@ -124,7 +125,7 @@
   ],
   "categories": {
     "commands": ["core", "pipeline", "milestone", "manage", "quality", "spec", "learn", "wiki", "worktree", "team", "ralph", "ui", "tools"],
-    "skills": ["meta", "team", "knowledge"],
+    "skills": ["meta", "team", "knowledge", "quality"],
     "agents": ["workflow", "team", "planning", "cli", "ui"]
   },
   "guide_files": [

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codify-to-knowhow
-description: Manifest-driven knowledge asset generator — converts structured packages into knowhow + spec entries
+description: "Manifest-driven knowledge asset generator — converts structured packages into knowhow + spec entries"
 argument-hint: "<package-path>"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---

package/.codex/skills/maestro-companion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-companion
-description: Knowledge companion — load context, record companion doc, capture insights, route to skills
+description: "Knowledge companion — load context, record companion doc, capture insights, route to skills"
 argument-hint: "[before|note|after|route] [--task <description>] [--type <task_type>] [--category <cat>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---

package/.codex/skills/maestro-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-help
-description: Maestro Flow command help system — search, browse, recommend commands, skills, agents, CLI tools, and workflows
+description: "Maestro Flow command help system — search, browse, recommend commands, skills, agents, CLI tools, and workflows"
 argument-hint: "[search <keyword>|workflow|skills|agents|cli|新手|下一步|<command-name>]"
 allowed-tools: Read, Grep, Glob, request_user_input
 ---

package/.codex/skills/maestro-impeccable/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-impeccable
-description: Use when designing, auditing, polishing, or improving frontend UI — websites, dashboards, landing pages, components
+description: "Use when designing, auditing, polishing, or improving frontend UI — websites, dashboards, landing pages, components"
 argument-hint: "<command|chain|intent> [target] [flags]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---

package/.codex/skills/maestro-next/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-next
-description: Single-command recommendation — pick the best next skill from the pool and execute it in-context
+description: "Single-command recommendation — pick the best next skill from the pool and execute it in-context"
 argument-hint: "\"<intent>\" [-y] [--dry-run] [--top N] [--list]"
 allowed-tools: Read, Bash, Glob, Grep, request_user_input
 ---

package/.codex/skills/maestro-ralph-beta/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-ralph-beta
-description: Self-running loop controller for adaptive maestro workflow — build, tick, decide in one skill
+description: "Self-running loop controller for adaptive maestro workflow — build, tick, decide in one skill"
 argument-hint: "<intent> [-y] | continue | status"
 allowed-tools:
   - Read