maestro-flow 0.5.2 → 0.5.31

package/.agy/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/.agy/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/.agy/skills/learn-follow/SKILL.md

@@ -13,117 +13,117 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional flags.
-
-**Target resolution** (auto-detected):
-| Input | Resolution |
-|-------|-----------|
-| File path (contains `/` or `\`) | Read source file |
-| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
-| Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |
-
-**Flags**:
-- `--depth shallow` (default): key patterns and structure only
-- `--depth deep`: every function, every branch, every assumption
-- `--save-wiki`: create wiki note entry with reading notes
-
-**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
-**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
-</context>
-
-<state_machine>
-
-<states>
-S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
-S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
-S_ORDER        — 确定阅读顺序                                PERSIST: —
-S_READ         — 逐节应用 forcing questions                   PERSIST: —
-S_EXTRACT      — 提取 patterns、cross-ref conventions         PERSIST: —
-S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowhow files
-</states>
-
-<transitions>
-
-S_RESOLVE:
-  → S_CONTEXT     WHEN: target resolved
-  → S_RESOLVE     WHEN: unresolvable                       DO: ask_question with suggestions
-
-S_CONTEXT:
-  → S_ORDER       DO: A_BUILD_CONTEXT_WEB
-
-S_ORDER:
-  → S_READ        DO: A_BUILD_READING_ORDER
-
-S_READ:
-  → S_EXTRACT     DO: A_GUIDED_READ (apply 4 forcing questions per section)
-
-S_EXTRACT:
-  → S_PERSIST     DO: A_EXTRACT_PATTERNS
-
-S_PERSIST:
-  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
-
-</transitions>
-
-<actions>
-
-### A_BUILD_CONTEXT_WEB
-
-| Target type | Context |
-|-------------|---------|
-| Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related |
-| Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) |
-| Directory | List files, identify entry points → build reading order: entry → core → utils → tests |
-
-### A_BUILD_READING_ORDER
-
-- Single file: split by function/class/export boundaries
-- Wiki entry: split by markdown headings
-- Directory: order by dependency (entry points first, leaf last)
-- `--depth shallow`: top-level structure only; `--depth deep`: every body and branch
-
-### A_GUIDED_READ
-
-For each section, apply 4 forcing questions:
-
-| # | Question | Extracts |
-|---|----------|----------|
-| 1 | "What pattern is being used here?" | Design patterns, idioms, conventions |
-| 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options |
-| 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering |
-| 4 | "What would break if this changed?" | Fragility, downstream effects |
-
-### A_EXTRACT_PATTERNS
-
-Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
-Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for spec-add".
-
-Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections.
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| W002 | coding-conventions.md not found | All patterns marked "unknown status" |
-| W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
-</error_codes>
-
-<success_criteria>
-- [ ] 4 forcing questions applied per section
-- [ ] Patterns extracted with file:line anchors and convention cross-ref
-- [ ] Understanding map + spec-entry blocks written
-</success_criteria>
-
-<next_step_routing>
-- Deep pattern dive → `/learn-decompose <path>`
-- Add to specs → `/spec-add coding <description>`
-- Second opinion → `/learn-second-opinion <file>`
-</next_step_routing>
+<purpose>
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path (contains `/` or `\`) | Read source file |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |
+
+**Flags**:
+- `--depth shallow` (default): key patterns and structure only
+- `--depth deep`: every function, every branch, every assumption
+- `--save-wiki`: create wiki note entry with reading notes
+
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`
+</context>
+
+<state_machine>
+
+<states>
+S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
+S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
+S_ORDER        — 确定阅读顺序                                PERSIST: —
+S_READ         — 逐节应用 forcing questions                   PERSIST: —
+S_EXTRACT      — 提取 patterns、cross-ref conventions         PERSIST: —
+S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved
+  → S_RESOLVE     WHEN: unresolvable                       DO: ask_question with suggestions
+
+S_CONTEXT:
+  → S_ORDER       DO: A_BUILD_CONTEXT_WEB
+
+S_ORDER:
+  → S_READ        DO: A_BUILD_READING_ORDER
+
+S_READ:
+  → S_EXTRACT     DO: A_GUIDED_READ (apply 4 forcing questions per section)
+
+S_EXTRACT:
+  → S_PERSIST     DO: A_EXTRACT_PATTERNS
+
+S_PERSIST:
+  → END           DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
+
+</transitions>
+
+<actions>
+
+### A_BUILD_CONTEXT_WEB
+
+| Target type | Context |
+|-------------|---------|
+| Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related |
+| Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) |
+| Directory | List files, identify entry points → build reading order: entry → core → utils → tests |
+
+### A_BUILD_READING_ORDER
+
+- Single file: split by function/class/export boundaries
+- Wiki entry: split by markdown headings
+- Directory: order by dependency (entry points first, leaf last)
+- `--depth shallow`: top-level structure only; `--depth deep`: every body and branch
+
+### A_GUIDED_READ
+
+For each section, apply 4 forcing questions:
+
+| # | Question | Extracts |
+|---|----------|----------|
+| 1 | "What pattern is being used here?" | Design patterns, idioms, conventions |
+| 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options |
+| 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering |
+| 4 | "What would break if this changed?" | Fragility, downstream effects |
+
+### A_EXTRACT_PATTERNS
+
+Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for spec-add".
+
+Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| W002 | coding-conventions.md not found | All patterns marked "unknown status" |
+| W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
+</error_codes>
+
+<success_criteria>
+- [ ] 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors and convention cross-ref
+- [ ] Understanding map + spec-entry blocks written
+</success_criteria>
+
+<next_step_routing>
+- Deep pattern dive → `/learn-decompose <path>`
+- Add to specs → `/spec-add coding <description>`
+- Second opinion → `/learn-second-opinion <file>`
+</next_step_routing>