bigpowers 2.83.3 → 2.84.0

package/.codebuddy/skills/find-way/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: find-way
+model: sonnet
+description: "Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building."
+---
+
+# Find Way
+
+## Concept
+
+A large effort arrives — too big for one session, wrapped in fog. **Find-way** charts the way as a **shared map** on the repo's issue tracker, then works **decision tickets** — questions whose resolution is a decision, not build slices — one at a time until the route is clear.
+
+**Plan, don't do.** Each ticket resolves a decision. The map is done when the way is clear — nothing left to decide before someone executes.
+
+**Refer by name.** Every map and ticket is an issue with a title. Always use the name, never bare ids or numbers.
+
+## The Map
+
+A single issue labelled `wayfinder:map` — the canonical artifact. Child issues are its tickets.
+
+```markdown
+## Destination
+<what reaching the end looks like — one or two lines>
+
+## Notes
+<domain, skills to consult, standing preferences>
+
+## Decisions so far
+- [closed ticket title](link) — one-line gist
+
+## Not yet specified
+<in-scope fog you can't ticket yet>
+
+## Out of scope
+<work ruled beyond the destination>
+```
+
+## Ticket Types
+
+| Type | Label | Mode | Purpose |
+|------|-------|------|---------|
+| Research | `wayfinder:research` | AFK | Surface facts from docs/APIs |
+| Prototype | `wayfinder:prototype` | HITL | Cheap artifact to react to |
+| Grilling | `wayfinder:grilling` | HITL | One-question-at-a-time dialogue |
+| Task | `wayfinder:task` | Either | Manual work unblocking a decision |
+
+**HITL** = human in the loop. **AFK** = agent alone.
+
+## Two Modes
+
+### Chart the Map
+
+User invokes with a loose idea.
+
+1. **Name the destination** — grill to pin down what this map finds its way to
+2. **Map the frontier** — breadth-first: surface open decisions and first steps. If no fog emerges, the effort fits one session — skip the map
+3. **Create the map** issue (label `wayfinder:map`)
+4. **Create tickets** as child issues, then wire blocking edges in a second pass
+5. **Fire research subagents** for each `research` ticket in parallel
+6. Stop — charting resolves nothing
+
+### Work Through the Map
+
+User invokes with a map (URL/number). Ticket optional — without one, pick the next frontier ticket.
+
+1. Load the map (low-res view)
+2. **Choose & claim** — assign ticket before any work
+3. **Resolve** — zoom into related/closed tickets as needed
+4. **Record** — post resolution comment, close issue, append to Decisions-so-far
+5. **Graduate fog** — create new tickets from newly-specifiable fog, clear from Not-yet-specified
+6. **Rule out of scope** if resolution reveals something past the destination
+
+**Never resolve more than one ticket per session** (except research).
+
+## Fog of War
+
+Beyond live tickets lies the **fog** — decisions you can tell are coming but can't pin down yet. The **Not yet specified** section holds this dim view.
+
+**Fog or ticket?** Test: can you state the question precisely now?
+
+- **Ticket** when the question is sharp (even if blocked)
+- **Not yet specified** when you can't phrase it sharply yet
+
+## Out of Scope
+
+Work beyond the destination. Ruling something out is a scoping act, not a route step. Never graduates — returns only if destination is redrawn.
+
+If an existing ticket sits past the destination, close it and note in Out of scope.
+
+## Blocking & Frontier
+
+- **Blocking**: tracker's native dependency relationship
+- **Unblocked**: every blocker is closed
+- **Frontier**: open, unblocked, unclaimed children — the edge of the known
+
+## Detailed Reference
+
+See [REFERENCE.md](REFERENCE.md) for ticket anatomy, resolution protocol, and examples.
+
+---
+
+# Find-Way Reference
+
+## Ticket Anatomy
+
+Each ticket holds one question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+**Labels:** `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`
+
+**Claim:** Assign to yourself before any work — claim blocks concurrent sessions.
+
+**Blocking:** Use tracker's native dependency relationship so the frontier renders visually.
+
+**Resolution:** Post answer as a comment, close the issue, append to map's Decisions-so-far.
+
+## Resolution Protocol
+
+1. **Load the map** — read low-res view, not every ticket body
+2. **Choose & claim** — assign ticket to yourself (or take first frontier ticket if not named)
+3. **Resolve** — zoom into related/closed tickets as needed; invoke skills the Notes block names
+4. **Record** — post resolution comment with the answer, close the issue
+5. **Update map** — append to Decisions-so-far with one-line gist + link
+6. **Graduate fog** — create new tickets from newly-specifiable fog; clear from Not-yet-specified
+7. **Rule out of scope** if resolution reveals something past the destination
+
+## Ticket Types in Detail
+
+### Research (AFK)
+Surfacing facts from docs, APIs, or knowledge bases that a decision waits on.
+- Resolved by a `/research` subagent
+- Use when knowledge outside the working directory is required
+- **Label:** `wayfinder:research`
+
+### Prototype (HITL)
+Raise fidelity by building cheap, rough, concrete artifact to react to — outline, stub, UI/logic code.
+- Use the `/prototype` skill
+- Links the prototype as an asset
+- Use when "how should it look" or "how should it behave" is key
+- **Label:** `wayfinder:prototype`
+
+### Grilling (HITL)
+Conversation via `/grilling` and `/domain-modeling` skills, one question at a time.
+- The default case for clarifying decisions
+- **Label:** `wayfinder:grilling`
+
+### Task (HITL or AFK)
+Manual work unblocking a decision — signing up for service, provisioning access, moving data.
+- This is the **only** type that does rather than decides
+- Earns its place by unblocking a decision, not by delivering the destination
+- Agent drives AFK tasks alone; HITL tasks get precise checklist
+- **Label:** `wayfinder:task`
+
+## Fog-to-Ticket Graduation
+
+When resolving a ticket clears fog, graduate the newly-specifiable bits into fresh tickets:
+
+1. **Identify the fog** in Not-yet-specified that the resolution illuminates
+2. **Create new tickets** with crisp question statements
+3. **Wire blocking edges** if the new tickets depend on each other or existing ones
+4. **Clear from fog** — remove the graduated patch from Not-yet-specified so it lives only as its ticket
+
+## Out-of-Scope Close Protocol
+
+If a ticket turns out to sit past the destination:
+
+1. **Close the ticket** — mark it resolved or won't-fix
+2. **Add one line to Out of scope** — gist + why it's out of scope, linking the closed ticket
+3. **Never append to Decisions so far** — scope boundaries aren't steps on the route
+
+## Map State Transitions
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| **Open, unblocked, unclaimed** | Frontier — ready to take | Claim and resolve |
+| **Open, blocked** | Waiting on something | Wait for blockers to close |
+| **Open, claimed** | Concurrent session working | Skip for now |
+| **Closed** | Decided — lives in Decisions so far | Reference, don't re-open |
+
+## Concurrency
+
+Users may run unblocked tickets in parallel, so expect the tracker to be edited concurrently. Always:
+
+- Refresh the map before picking a ticket
+- Claim immediately before starting work
+- Never assume state hasn't changed since last read

