@ivorycanvas/qamap 0.3.2 → 0.3.4

package/schema/qamap-agent.schema.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/IvoryCanvas/qamap/main/schema/qamap-agent.schema.json",
+  "title": "QAMap agent QA summary (qamap.qa v1)",
+  "description": "The single-line JSON object printed by `qamap qa --format agent`. Within schema version 1, fields are only ever added — existing fields are never removed or retyped. A breaking change bumps schema.version to 2.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema",
+    "base",
+    "head",
+    "project",
+    "runner",
+    "manifest",
+    "readiness",
+    "testSuite",
+    "flows",
+    "requiredEvidence",
+    "recommendedEvidenceCount",
+    "requiredBootstrap",
+    "prChecklist",
+    "commands"
+  ],
+  "properties": {
+    "schema": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "qamap.qa" },
+        "version": { "const": 1 }
+      }
+    },
+    "base": {
+      "type": "string",
+      "description": "Git ref the diff was computed against."
+    },
+    "head": {
+      "type": "string",
+      "description": "Git ref of the change under review."
+    },
+    "project": {
+      "type": "string",
+      "description": "Detected project type, for example web, react-native, node, python, unknown."
+    },
+    "runner": {
+      "type": "string",
+      "enum": ["maestro", "playwright", "manual"],
+      "description": "Recommended E2E runner for this repository."
+    },
+    "manifest": {
+      "type": ["string", "null"],
+      "description": "Path of the verification manifest in use, or null when the run used repo signals and the PR diff only."
+    },
+    "readiness": {
+      "type": "object",
+      "required": ["score", "level"],
+      "properties": {
+        "score": { "type": "number", "minimum": 0, "maximum": 100 },
+        "level": {
+          "type": "string",
+          "enum": ["ready", "near-runnable", "needs-work", "blocked"],
+          "description": "Stable machine value; human reports render this as a stage on a four-step journey."
+        }
+      }
+    },
+    "testSuite": {
+      "type": "object",
+      "required": ["present", "files"],
+      "properties": {
+        "present": { "type": "boolean" },
+        "files": { "type": "number", "minimum": 0 }
+      }
+    },
+    "firstDraftCommand": {
+      "type": "string",
+      "description": "One command that creates the first E2E draft. Only present when the repository has no test suite and the diff reaches a product journey."
+    },
+    "flows": {
+      "type": "array",
+      "description": "Affected user flows derived from the diff, most relevant first (capped).",
+      "items": {
+        "type": "object",
+        "required": ["title", "source", "draft", "steps", "selectors"],
+        "properties": {
+          "title": { "type": "string" },
+          "source": {
+            "type": "string",
+            "description": "Where the flow came from, for example verification-manifest, core-flow, domain-language, heuristic."
+          },
+          "draft": { "type": "string", "description": "Path of the fallback draft artifact for this flow. When verificationMode is present, run existing repository evidence first instead of generating it by default." },
+          "verificationMode": {
+            "type": "string",
+            "enum": ["existing-test-evidence", "configuration", "documentation", "generated-artifact"],
+            "description": "Why this flow should validate existing evidence instead of generating a new product-journey E2E draft."
+          },
+          "runnable": {
+            "type": "string",
+            "enum": ["runnable-candidate", "near-runnable", "review-only"],
+            "description": "How trustworthy the generated draft is as an executable test. Absent when not evaluated."
+          },
+          "entry": { "type": "string", "description": "Best entrypoint hint (route or screen). Absent when unknown." },
+          "changedFiles": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Changed or import-reached files that support this flow mapping (capped)."
+          },
+          "reviewQuestion": {
+            "type": "string",
+            "description": "The concrete question a reviewer should answer before merge."
+          },
+          "successSignal": {
+            "type": "string",
+            "description": "The observable result that would prove the flow still works."
+          },
+          "steps": { "type": "array", "items": { "type": "string" } },
+          "selectors": { "type": "array", "items": { "type": "string" } },
+          "existingEvidence": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Changed test files to execute instead of generating another draft. Present for test-evidence-only changes."
+          },
+          "evidence": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Short reasons and repository facts behind the mapping (capped)."
+          }
+        }
+      }
+    },
+    "requiredEvidence": {
+      "type": "array",
+      "description": "QA evidence the change still needs before merge (required priority only, capped at 8).",
+      "items": {
+        "type": "object",
+        "required": ["flow", "kind", "title"],
+        "properties": {
+          "flow": { "type": "string" },
+          "kind": { "type": "string" },
+          "title": { "type": "string" }
+        }
+      }
+    },
+    "recommendedEvidenceCount": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Count of recommended-priority evidence items not listed here; run without --format agent to see them."
+    },
+    "requiredBootstrap": {
+      "type": "array",
+      "description": "Setup steps that must happen before drafts can be treated as regression coverage (capped at 3).",
+      "items": {
+        "type": "object",
+        "required": ["title", "action"],
+        "properties": {
+          "title": { "type": "string" },
+          "action": { "type": "string" }
+        }
+      }
+    },
+    "prChecklist": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Ready-to-paste PR checklist lines (capped)."
+    },
+    "commands": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Suggested commands to run next, most useful first (capped at 4)."
+    }
+  }
+}

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

@@ -25,6 +25,7 @@ Use QAMap as a final local QA pass before presenting a pull request for human re
    ```
 
    Drop `--format agent` when a human will read the output directly; the default markdown report is written for people.
+   The agent JSON is a versioned contract (`schema: qamap.qa` v1, additive-only): see docs/agent-format.md in the QAMap repository.
 
 3. If the repository is a monorepo and the changed files are clearly inside one package, run a scoped pass too:
 
@@ -45,7 +46,7 @@ Use QAMap as a final local QA pass before presenting a pull request for human re
    - `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, read the `PR Comment Draft`, `Missing Evidence Before Trusting This PR`, and `PR Checklist` sections.
+   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.
 6. Include the useful parts in the PR body, review note, or handoff summary.
 
 ## Output Rules