@ivorycanvas/qamap 0.3.4 → 0.4.0

package/schema/qamap-behavior.schema.json

@@ -0,0 +1,307 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/IvoryCanvas/qamap/main/schema/qamap-behavior.schema.json",
+  "title": "QAMap Behavior Graph",
+  "description": "Framework-neutral, deterministic behavior evidence derived from a repository change.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "root", "base", "head", "surface", "adapters", "nodes", "edges", "diagnostics", "summary"],
+  "properties": {
+    "$schema": {
+      "const": "https://raw.githubusercontent.com/IvoryCanvas/qamap/main/schema/qamap-behavior.schema.json"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "workspaceRoot": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base": {
+      "type": "string",
+      "minLength": 1
+    },
+    "head": {
+      "type": "string",
+      "minLength": 1
+    },
+    "surface": {
+      "$ref": "#/$defs/surface"
+    },
+    "adapters": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/adapterRun"
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/node"
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/edge"
+      }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/diagnostic"
+      }
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    }
+  },
+  "$defs": {
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "surface": {
+      "type": "string",
+      "enum": ["web", "mobile", "api", "cli", "artifact", "unknown"]
+    },
+    "nodeKind": {
+      "type": "string",
+      "enum": ["domain", "flow", "surface", "action", "state", "effect", "contract", "assertion", "fixture", "locator", "source"]
+    },
+    "edgeKind": {
+      "type": "string",
+      "enum": ["contains", "enters-at", "precedes", "expects", "uses-fixture", "located-by", "implemented-by", "impacts"]
+    },
+    "evidenceKind": {
+      "type": "string",
+      "enum": ["commit", "diff", "source", "manifest", "selector", "fixture", "test", "inference"]
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "value"],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/evidenceKind"
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "impact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "changedFiles"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["direct", "propagated"]
+        },
+        "changedFiles": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "attributeValue": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "number" },
+        { "type": "boolean" },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "label", "confidence", "evidence"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "$ref": "#/$defs/nodeKind"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidence"
+          }
+        },
+        "attributes": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/attributeValue"
+          }
+        },
+        "impact": {
+          "$ref": "#/$defs/impact"
+        }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "from", "to", "confidence", "evidence"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "$ref": "#/$defs/edgeKind"
+        },
+        "from": {
+          "type": "string",
+          "minLength": 1
+        },
+        "to": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidence"
+          }
+        }
+      }
+    },
+    "adapterRun": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "status", "detection", "nodeCount", "edgeCount"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": ["used", "skipped", "failed"]
+        },
+        "detection": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["confidence", "reason", "evidence"],
+          "properties": {
+            "confidence": {
+              "type": "string",
+              "enum": ["none", "low", "medium", "high"]
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1
+            },
+            "evidence": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "nodeCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "edgeCount": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "message"],
+      "properties": {
+        "severity": {
+          "type": "string",
+          "enum": ["info", "warning"]
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "adapterId": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes", "edges", "impactedNodes", "byKind"],
+      "properties": {
+        "nodes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "edges": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "impactedNodes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "byKind": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["domain", "flow", "surface", "action", "state", "effect", "contract", "assertion", "fixture", "locator", "source"],
+          "properties": {
+            "domain": { "type": "integer", "minimum": 0 },
+            "flow": { "type": "integer", "minimum": 0 },
+            "surface": { "type": "integer", "minimum": 0 },
+            "action": { "type": "integer", "minimum": 0 },
+            "state": { "type": "integer", "minimum": 0 },
+            "effect": { "type": "integer", "minimum": 0 },
+            "contract": { "type": "integer", "minimum": 0 },
+            "assertion": { "type": "integer", "minimum": 0 },
+            "fixture": { "type": "integer", "minimum": 0 },
+            "locator": { "type": "integer", "minimum": 0 },
+            "source": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/qamap-pr-qa/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qamap-pr-qa
-description: Local-first PR QA workflow for AI-assisted code changes. Use when an agent is preparing, updating, or reviewing a pull request and needs to run QAMap to identify affected flows, recommended E2E or manual QA work, missing fixture/selector/assertion/runner evidence, PR checklist items, and optional manifest repair guidance without calling a cloud service or LLM.
+description: Local zero-LLM PR QA workflow. Use when an agent is preparing, updating, or reviewing a pull request and needs to derive commit-backed change intent, behavior lifecycle, runner-independent QA scenarios, affected flows, automation drafts, missing evidence, and optional manifest repair guidance without calling a cloud service or LLM.
 ---
 
 # QAMap PR QA
@@ -33,28 +33,30 @@ Use QAMap as a final local QA pass before presenting a pull request for human re
    pnpm dlx @ivorycanvas/qamap qa <package-path> --workspace-root . --base <base> --head HEAD
    ```
 
-4. If QAMap prints `First E2E Draft Bootstrap`, treat it as an instruction to create the starter draft before writing broad QA notes:
+4. Read and verify intent before generating code. In agent format:
+   - `intents[]` — commit/diff evidence, confidence, `reviewRequired`, ordered lifecycle, and primary/failure/boundary/state-transition scenarios.
+   - If `reviewRequired` is true or the lifecycle conflicts with the PR, ask a human to confirm the intended behavior before promoting a draft.
+   - `flows[]` — affected flows with `draft` path, `runnable` status, entry route, capped steps, and selectors.
+   - `requiredEvidence[]` — evidence that must exist before the PR can be trusted; `recommendedEvidenceCount` for the rest.
+   - `requiredBootstrap[]` — setup steps that block trusting generated drafts.
+   - `prChecklist[]` and `commands[]` — checklist lines and validation commands for the handoff.
+
+5. If the intent is credible and QAMap prints `First E2E Draft Bootstrap`, create the starter draft instead of stopping at broad QA notes:
 
    ```sh
    pnpm exec qamap e2e setup . --runner <runner>
    ```
 
    Use the exact create command from the output when it differs.
-5. Read the output. In agent format (single minified JSON object, `schema.name` = `qamap.qa`):
-   - `flows[]` — affected flows with `draft` path, `runnable` status, `entry` route, capped `steps` and `selectors`.
-   - `requiredEvidence[]` — evidence that must exist before the PR can be trusted; `recommendedEvidenceCount` for the rest.
-   - `requiredBootstrap[]` — setup steps that block trusting generated drafts.
-   - `firstDraftCommand` — present only when the repo has no test suite; run it to create the first starter draft.
-   - `prChecklist[]` and `commands[]` — checklist lines and validation commands for the handoff.
-   In markdown format, start from `At a Glance` (affected flows, the single next command, blocking items), then read the `PR Comment Draft`, `Missing Evidence Before Trusting This PR`, and `PR Checklist` sections.
+   `firstDraftCommand` is present only when the repo has no test suite; run it to create the first starter draft. In markdown format, start from `At a Glance` and `Change Intent Evidence`, then read the PR comment, missing evidence, and checklist sections.
 6. Include the useful parts in the PR body, review note, or handoff summary.
 
 ## Output Rules
 
 - Treat QAMap output as QA planning evidence, not proof that browser, device, API, or manual QA passed.
-- Preserve the affected flow, suggested E2E/checklist path, missing evidence, and validation command in the handoff.
+- Preserve change intent, confidence, lifecycle, QA scenarios, affected flow, suggested E2E/checklist path, missing evidence, and validation command in the handoff.
 - Prefer creating the suggested starter E2E draft over only reporting that a draft is needed.
-- If QAMap recommends Playwright, Maestro, or manual QA, do not force a different runner unless the repository already has stronger runner evidence.
+- Treat Playwright, Maestro, and manual output as adapters after QA design. Do not let runner selection replace review of the inferred intent and scenarios.
 - If the output is `review only` or `near runnable`, explain what blocks it from becoming trusted regression evidence.
 - If `qamap qa` says no manifest was found, do not stop. The first run is allowed to be manifest-free.
 
@@ -74,6 +76,9 @@ Then humans should review `.qamap/manifest.yaml` and keep only durable team QA l
 
 ```txt
 QAMap QA
+- Change intent and confidence:
+- Behavior lifecycle:
+- Required QA scenarios:
 - Affected flow:
 - Suggested E2E/checklist:
 - Missing evidence: