@xera-ai/skills 0.9.8 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @xera-ai/skills
 
+## 0.11.0
+
+## 0.10.0
+
+### Minor Changes
+
+- [#64](https://github.com/xera-ai/xera/pull/64) [`c5aca3c`](https://github.com/xera-ai/xera/commit/c5aca3c95362ca99de6b072e68173933a4a23035) Thanks [@thanhtrinity](https://github.com/thanhtrinity)! - v0.8 — Coverage gap & AC matrix
+
+  QA teams now get an actionable "where to write tests next" surface built on top of the v0.6 project knowledge graph.
+
+  **New skills:**
+
+  - `/xera-coverage` — area-level + AC-level coverage report. Areas classify as UNCOVERED (no POM covers it), STALE (POM exists but no PASS in 30d), or COVERED. Risk-weighted gap list with `--why` drill-down. AC backfill auto-orchestrates on first invocation to map legacy scenarios → ACs via `map-ac-to-scenarios.md` prompt.
+  - `/xera-fill-gap <area>` and `/xera-fill-gap --ticket <TICKET>` — AI-drafted Gherkin scenarios for UNCOVERED areas or unsatisfied ACs. Atomic boundary — produces `.xera/<TICKET>/feature.draft.md`, user iterates and invokes `/xera-script` when ready.
+
+  **HTML viewer Coverage tab** (`/xera-coverage --viewer`):
+
+  - Map sub-tab — vis-network recolors area nodes by status (red/amber/green)
+  - List sub-tab — sortable area table + per-ticket AC gap matrix
+  - Trend sub-tab — inline SVG line chart of UNCOVERED+STALE count over time
+
+  **Graph schema additions:**
+
+  - New node kind `ACNode` (id = `${ticketId}#ac-${index}`)
+  - New edge kind `satisfies` (Scenario → AC, eager from `/xera-script` or lazy from backfill)
+  - New `Snapshot` projections: `acNodes`, `classifications`
+  - New event types `coverage.snapshot` (history for Trend) and `ac-coverage.backfilled` (materializes satisfies edges idempotently)
+
+  **Config additions** (`xera.config.ts`):
+
+  ```ts
+  coverage: {
+    staleAfterDays: 30,           // default
+    criticalAreas: [],             // boost ×2 in risk formula
+    autoSnapshotOnCoverage: true,  // emit trend snapshots
+  }
+  ```
+
+  **Doctor checks added:**
+
+  - Warns when `coverage.staleAfterDays > 90`
+  - Warns when `criticalAreas` slug is missing from snapshot
+  - Warns when a ticket has ACs but no `ACNode` materialized
+
+  **Internals:**
+
+  - 5 new xera-internal subcommands: `coverage-prepare`, `ac-coverage-backfill-{prepare,finalize}`, `fill-gap-{prepare,finalize}`
+  - 2 new prompt templates: `map-ac-to-scenarios.md`, `propose-scenarios.md` (in-scope prompt count now 11)
+  - New `packages/core/src/coverage/` module (pure functions: status, risk, report, why)
+  - 6 golden fixtures in `fixtures/golden-coverage/` covering UNCOVERED, STALE, COVERED, critical-boost, bug-history, AC gap scenarios
+
+  See full spec at `docs/superpowers/specs/2026-05-17-xera-v08-coverage-gap-design.md`.
+
 ## 0.9.8
 
 ## 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/skills",
-  "version": "0.9.8",
+  "version": "0.11.0",
   "files": [
     "*.md",
     "version.json"

package/xera-coverage.md

@@ -0,0 +1,127 @@
+---
+name: xera-coverage
+description: Show area-level and AC-level coverage report for the current xera project; sort by risk; drill-down via --why; optional HTML viewer (v0.8.1+). Available v0.8.0+.
+---
+
+The user invoked `/xera-coverage [--why <area-or-TICKET>] [--all] [--json] [--viewer]`. Read flag arguments and forward to the binary.
+
+This skill walks the project knowledge graph (`.xera/graph/`) to identify untested areas and unsatisfied acceptance criteria. It does NOT modify graph state or run tests — strictly read-only reporting plus an optional snapshot event for trend history.
+
+## Step 1 — Verify project layout
+
+Confirm the cwd is a xera project: `xera.config.ts` exists. If not, surface:
+
+```
+xera.config.ts not found — this command must run inside a xera project.
+```
+
+And STOP.
+
+## Step 2 — Run coverage-prepare
+
+Pass through the user's flags:
+
+```bash
+bun run xera:coverage-prepare [--why <id>] [--all] [--json] [--no-emit-event]
+```
+
+Flag handling:
+
+- **`--why <id>`** — binary prints drill-down to stdout, no files written. Return that output to the user; do not continue to Step 3.
+- **`--json`** — binary prints `report.json` to stdout. Return as-is.
+- **No flag (default), or `--all`** — binary writes `.xera/coverage/report.json` and `.xera/coverage/report.md`, plus emits a `coverage.snapshot` event (unless config disables it).
+
+Exit codes:
+
+- `0` — report generated.
+- `1` — unknown flag passed.
+- `2` — `xera.config.ts` missing or invalid; surface stderr and STOP.
+- `4` — internal error; surface stderr and STOP.
+
+## Step 3 — Detect + run AC backfill if needed
+
+Read `.xera/coverage/report.json`. If `acBackfillNeeded === true`:
+
+### 3a — Assemble unmapped context
+
+```bash
+bun run xera:ac-coverage-backfill-prepare
+```
+
+This writes `.xera/coverage/ac-backfill-input.json` listing tickets that have ACs + scenarios but no `satisfies` edges yet.
+
+If the input file is `{ "tickets": [] }`, skip to Step 4 — there's nothing to backfill (the `acBackfillNeeded` flag in report.json may be a leftover stale state; re-running `coverage-prepare` will refresh it).
+
+### 3b — Invoke the AC-mapping prompt
+
+Mint a fresh per-invocation nonce:
+
+```bash
+bun -e "console.log('XR_' + crypto.randomUUID().replace(/-/g,'').slice(0,12))"
+```
+
+Capture the single-line output as the nonce.
+
+Read `.xera/coverage/ac-backfill-input.json` and `node_modules/@xera-ai/prompts/map-ac-to-scenarios.md`. Generate the AC mapping decisions following that prompt's rules. Wrap the input JSON between two identical `<NONCE>` tags before feeding it to your generation context.
+
+Write the prompt output to `.xera/coverage/ac-backfill-decisions.json`. The output schema is:
+
+```json
+{
+  "mappings": [
+    { "scenarioId": "<id>", "satisfiesAcs": [<indices>], "confidence": <0-1> }
+  ]
+}
+```
+
+### 3c — Materialize the satisfies edges
+
+```bash
+bun run xera:ac-coverage-backfill-finalize
+```
+
+This validates the decisions JSON and emits one `ac-coverage.backfilled` event per ticket. Each event materializes the `satisfies` edges in the graph snapshot.
+
+### 3d — Re-run coverage-prepare
+
+```bash
+bun run xera:coverage-prepare --no-emit-event
+```
+
+This regenerates `.xera/coverage/report.json` with the newly materialized `satisfies` edges. After this, `acBackfillNeeded` should be `false` (or only `true` for tickets the AI declined to map — those are an AI quality issue and need a human eye).
+
+## Step 4 — Print report.md
+
+Read `.xera/coverage/report.md` and print it verbatim to the terminal.
+
+## Step 5 — Handle --viewer
+
+If the user passed `--viewer`, run:
+
+```bash
+bun run xera:graph-render --include-coverage
+```
+
+This regenerates `.xera/graph.html` with a top-level Coverage tab (Map / List / Trend). Print the path so the user knows where to open it:
+
+```
+Coverage HTML viewer ready: .xera/graph.html
+Open in any browser. The Coverage tab is at the top right.
+```
+
+## Step 6 — Print next-step hints
+
+After the report (skip for `--why` and `--json` runs):
+
+```
+Next:
+  /xera-coverage --why <area-or-TICKET>   full breakdown
+  /xera-coverage --viewer                  HTML viewer (v0.8.1)
+  /xera-fill-gap <area>                    draft scenarios (v0.8.2)
+  /xera-fill-gap --ticket <TICKET>         draft AC gap scenarios (v0.8.2)
+```
+
+## Edge cases
+
+- Graph snapshot not present yet: `loadAllEvents` returns `[]` → empty report. That's fine; surface "no events yet, run /xera-fetch on a ticket first" hint after Step 6.
+- Config has invalid `coverage.criticalAreas` slug → binary exits 2 with parse error; surface and STOP.

package/xera-fill-gap.md

@@ -0,0 +1,111 @@
+---
+name: xera-fill-gap
+description: Generative — draft Gherkin scenarios for an UNCOVERED area or the unsatisfied ACs of a specific ticket. Use when you want AI to fill a coverage gap. Available v0.8.2+.
+---
+
+The user invoked one of:
+- `/xera-fill-gap <area>` (area mode — fill an UNCOVERED area)
+- `/xera-fill-gap --ticket <TICKET>` (ticket mode — fill unsatisfied ACs of a specific ticket)
+
+If neither is provided, ask.
+
+This skill does NOT modify graph state, run tests, or auto-chain into `/xera-script`. It produces draft `.feature` files that the user reviews; the user invokes `/xera-script` separately when ready.
+
+## Step 1 — Verify project layout
+
+Confirm `xera.config.ts` exists in cwd. If not, say `xera.config.ts not found — run this inside a xera project.` and STOP.
+
+## Step 2 — Assemble context
+
+Run:
+
+```bash
+bun run xera:fill-gap-prepare {{--area <slug> | --ticket <TICKET>}}
+```
+
+Exit codes:
+- `0` — context written
+- `1` — invalid flags (shouldn't happen if you pass-through user input)
+- `2` — area has no tickets / ticket has no unsatisfied ACs. Surface the stderr and STOP.
+
+The output is `.xera/coverage/<scope>/context.json` where `<scope>` is the area slug or ticket ID.
+
+## Step 3 — Invoke the propose-scenarios prompt
+
+Mint a fresh per-invocation nonce:
+
+```bash
+bun -e "console.log('XR_' + crypto.randomUUID().replace(/-/g,'').slice(0,12))"
+```
+
+Capture the single-line output as the nonce.
+
+Read `.xera/coverage/<scope>/context.json` and `node_modules/@xera-ai/prompts/propose-scenarios.md`. Generate scenario proposals following that prompt's rules. Wrap the context JSON between two identical `<NONCE>` tags before feeding it to your generation context.
+
+Write the prompt output to `.xera/coverage/<scope>/proposals.json`. Schema:
+
+```json
+{
+  "proposals": [
+    {
+      "id": "P1", "ticketId": "<id>", "title": "<title>",
+      "rationale": "<one sentence>",
+      "gherkin": "Scenario: ...\n  Given ...\n  When ...\n  Then ...",
+      "satisfiesAcs": [<indices or empty>]
+    }
+  ]
+}
+```
+
+## Step 4 — Present proposals to user
+
+Read the proposals and print them in a numbered list:
+
+```
+3 candidate scenarios for `<scope>`:
+
+  [P1] PROJ-101 · "Customer pays with Apple Pay"
+       Why: Ticket adds Apple Pay; no scenario tests this path.
+       Preview: Given user is on /checkout · When they select Apple Pay · Then ...
+
+  [P2] PROJ-101 · "Apple Pay declined with no second attempt"
+       Why: ...
+       Preview: ...
+
+  ...
+```
+
+Ask the user: `Pick proposals to draft [comma-separated IDs / all / none]:`
+
+- **none** — STOP. Mention the proposals.json file path so the user can review later.
+- **all** — accept every proposal in proposals.json.
+- **comma-separated IDs** (e.g. `P1, P3`) — accept the named subset.
+
+## Step 5 — Finalize each accepted proposal
+
+For each accepted proposal ID, run:
+
+```bash
+bun run xera:fill-gap-finalize --accept <id> --ticket <proposal.ticketId> --source .xera/coverage/<scope>/proposals.json
+```
+
+If the binary returns exit 3 (`feature.draft.md` already exists), prompt the user: `Overwrite existing draft for <TICKET>? (y/N)`. If yes, re-run with `--force`.
+
+Collect the list of written `.xera/<TICKET>/feature.draft.md` paths.
+
+## Step 6 — Print next-step summary
+
+```
+Drafted N scenario(s):
+  - .xera/PROJ-101/feature.draft.md
+  - ...
+
+Next:
+  Review each feature.draft.md, edit as needed, then run /xera-script <TICKET> when ready.
+```
+
+## Edge cases
+
+- Graph snapshot not present yet — `fill-gap-prepare` will return exit 2; surface message + suggest `/xera-fetch` first.
+- All proposals declined — STOP, no files written, no graph events emitted (the prompt run leaves only `.xera/coverage/<scope>/proposals.json` on disk, which is fine and reviewable).
+- Mixed acceptance / overwrite conflict — handle one at a time; don't abort all on first --force prompt.