bigpowers 2.87.4 → 2.87.5

package/.gemini/extensions/bigpowers/commands/prompts/gate-trace.md

@@ -0,0 +1,91 @@
+---
+name: gate-trace
+description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability."
+---
+
+# Gate Trace
+
+Deterministic quality gate that combines traceability coverage and blind-spot data into a single PASS/FAIL/CONCERNS/WAIVED decision before release.
+
+## Decision Rules
+
+| Rule | Condition | Verdict |
+|------|-----------|---------|
+| R1 | Any undone story with 0 code tags | FAIL |
+| R2 | Any story done but no verify evidence | CONCERNS |
+| R3 | P0 story (top WSJF quartile) with 0% coverage | FAIL |
+| R4 | Overall coverage < 60% | CONCERNS |
+| R6 | P0 story + eNN-TEST_PLAN_LATEST.md exists + zero SC-eNNsYY-P0-* in test files | CONCERNS |
+| R5 | Overall ≥ 80% + no critical gaps + all verify → PASS | PASS |
+
+## Oracle Confidence Downgrade
+
+TEA-inspired: if trace links rely on heuristics rather than explicit tags, confidence drops.
+
+| Heuristic Ratio | Downgrade |
+|-----------------|-----------|
+| > 50% links from heuristics (file-name or task-reference) | One level (PASS→CONCERNS, CONCERNS→FAIL) |
+| > 80% links from heuristics | Two levels (PASS→FAIL, CONCERNS→FAIL) |
+
+## Process
+
+1. **Pre-flight:** Ensure `scripts/trace-stories.sh --json` has been run (produces `specs/traceability-matrix.json`). If not present, run it.
+2. Ensure `scripts/check-blind-spots.sh` has been run (produces `specs/blind-spots.json`). If not present, run it.
+3. Read `specs/traceability-matrix.json` and `specs/blind-spots.json`.
+4. Apply decision rules R1–R5 in order (first match wins).
+5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`.
+6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details."
+7. Output verdict + rationale to stdout.
+8. **Adversarial refute check (e45s32):** Before emitting PASS, attempt to **refute** the verdict — list at least one concrete traceability gap that would block merge if it were real. If the gap is real, downgrade the verdict. Rubber-stamping is prohibited; every PASS must survive one refutation attempt.
+9. **Completeness critic (e45s05)** — Run adversarial gap-finding:
+
+```bash
+bash scripts/lib/completeness-critic.sh
+```
+
+Classify output as **BLOCKER / WARNING / FILLED**. **BLOCKER overrides any PASS verdict → FAIL.** Append critic summary to rationale.
+10. Update `specs/execution-status.yaml` with gate-trace result.
+
+## Verdict Semantics
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| PASS | All gates satisfied | Proceed with merge |
+| CONCERNS | Non-critical issues found | Requires explicit human override in `state.yaml` |
+| FAIL | Critical traceability gap | Block merge — fix gap first |
+| WAIVED | Cannot evaluate (missing inputs) | Skip gate — data not available |
+
+## Output Format
+
+```yaml
+gate_trace:
+  verdict: PASS|CONCERNS|FAIL|WAIVED
+  generated_at: "<ISO 8601>"
+  rationale: "<human-readable explanation>"
+  heuristic_ratio: <0.0–1.0>
+  downgrade_applied: <true|false>
+```
+
+## Integration Points
+
+- **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
+- **sync-skills.yml** — runs `trace-stories.sh --strict` as its "Traceability gate" step (FAIL
+  blocks pipeline), which shares this skill's coverage data (`traceability-matrix.json`) but
+  does not invoke a gate-trace PASS/CONCERNS/FAIL/WAIVED verdict directly.
+- **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
+
+## References
+
+- BMAD TEA traceability approach (market survey 2026-07-02).
+- scripts/trace-stories.sh (e38s01) — produces traceability-matrix.json.
+- scripts/check-blind-spots.sh (e38s04) — produces blind-spots.json.
+- specs/execution-status.yaml — output target for gate result.
+
+## Handoff
+
+Gate: READY → next: release-branch (final step before merge)
+Writes: state.yaml handoff.next_skill = release-branch
+
+## Verify
+
+→ verify: `test -x scripts/run-gate-trace-verify.sh && bash scripts/run-gate-trace-verify.sh --self-test && echo OK`

package/.gemini/extensions/bigpowers/commands/prompts/generate-allure-report.md

@@ -0,0 +1,284 @@
+---
+name: generate-allure-report
+description: "Generate Allure-ready reports from bigpowers YAML metadata. Reads execution-status.yaml, release-plan.yaml, epic capsules, task YAMLs, cycle-times.yaml, and bug registry to produce allure-results/junit-results.xml, categories.json, and executor.json. Use when preparing progress dashboards, integrating with Allure TestOps, or generating CI reports."
+---
+
+# Generate Allure Report
+
+Generate Allure TestOps-compatible reports from bigpowers project metadata. Produces JUnit XML for story-level test results, custom categories for filtering, and executor metadata — all in the `allure-results/` directory.
+
+## Quick Start
+
+```bash
+bash scripts/generate-allure-report.sh
+```
+
+## What It Produces
+
+Three files in `allure-results/`:
+
+| File | Description |
+|------|-------------|
+| `junit-results.xml` | One `<testcase>` per story with `<properties>` for risk, security, WSJF, tier, wave, and status. Incomplete stories get a `<failure>` element. |
+| `categories.json` | Custom Allure categories for filtering by epic, risk level (P0), and security reviews. |
+| `executor.json` | Build metadata — name, type, version from release-plan.yaml, build order. |
+
+## Data Sources
+
+See [REFERENCE.md](REFERENCE.md)
+
+## Verify
+
+```bash
+test -f allure-results/junit-results.xml && test -f allure-results/categories.json && test -f allure-results/executor.json
+```
+
+## Handoff
+
+- next_skill: null (terminal skill — no downstream workflow step)
+
+---
+
+# generate-allure-report — Reference
+
+## Data Sources
+
+The script reads five YAML sources from the project:
+
+| Source | Path | Fields Used |
+|--------|------|-------------|
+| Execution status | `specs/execution-status.yaml` | `epics`, `stories`, `development_status` |
+| Release plan | `specs/release-plan.yaml` | `release.version`, `release.status`, `bugs` summary |
+| Epic capsules | `specs/epics/**/epic.yaml` + `-tasks.yaml` | Epic metadata, task pass/fail counts |
+| Cycle times | `specs/metrics/cycle-times.yaml` | Story-level `cycle_minutes`, `bcp_per_hour`, `source` |
+| Bug registry | `specs/bugs/registry.yaml` | Bug counts by status and severity |
+
+## Script Body
+
+`scripts/generate-allure-report.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="$(dirname "${BASH_SOURCE[0]}")/.."
+
+mkdir -p "$ROOT/allure-results"
+
+$PYTHON - "$ROOT" <<'PY'
+import json
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+root = Path(sys.argv[1])
+out = root / "allure-results"
+
+# 1. Read execution-status.yaml
+exec_status_file = root / "specs" / "execution-status.yaml"
+release_plan_file = root / "specs" / "release-plan.yaml"
+cycle_times_file = root / "specs" / "metrics" / "cycle-times.yaml"
+bugs_registry_file = root / "specs" / "bugs" / "registry.yaml"
+
+sys.path.insert(0, str(root / "scripts" / "lib"))
+from simple_yaml import parse_simple_yaml
+
+exec_status = parse_simple_yaml(exec_status_file.read_text()) if exec_status_file.exists() else {}
+release_plan = parse_simple_yaml(release_plan_file.read_text()) if release_plan_file.exists() else {}
+cycle_times = parse_simple_yaml(cycle_times_file.read_text()) if cycle_times_file.exists() else {"stories": []}
+bugs_registry = parse_simple_yaml(bugs_registry_file.read_text()) if bugs_registry_file.exists() else {"bugs": []}
+
+# Build cycle-times lookup
+ct_lookup = {}
+for ct in cycle_times.get("stories", []):
+    if isinstance(ct, dict):
+        ct_lookup[ct.get("id", "")] = ct
+
+# 2. Build JUnit XML
+stories = exec_status.get("stories", {})
+
+# Counts for testsuite attributes
+total_stories = len(stories)
+incomplete = sum(1 for s in stories.values() if isinstance(s, dict) and s.get("status") != "done")
+
+testsuite = ET.Element("testsuite", {
+    "name": "bigpowers-epic-progress",
+    "tests": str(total_stories),
+    "failures": str(incomplete),
+    "errors": "0",
+    "skipped": "0",
+})
+
+for story_id in sorted(stories.keys()):
+    story = stories[story_id]
+    if not isinstance(story, dict):
+        continue
+
+    epic_id = story.get("epic", "unknown")
+    title = story.get("title", story_id)
+    bcps = story.get("bcps", 0)
+    status = story.get("status", "backlog")
+    risk_max = story.get("risk_max", "none")
+    security_max = story.get("security_max", "none")
+
+    # Enrich with cycle-times data
+    ct_data = ct_lookup.get(story_id, {})
+    cycle_minutes = ct_data.get("cycle_minutes", 0)
+    bcp_per_hour = ct_data.get("bcp_per_hour", 0)
+
+    # Time: cycle_minutes * 60 for seconds in Allure display
+    time_seconds = cycle_minutes * 60.0 if cycle_minutes else 0.0
+
+    testcase = ET.SubElement(testsuite, "testcase", {
+        "classname": epic_id,
+        "name": f"{story_id}: {title}",
+        "time": str(round(time_seconds, 3)),
+    })
+
+    props = ET.SubElement(testcase, "properties")
+    ET.SubElement(props, "property", {"name": "risk", "value": risk_max})
+    ET.SubElement(props, "property", {"name": "security", "value": security_max})
+    ET.SubElement(props, "property", {"name": "bcps", "value": str(bcps)})
+    ET.SubElement(props, "property", {"name": "status", "value": status})
+    ET.SubElement(props, "property", {"name": "bcp_per_hour", "value": str(bcp_per_hour)})
+    ET.SubElement(props, "property", {"name": "lead_time_minutes", "value": str(cycle_minutes)})
+
+    if status != "done":
+        ET.SubElement(testcase, "failure", {
+            "message": f"Story {story_id} is {status} [risk={risk_max}, security={security_max}]",
+            "type": "StoryIncomplete"
+        })
+
+tree = ET.ElementTree(testsuite)
+ET.indent(tree, space="  ")
+tree.write(str(out / "junit-results.xml"), encoding="utf-8", xml_declaration=True)
+
+# 3. Build categories.json
+epics = exec_status.get("epics", {})
+categories = []
+
+for epic_id in sorted(epics.keys()):
+    epic = epics[epic_id]
+    if isinstance(epic, dict) and epic.get("status") != "done":
+        categories.append({
+            "name": f"Epic: {epic.get('title', epic_id)}",
+            "matchedStatuses": ["failed"],
+            "messageRegex": f".*{epic_id}:.*"
+        })
+
+categories.append({
+    "name": "P0 Risk",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*risk.*P0.*"
+})
+categories.append({
+    "name": "Security Review",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*security.*(?:medium|high).*"
+})
+
+# Add bug-based categories
+bug_list = bugs_registry.get("bugs", [])
+bug_count = len(bug_list) if isinstance(bug_list, list) else 0
+open_bugs = sum(1 for b in bug_list if isinstance(b, dict) and b.get("status") not in ("fixed", "closed", None))
+if open_bugs > 0:
+    categories.append({
+        "name": "Open Bugs",
+        "matchedStatuses": ["failed"],
+        "messageRegex": ".*Bug.*"
+    })
+
+(out / "categories.json").write_text(json.dumps(categories, indent=2))
+
+# 4. Build executor.json
+rl = release_plan.get("release", {}) if isinstance(release_plan.get("release"), dict) else {}
+executor = {
+    "name": "bigpowers",
+    "type": "bigpowers",
+    "buildName": rl.get("version", "unknown") if isinstance(rl, dict) else "unknown",
+    "buildOrder": len(exec_status.get("development_status", {})),
+}
+(out / "executor.json").write_text(json.dumps(executor, indent=2))
+
+# Summary
+epic_count = len([e for e in epics.values() if isinstance(e, dict) and e.get("status") == "done"])
+total_epics = len(epics)
+print(f"generate-allure-report: {total_stories} stories, {epic_count}/{total_epics} epics done, {bug_count} bugs")
+print(f"  -> {out}/junit-results.xml")
+print(f"  -> {out}/categories.json")
+print(f"  -> {out}/executor.json")
+PY
+```
+
+## JUnit XML Schema
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<testsuite name="bigpowers-epic-progress" tests="N" failures="F" errors="0" skipped="0">
+  <testcase classname="e01" name="e01s01: Security slopcheck tags" time="0.75">
+    <properties>
+      <property name="risk" value="none"/>
+      <property name="security" value="none"/>
+      <property name="bcps" value="1"/>
+      <property name="status" value="done"/>
+      <property name="bcp_per_hour" value="1.3"/>
+      <property name="lead_time_minutes" value="45"/>
+    </properties>
+  </testcase>
+  <testcase classname="e01" name="e01s99: Some incomplete story" time="0.0">
+    <properties>...</properties>
+    <failure message="Story e01s99 is backlog [risk=P0, security=high]" type="StoryIncomplete"/>
+  </testcase>
+</testsuite>
+```
+
+## Categories JSON Schema
+
+```json
+[
+  {
+    "name": "Epic: Quality Core - Skill Hardening",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*e45:.*"
+  },
+  {
+    "name": "P0 Risk",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*risk.*P0.*"
+  },
+  {
+    "name": "Security Review",
+    "matchedStatuses": ["failed"],
+    "messageRegex": ".*security.*(?:medium|high).*"
+  }
+]
+```
+
+## Executor JSON Schema
+
+```json
+{
+  "name": "bigpowers",
+  "type": "bigpowers",
+  "buildName": "2.76.2",
+  "buildOrder": 400
+}
+```
+
+## Example Usage
+
+```bash
+# Generate reports
+bash scripts/generate-allure-report.sh
+
+# Verify output
+test -f allure-results/junit-results.xml && echo "JUnit OK"
+test -f allure-results/categories.json && echo "Categories OK"
+test -f allure-results/executor.json && echo "Executor OK"
+
+# Serve with Allure
+allure serve allure-results/
+
+# Or open the Allure TestOps UI
+allure open allure-results/
+```

