bigpowers 2.87.4 → 2.87.5

package/.cursor/rules/using-bigpowers.mdc

@@ -0,0 +1,110 @@
+---
+description: "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks \"where do I start?\", or when the skills system needs to be explained."
+alwaysApply: false
+---
+
+# Using bigpowers
+> **HARD GATE** — **HARD GATE** — This skill is the entry point. Do NOT skip it when onboarding new users or starting a new session. It establishes the bigpowers methodology, lifecycle phases, and conventions.
+
+
+Welcome to **bigpowers** — a lifecycle of agent skills for production-ready, TDD-driven software by solo developers. The live catalog and its count are generated in [`SKILL-INDEX.md`](../../SKILL-INDEX.md); never hardcode the number here.
+
+## Install
+
+```bash
+npx bigpowers setup           # one-shot setup
+npm install -g bigpowers       # global install
+bigpowers setup                # sync skills + link to your tools
+```
+
+From source: `git clone` → `bash scripts/install.sh`. Package: [bigpowers on npm](https://www.npmjs.com/package/bigpowers).
+
+**Reach tools:** **Cline** — native AGENTS.md reader (no extension). **Aider** — opt-in `.aider.conf.yml` with `read: AGENTS.md` ([Aider-AI/aider](https://github.com/Aider-AI/aider)). **Codex CLI** — optional `.codex/config.toml` via seed-conventions; global `~/.codex/AGENTS.md` from install.sh.
+
+## What bigpowers is
+
+A curated set of skills organized around the PMBOK developer lifecycle. Each skill does one thing. Skills reference each other by name only — low coupling, high cohesion. All written output goes to `specs/` at your project root.
+
+## The lifecycle at a glance
+
+See orchestrate-project for the canonical 6-phase lifecycle.
+
+```
+BOOTSTRAP   using-bigpowers (this skill, first time only)
+              ↓
+DISCOVER    survey-context → research-first → elaborate-spec
+              ↓
+DESIGN      model-domain / define-language / grill-me / deepen-architecture / design-interface
+              ↓
+PLAN        scope-work → slice-tasks → plan-work / plan-refactor
+              ↓
+INITIATE    kickoff-branch → guard-git / hook-commits / seed-conventions
+              ↓
+SPIKE?      spike-prototype → (feeds back to plan-work)
+              ↓
+EXECUTE     develop-tdd + enforce-first ←→ delegate-task / dispatch-agents / execute-plan
+              ↓
+VERIFY      run-evals → verify-work
+              ↓
+HARDEN      wire-observability (any phase)
+              ↓
+BUG?        investigate-bug → diagnose-root → validate-fix
+              ↓
+REVIEW      audit-code → request-review → respond-review
+              ↓
+INTEGRATE   commit-message → release-branch
+              ↓
+SUSTAIN     inspect-quality / organize-workspace (ongoing)
+
+UTILITY     terse-mode / craft-skill / edit-document (any phase)
+```
+
+## Where to start
+
+| Your situation | First skill to call |
+|---------------|---------------------|
+| Greenfield project, nothing set up | `seed-conventions` |
+| Existing project, new task | `survey-context` |
+| Vague idea that needs shaping | `elaborate-spec` |
+| Plan exists, ready to implement | `kickoff-branch` → `develop-tdd` |
+| Bug to fix | `investigate-bug` |
+| Code ready for review | `audit-code` |
+| Shipping a feature | `commit-message` → `release-branch` |
+| Solo dev, PRs feel heavy | Enable `profiles/solo-git.md` → `specs/WORKFLOW-solo-git.md` → land via `scripts/land-branch.sh` |
+
+## Solo Git profile
+
+If you work alone and do not want PR ceremony every task:
+
+1. Read [profiles/solo-git.md](../../profiles/solo-git.md).
+2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`.
+3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`.
+
+You still use worktrees, protected `main`, and verification gates — only the integrate step changes.
+
+## YAML cockpit and dashboard
+
+Operational source of truth:
+
+- `specs/state.yaml` — session, active epic/story, handoff
+- `specs/release-plan.yaml` — release index and epic list
+- `specs/epics/eNN-*.yaml` — stories and tasks with `verify`
+- `specs/execution-status.yaml` — done/pending per story
+
+Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir=<abs>` and `GET /cockpit.html` for a read-only PM view.
+
+## Key conventions
+
+- **specs/ is your memory.** All domain docs, plans, and investigation outputs go in `specs/` at your project root.
+- **Integrate:** team default is `gh pr` (team-pr); solo profile uses `land-branch.sh`. Never create GitHub issues from skills — use local Markdown files instead.
+- **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
+- **verify: every step.** Every epic task must have `verify: <runnable command>`. Evidence over claims.
+- **The full catalog is auto-generated.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+
+## After this
+
+Call `survey-context` to read your project's current state and get a personalized recommendation for where to go next.
+
+
+
+<!-- story: e03s02 -->

package/.cursor/rules/validate-contracts.mdc

@@ -0,0 +1,285 @@
+---
+description: "Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy."
+alwaysApply: false
+---
+
+# Validate Contracts
+
+> **HARD GATE** — Do NOT deploy or migrate data without running `validate-contracts` first. Silent data divergence between system boundaries causes the hardest-to-debug production bugs.
+>
+> **HARD GATE** — Contract files MUST be version-controlled alongside code. Outdated contracts are worse than no contracts. If a contract hasn't been reviewed in 30 days, flag it as stale.
+
+Validate that data structures stay in sync across system boundaries — front-end vs back-end, API responses vs expected schemas, config files vs code assumptions, migration output vs target shape.
+
+## Contract types
+
+| Mode | What it catches | When to use |
+|------|----------------|-------------|
+| **Schema** | API response shape mismatches | Before every deploy, after API changes |
+| **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
+| **Shape** | Column type or format violations | After migrations, before consuming exports |
+
+## Contract file convention
+
+All contract files live in `specs/contracts/` as YAML. See [REFERENCE.md](REFERENCE.md) for extended examples.
+
+### Key-set example
+
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/locales/en.json
+  target: src/messages/en.json
+mode: subset
+```
+
+## Process
+
+### 1. Define contract
+
+Create a YAML file in `specs/contracts/` following the schema for the mode.
+
+### 2. Run validation
+
+```bash
+bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
+```
+
+The runner auto-detects key-set contracts (`sources:` block). Schema and shape modes are documented in REFERENCE.md for consumer projects.
+
+### 3. Read the report
+
+```
+PASS: key-set contract
+# or
+FAIL: key-set — N keys in reference missing from target
+```
+
+JSON Lines output for CI is planned for schema/shape modes; key-set failures exit non-zero.
+
+### 4. Fix divergence
+
+- **Missing keys** → add to target source
+- **Type mismatches** → update schema or fix producer
+- **Shape violations** → fix migration or consumer
+
+### 5. Re-validate
+
+```bash
+bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
+```
+
+## Verify arc
+
+Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
+
+## Verify
+
+→ verify: `test -x scripts/validate-contracts.sh && bash scripts/validate-contracts.sh --self-test && grep -q 'validate-contracts.sh' skills/validate-contracts/SKILL.md && echo OK`
+
+---
+
+# Validate Contracts — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–23 | Navigation |
+| 24–32 | Integration |
+| 33–44 | Configuration |
+| 45–54 | Verification |
+| 55–71 | Reference block 1 |
+| 72–92 | Reference block 2 |
+| 93–104 | Example 1 |
+| 105–121 | Example 2 |
+| 122–133 | Example 3 |
+| 134–144 | Example 4 |
+| 145–165 | Example 5 |
+| 166–176 | Example 6 |
+| 177–185 | Integration |
+| 186–197 | Configuration |
+| 198–204 | Verification |
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
+
+---
+
+## Reference block 1
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Reference block 2
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 1
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+---
+
+## Example 2
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Example 3
+
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/frontend/locales/en.json
+  target: src/backend/messages/en.json
+mode: subset      # all target keys must exist in reference
+```
+
+---
+
+## Example 4
+
+```bash
+validate-contracts --key-set specs/contracts/i18n-keys.yaml
+# → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
+# → added: 1 key in target not in reference: ['deprecated.field']
+# → exit 1 (divergence)
+```
+
+---
+
+## Example 5
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 6
+
+```bash
+validate-contracts --shape specs/contracts/migration-output.yaml
+# → PASS: 3/3 fields validated, 5000 rows OK
+# → WARN: field 'full_name' has 12 null values (0.24%)
+# → FAIL: field 'user_id' has 3 rows with type string (expected number)
+```
+
+---
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`

package/.cursor/rules/validate-fix.mdc

@@ -0,0 +1,146 @@
+---
+description: "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation."
+alwaysApply: false
+---
+
+# Validate Fix
+> **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success.
+
+
+Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence.
+
+> **Two-commit red/green policy (e45s08)** — Bug fixes follow the same two-commit discipline as `develop-tdd`: first commit adds/adjusts the failing test (`test(<scope>): …`), second commit applies the fix (`fix(<scope>): …`). Do not squash RED and GREEN before review.
+
+## Checklist
+
+### 1. Re-run the originally failing test
+
+```bash
+# Run the specific test that captured the bug
+<test command for the failing test>
+```
+
+- [ ] Previously failing test now passes
+
+### 2. Run the full test suite
+
+```bash
+# Run all tests — no filtering
+<full test command from CLAUDE.md>
+```
+
+- [ ] All tests pass (zero regressions)
+
+### 3. Type check
+
+```bash
+<typecheck command>
+```
+
+- [ ] No type errors introduced
+
+### 4. Lint
+
+```bash
+<lint command>
+```
+
+- [ ] No lint violations introduced
+
+### 5. Harden against recurrence
+
+For every bug fixed, add at least one prevention layer:
+
+| Mechanism | When to use |
+|-----------|-------------|
+| Type guard | Input could be the wrong shape |
+| Schema validation (Zod, Pydantic, etc.) | External data crossing a boundary |
+| Invariant assertion | Internal state that must always hold |
+| Lint rule | Pattern that's easy to repeat by mistake |
+| Environment check at startup | Missing config causes silent failure |
+
+- [ ] At least one hardening mechanism added
+- [ ] Hardening mechanism is tested
+
+### 5b. Generalize-fix (HARD GATE — e80s04 / GH #98)
+
+Sweep the **defect class** across the codebase after local hardening — see [REFERENCE-generalize-fix.md](REFERENCE-generalize-fix.md).
+
+- [ ] Defect class documented (not just the one-line root cause)
+- [ ] Grep sweep run and `match_count` recorded
+- [ ] `verify-generalize-sweep.sh` passes on the artifact
+
+### 6. Update the bug file and registry.yaml
+
+Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
+
+```markdown
+## Resolution
+
+**Fixed:** [date]
+**Root cause confirmed:** [one sentence]
+**Fix applied:** [what was changed]
+**Hardening added:** [type guard / schema / assertion / lint rule]
+**Evidence:** all tests pass (`<verify command>`)
+**Commit:** `fix(<scope>): <description>`
+```
+
+Also update the corresponding row in `specs/bugs/registry.yaml`: set `status` to `fixed`, fill in `files_changed`, `approach`, `risk_level`, `commit_message`, and any other resolution fields.
+
+- [ ] specs/bugs/BUG-*.md updated with resolution
+- [ ] specs/bugs/registry.yaml row updated with resolution fields
+
+### 7. Behavioral Proof (HARD GATE)
+
+Mechanical verification (tests passing) is only half the fix. You must prove **behavioral correctness**.
+
+- [ ] Manually demonstrate the fixed behavior (e.g., via `run_shell_command` or `web_fetch`)
+- [ ] Compare the output/state against the "Expected Behavior" in the bug file
+- [ ] Show the user evidence of the behavior, not just the test logs
+
+## Rules
+
+- **Loop until behavioral correctness is verified**: if any checklist item fails, or if the behavior is still incorrect despite passing tests, return to step 1 and run all checks again from the top — do not declare done until every item is green and the behavior is proven correct in a single run.
+- **Never use `@ts-ignore`, `as any`, or `// eslint-disable`** to "fix" a bug — these suppress the symptom without fixing the root cause
+- **Never mark the task done if any test is still failing**
+- **The verify command from specs/bugs/BUG-*.md or the active epic task `verify` field must pass**
+
+Suggest next skill: `audit-code` → `commit-message`.
+
+## Verify
+
+→ verify: `grep -q 'generalize-fix' skills/validate-fix/SKILL.md && test -x scripts/verify-generalize-sweep.sh && bash scripts/verify-generalize-sweep.sh --self-test && echo OK`
+
+---
+
+# Generalize-fix (e80s04 / GH #98)
+
+After local hardening in `validate-fix`, sweep the **defect class** across the codebase.
+
+## Steps
+
+1. **Classify** — name the pattern (e.g. `unscoped org query`, `fail-open verify`, `hardcoded package manager`).
+2. **Sweep** — grep for sibling instances; record `match_count` and `grep_pattern`.
+3. **Resolve** — patch all matches in this PR **or** file one tracking issue listing every remaining instance.
+4. **Artifact** — write sweep evidence before declaring done:
+
+```bash
+cat > specs/verifications/generalize-sweep-BUG-YYYY-MM-DD-slug.json <<EOF
+{
+  "defect_class": "fail-open-verify",
+  "grep_pattern": "\\\\|\\\\| echo",
+  "match_count": 0,
+  "sweep_scope": "skills/*/SKILL.md",
+  "patched_in_pr": [],
+  "tracked_issues": []
+}
+EOF
+bash scripts/verify-generalize-sweep.sh specs/verifications/generalize-sweep-*.json
+```
+
+## Security classes
+
+When the defect class is security- or gate-relevant:
+
+- Add a row to `security-review` CWE fixture table (see `skills/security-review/SKILL.md` § CWE mapping mandate).
+- If security-impact was MEDIUM+: add regression test, false-positive exclusion rule, and threat-model update (HIGH+).