@ivorycanvas/qamap 0.3.0

package/schema/qamap-manifest.schema.json

@@ -0,0 +1,323 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/IvoryCanvas/qamap/main/schema/qamap-manifest.schema.json",
+  "title": "QAMap verification manifest",
+  "description": "Repository-local verification knowledge used by QAMap to map branch changes to domains, flows, anchors, checks, and E2E draft requirements.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "domains", "flows"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional JSON Schema URL for editor validation."
+    },
+    "version": {
+      "const": 1
+    },
+    "domains": {
+      "type": "array",
+      "description": "Product or repository areas that map changed files to team language.",
+      "items": {
+        "$ref": "#/$defs/domain"
+      },
+      "default": []
+    },
+    "context": {
+      "$ref": "#/$defs/context"
+    },
+    "flows": {
+      "type": "array",
+      "description": "User, API, command, or artifact flows that should shape PR verification evidence.",
+      "items": {
+        "$ref": "#/$defs/flow"
+      },
+      "default": []
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "sourceKind": {
+      "type": "string",
+      "enum": ["declared", "inferred"]
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "criticality": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "runner": {
+      "type": "string",
+      "enum": ["manual", "maestro", "playwright"]
+    },
+    "anchorKind": {
+      "type": "string",
+      "enum": ["api", "component", "file", "route", "test"]
+    },
+    "checkType": {
+      "type": "string",
+      "enum": ["contract", "edge", "failure", "success", "visual"]
+    },
+    "instructionKind": {
+      "type": "string",
+      "enum": ["adr", "agent-instruction", "context", "goal", "qa-runbook", "release-runbook", "runbook", "test-runbook"]
+    },
+    "instructionRole": {
+      "type": "string",
+      "enum": ["agent-skill", "domain-context", "harness-config", "release-policy", "safety-policy", "test-runner", "verification-rubric", "workflow-lifecycle"]
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "confidence", "from"],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/sourceKind"
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        },
+        "from": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "instructionFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "kind", "confidence", "signals"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "$ref": "#/$defs/instructionKind"
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        },
+        "roles": {
+          "type": "array",
+          "description": "Advisory role classification for the context source, such as verification rubric, workflow lifecycle, harness config, or agent skill.",
+          "items": {
+            "$ref": "#/$defs/instructionRole"
+          },
+          "uniqueItems": true,
+          "default": []
+        },
+        "signals": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instructionFiles", "validationCommands", "safetyRules", "source"],
+      "properties": {
+        "instructionFiles": {
+          "type": "array",
+          "description": "Advisory context files used to bootstrap manifest quality, such as CONTEXT.md, ADRs, goals, agent instructions, and QA runbooks.",
+          "items": {
+            "$ref": "#/$defs/instructionFile"
+          },
+          "default": []
+        },
+        "validationCommands": {
+          "type": "array",
+          "description": "Validation commands inferred from context files. These are hints until reviewed.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
+        },
+        "safetyRules": {
+          "type": "array",
+          "description": "Safety or workflow rules inferred from context files. These are advisory and may not be product truth.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
+        },
+        "source": {
+          "$ref": "#/$defs/source"
+        }
+      }
+    },
+    "domain": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "paths", "criticality", "source"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "paths": {
+          "type": "array",
+          "description": "Glob-like path patterns relative to the manifest root.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "criticality": {
+          "$ref": "#/$defs/criticality"
+        },
+        "source": {
+          "$ref": "#/$defs/source"
+        }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source"],
+      "properties": {
+        "route": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "$ref": "#/$defs/sourceKind"
+        }
+      }
+    },
+    "anchor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source", "confidence"],
+      "anyOf": [
+        { "required": ["path"] },
+        { "required": ["route"] },
+        { "required": ["symbol"] }
+      ],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/anchorKind"
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "route": {
+          "type": "string",
+          "minLength": 1
+        },
+        "symbol": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "$ref": "#/$defs/sourceKind"
+        },
+        "confidence": {
+          "$ref": "#/$defs/confidence"
+        }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "type"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "$ref": "#/$defs/checkType"
+        },
+        "selector": {
+          "type": "string",
+          "description": "Optional stable selector hint used when QAMap turns this check into a draft step, such as [data-testid=coupon-input] or role=button:Apply.",
+          "minLength": 1
+        },
+        "value": {
+          "type": "string",
+          "description": "Optional sample value for input-like checks, such as WELCOME10 or qa@example.com.",
+          "minLength": 1
+        },
+        "steps": {
+          "type": "array",
+          "description": "Optional concrete human-readable steps for this check. QAMap uses them before falling back to title parsing.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
+        }
+      }
+    },
+    "flow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "anchors", "checks", "source"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "domain": {
+          "$ref": "#/$defs/id"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "entry": {
+          "$ref": "#/$defs/entry"
+        },
+        "runner": {
+          "$ref": "#/$defs/runner"
+        },
+        "anchors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/anchor"
+          },
+          "minItems": 1
+        },
+        "checks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/check"
+          },
+          "minItems": 1
+        },
+        "source": {
+          "$ref": "#/$defs/source"
+        }
+      }
+    }
+  }
+}