package/.gemini/extensions/bigpowers/commands/prompts/grill-me.md

@@ -0,0 +1,107 @@
+---
+name: grill-me
+description: "Interactive assumption-surfacing Q&A that stress-tests a plan through relentless questioning until every decision is resolved. Use when user wants to challenge a plan, validate decisions from conversation/context, or mentions \"grill me\". For doc-grounded variant, use grill-with-docs."
+---
+
+# Grill Me
+
+> **Use this vs grill-with-docs:** `grill-me` surfaces assumptions from the conversation and context alone — no documentation fetching. Use `grill-with-docs` (the doc-grounded variant) when the plan relies on a specific library or external API and every challenge must cite a real doc URL.
+
+Two modes. Default is **Design**. Switch to **Docs** by saying "grill me with docs" or when the plan relies on a specific library or external API.
+
+> **HARD GATE** — Do NOT accept a design until every hard decision has been stress-tested. "Seems right" is not a decision. Grilling must identify and resolve tensions before build begins.
+
+## Design mode (default)
+
+Interview relentlessly about every aspect of this plan until reaching shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask one question at a time.
+
+If a question can be answered by exploring the codebase, explore it instead.
+
+### Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by exploring the codebase, reading docs, or checking APIs. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the code, go find it. Only ask questions where the user's judgment is needed.
+
+## Docs mode
+
+Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process.
+
+Short form:
+1. List every external library, third-party API, and framework behavior relied upon.
+2. Fetch the actual docs for each (`WebFetch` the official API reference).
+3. Challenge each plan assumption against the real docs: correct method signature? right version? deprecated?
+4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
+5. Update the plan for each confirmed discrepancy.
+
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
+---
+
+# Docs Mode — Full Process
+
+Triggered by "grill me with docs" or when a plan depends on a specific library or external API.
+
+**Why this matters:** AI agents hallucinate API methods, argument orders, and behaviors. Every assumption about an external dependency must be validated against the actual docs before code is written.
+
+## Step 1 — Identify the dependencies
+
+From the plan or conversation, list:
+- Every external library being used
+- Every third-party API being called
+- Every framework behavior being relied upon
+
+Ask: "Which of these are you most confident about? Which are you less sure of?"
+
+## Step 2 — Fetch the relevant docs
+
+For each dependency, fetch the actual documentation:
+
+```
+WebFetch the official docs for [library/API]
+```
+
+Prioritize:
+- The API reference for the specific method being used
+- The changelog for the version in use (breaking changes)
+- Migration guides if upgrading from a previous version
+- Known gotchas / FAQ sections
+
+## Step 3 — Challenge each assumption
+
+For every assumption in the plan, find the corresponding doc section and ask:
+
+- "Does the real API actually work this way? Show me the doc."
+- "Is this method available in the version you're using?"
+- "Does this argument order match the actual signature?"
+- "Are there rate limits, quotas, or timeout behaviors that affect this design?"
+- "Is this marked as deprecated in the current version?"
+
+Ask one question at a time. For each challenge, cite the specific URL and section.
+
+## Step 4 — Surface hallucinations
+
+When an assumption doesn't match the docs:
+
+> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
+
+Document each discrepancy clearly.
+
+## Step 5 — Update the plan
+
+For each confirmed discrepancy, recommend a concrete fix:
+- Correct method signature
+- Correct argument order
+- Alternative approach that matches what the library actually supports
+- Whether a spike (`spike-prototype`) is needed to validate a remaining uncertainty
+
+## Step 6 — Sign off
+
+When all major assumptions have been validated against docs, report:
+- Which assumptions were confirmed ✓
+- Which were corrected ✗ + what the correct approach is
+- Which remain uncertain → recommend `spike-prototype`