package/.codebuddy/skills/fix-bug/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: fix-bug
+model: sonnet
+description: "Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect."
+---
+
+# Fix Bug
+
+**Boundary**: Orchestrator flow — chains `investigate-bug` (entry point + RCA via `diagnose-root`) → `develop-tdd` → `validate-fix`. Does not implement RCA or write bug files directly.
+
+Orchestrates **fix_bug** flow without mixing epic build state.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.
+
+## Discovered gate failures (e51s04)
+
+Valid entry **without a user-reported bug** when:
+
+- **Preflight** or **CI** is red at kickoff or verify-work
+- **Golden suite** or project baseline is red (`bash scripts/run-verification-gates.sh` or equivalent)
+- A reproducible gate failure during unrelated epic work exceeds quick-fix guardrails
+
+Create `specs/bugs/BUG-*.md` via `investigate-bug` (or inline in fix-bug step 1) describing the gate failure, then run the standard fix_bug chain.
+
+## Five steps (`bug_cycle` in state.yaml)
+
+| Step | Skill / action |
+|------|----------------|
+| 1 | `investigate-bug` — create BUG-*.md with RCA |
+| 2 | `diagnose-root` — 4-phase root cause analysis |
+| 3 | `develop-tdd` — red-green against bug file verify steps |
+| 4 | `validate-fix` — re-run failing test, full suite, lint |
+| 5 | `release-branch` — PR or solo land the fix |
+
+### Checkpoint / resume
+
+Track progress via `specs/state.yaml` `bug_cycle`:
+- `bug_cycle.current_step`: current step (1–5)
+- `bug_cycle.completed_steps`: completed step numbers
+- `handoff.next_skill`: skill for the current step
+- On resume, read `bug_cycle.current_step` and continue from there
+
+## Process
+
+1. **Step 1 — investigate-bug:** If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file. Increment `bug_cycle.current_step` to 2 on completion.
+2. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3.
+3. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green.
+4. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5.
+5. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.
+
+## Bug file SoT
+
+One markdown file per bug with frontmatter:
+
+```yaml
+---
+bug_id: BUG-001
+status: open
+severity: high
+scope: api
+title: Short title
+---
+```
+
+## Verify
+
+→ verify: `test -d specs/bugs && test -f scripts/run-skill-verify.sh`

package/.codebuddy/skills/gate-trace/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: gate-trace
+model: haiku
+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

package/.codebuddy/skills/generate-allure-report/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: generate-allure-report
+model: sonnet
+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/
+```