package/schema/qamap.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/IvoryCanvas/qamap/main/schema/qamap.schema.json",
+  "title": "QAMap configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "failOn": {
+      "$ref": "#/$defs/severity",
+      "description": "Exit with code 1 when findings at this severity or higher are present."
+    },
+    "ignoreRules": {
+      "type": "array",
+      "description": "Rule ids to suppress for this repository.",
+      "items": {
+        "$ref": "#/$defs/ruleId"
+      },
+      "uniqueItems": true
+    },
+    "maxFiles": {
+      "type": "integer",
+      "description": "Maximum number of repository files QAMap will inspect.",
+      "minimum": 1
+    },
+    "severity": {
+      "type": "object",
+      "description": "Rule-specific severity overrides.",
+      "additionalProperties": {
+        "$ref": "#/$defs/severity"
+      },
+      "propertyNames": {
+        "$ref": "#/$defs/ruleId"
+      }
+    },
+    "validationCommands": {
+      "type": "array",
+      "description": "Project-specific validation commands to show in test-plan, eval, verify, and GitHub Action reports.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "ruleId": {
+      "type": "string",
+      "pattern": "^CW[0-9]{3}$"
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "low", "medium", "high"]
+    }
+  }
+}

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

@@ -0,0 +1,81 @@
+---
+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.
+---
+
+# QAMap PR QA
+
+Use QAMap as a final local QA pass before presenting a pull request for human review.
+
+## Workflow
+
+1. Detect the comparison base.
+   - Prefer the target PR base branch when known.
+   - Otherwise use `origin/main`, then `origin/master`, then the repository default branch.
+2. Run QAMap from the repository root. Prefer the compact agent format — it carries the same decision content as the markdown report in a fraction of the tokens:
+
+   ```sh
+   pnpm dlx @ivorycanvas/qamap qa . --base <base> --head HEAD --format agent
+   ```
+
+   For an installed project, prefer:
+
+   ```sh
+   pnpm exec qamap qa . --base <base> --head HEAD --format agent
+   ```
+
+   Drop `--format agent` when a human will read the output directly; the default markdown report is written for people.
+
+3. If the repository is a monorepo and the changed files are clearly inside one package, run a scoped pass too:
+
+   ```sh
+   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:
+
+   ```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, 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
+
+- 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.
+- 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.
+- 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.
+
+## Manifest Repair
+
+When the recommendation is wrong or too broad, do not repeatedly re-prompt for the same QA context. Ask the maintainer which domain, flow, anchor, or check should be corrected.
+
+If the team accepts QAMap for ongoing use, suggest this follow-up:
+
+```sh
+pnpm exec qamap manifest init .
+```
+
+Then humans should review `.qamap/manifest.yaml` and keep only durable team QA language.
+
+## Handoff Template
+
+```txt
+QAMap QA
+- Affected flow:
+- Suggested E2E/checklist:
+- Missing evidence:
+- Validation command:
+- Manifest repair needed:
+```