package/.gemini/extensions/bigpowers/commands/prompts/grill-with-docs.md

@@ -0,0 +1,52 @@
+---
+name: grill-with-docs
+description: "Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching and citing real library or API documentation. Every challenge must cite a real URL. Use when the plan depends on a specific library or external API."
+---
+
+# Grill With Docs
+
+> **Use this vs grill-me:** `grill-with-docs` is the doc-grounded variant of `grill-me`. Use it when the plan relies on external libraries or APIs and every challenge must be grounded in and cite a real documentation URL. Use `grill-me` for context-only assumption surfacing without fetching docs.
+
+> **HARD GATE** — Every challenge must cite a real documentation URL. No hallucinated APIs.
+
+## Process
+
+1. Read the plan or design under test (`specs/release-plan.yaml + epic shards`, INTERFACE-OPTIONS.md, etc.).
+2. List assumptions that depend on external libraries or APIs.
+3. For each assumption: fetch or quote official docs; challenge with "docs say X, plan says Y."
+4. Resolve or update the plan inline; unresolved items block `plan-work`.
+
+## Docs mode rules
+
+- Cite URL + quoted snippet (method name, parameter, version).
+- If docs contradict the plan, plan loses until updated.
+- Prefer official docs over blog posts.
+
+## Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by reading docs, checking APIs, or exploring the codebase. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the docs, go fetch it. Only ask questions where the user's judgment is needed.
+
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
+## Verify
+
+→ verify: `test -f skills/grill-with-docs/SKILL.md && test -f skills/grill-with-docs/REFERENCE.md`
+
+See [REFERENCE.md](REFERENCE.md) for question templates.
+
+
+<!-- story: e03s01 -->
+
+---
+
+# Grill With Docs — Question templates
+
+- "Docs at [URL] show signature `foo(bar?: Baz)`. Your plan calls `foo(bar, baz)` — which is correct?"
+- "The changelog at [URL] deprecates X in v3. Your plan still uses X — migrate or pin version?"
+- "Error handling in [URL] throws `NetworkError`. Your plan catches `Error` only — is that sufficient?"