bigpowers 2.82.4 → 2.83.0

package/.agents/skills/align-grid/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: align-grid
+model: sonnet
+description: "Build editorial/magazine/report webpages on a GENUINE Müller-Brockmann modular grid (International Typographic Style) — not a decorative one. Encodes the discipline (columns + modules + baseline, grotesque type, flush-left, restrained black/white/red palette) AND the hard-won front-end engineering to make the grid real, visible, and verified: one CSS-variable source of truth, an interactive grid-toggle overlay that lives in the SAME content box as the content, subgrid \"bands\" so every element snaps to a column line, an 8px baseline lock, and runtime OPTICAL ALIGNMENT that puts display type's ink (not its box) on the line. Ships with a scaffold generator and a Puppeteer verification harness that proves 0px adherence."
+---
+
+# Müller-Brockmann Grid Systems — built real, visible, and verified
+
+Josef Müller-Brockmann (1914–1996), Zurich; *Grid Systems in Graphic Design* (1981) is the corpus. The grid is treated as an ethic, not decoration: **"The grid system is an aid, not a guarantee. It permits a number of possible uses and each designer can look for a solution appropriate to his personal style. But one must learn how to use the grid; it is an art that requires practice."** This skill encodes that discipline AND — the part most attempts get wrong — the front-end engineering to make the grid genuinely load-bearing on the web, plus a harness that PROVES it.
+
+> **HARD GATE** — Do NOT ship a grid page without running `verify_grid.js` first. A visually plausible layout is not evidence of grid adherence — the harness is. Zero failing assertions is the only passing bar.
+
+> Two real review notes this skill exists to prevent:
+> 1. *"the grid is just slapped on top and misaligned"* → the overlay wasn't in the same content box as the content (see §2.2).
+> 2. *"the H in the headline is off the grid"* → the headline's BOX was on the grid but its INK wasn't; large glyphs carry a side-bearing (see §2.6). **Box-on-grid ≠ ink-on-grid.**
+
+---
+
+## PART 1 — THE DISCIPLINE (decide before drawing)
+- **Objective order.** The grid brings "constructive thought," legibility, and "objective and functional" design. Restraint is the point; the system, not the ego, organizes the page.
+- **Modular grid.** Divide the type area into a field of **modules** — columns AND rows — separated by consistent **gutters**, inside defined **margins**. Text and images occupy whole modules. Müller-Brockmann specimens common field counts (8 / 20 / 32 fields). For the web, a **12-column grid + 8px baseline** is a robust general default; a **6×6 or 4×8 modular field grid** when you want visible rows too.
+- **Baseline grid.** Vertical rhythm is sacred: **leading = a whole multiple of the baseline unit**, and every element snaps to it. This is what makes facing columns and images line up across the page.
+- **Typography.** A **grotesque sans** (Akzidenz-Grotesk / Helvetica; on the web Inter, Helvetica Now, Archivo). **Flush-left, ragged-right.** Few sizes, large jumps in **scale** for hierarchy; objective, not expressive. Big **numerals/data set large** is a signature move.
+- **Palette.** Pure white paper, near-black ink, **one accent — red is canonical**. Avoid the warm-cream "Claude look"; **never blue/purple gradients** (hard house rule).
+- **White space + asymmetry.** Generous margins; asymmetric compositions held in tension by the grid.
+
+---
+
+## PART 2 — MAKE THE GRID REAL ON THE WEB (the load-bearing engineering)
+`grid_tokens.py` emits this whole scaffold correctly; the rules below are why it's built the way it is.
+
+### 2.1 One source of truth
+Put every grid parameter in `:root` CSS variables — `--cols, --gutter, --margin, --bl (baseline), --lh (leading=3×bl), --maxw`. **Content and the overlay both read these same variables.** Never hand-author the overlay separately or it will drift.
+
+### 2.2 The overlay MUST live in the SAME content box as the content  ← #1 bug
+Failure mode: content sits in a centered `max-width` container while the overlay is a **full-width sibling** of the section. On any viewport wider than `--maxw`, the centered content and the full-width overlay no longer share column positions → "slapped on top / misaligned."
+**Fix:** put `.guides` *inside* the same `.wrap`, and draw the column guides with `left/right = var(--margin)` and the **same** `repeat(var(--cols),1fr)` + `column-gap:var(--gutter)`. Then the overlay columns **are** the content columns at every width. Add left/right margin lines at `var(--margin)`.
+
+### 2.3 Place every element by column LINE via subgrid bands
+Don't eyeball spans. Each horizontal **band** spans all columns and re-exposes them:
+```css
+.band{grid-column:1 / -1; display:grid; grid-template-columns:subgrid; column-gap:var(--gutter); align-items:start;}
+@supports not (grid-template-columns:subgrid){ .band{grid-template-columns:repeat(var(--cols),1fr);} }
+```
+Children place with `grid-column: <startline> / <endline>` (e.g. `1 / 6`, `6 / 13`). Every headline, paragraph, photo, caption now snaps to identical lines.
+
+### 2.4 Lock vertical rhythm to the baseline
+- Leading = `--lh` (e.g. 24px = 3×8). **Every line-height a multiple of the baseline, in px (not unitless) for display type** — unitless line-heights on large type push the box off the grid.
+- Every margin/padding a multiple of the baseline. Spread top/bottom padding a multiple too, so content starts on a line.
+- **Media heights = multiples of the leading** (e.g. 240/360/432/480px) so a photo's top AND bottom both land on lines.
+- Hairline rules sit inside a baseline-height band, not free-floating.
+
+### 2.5 The toggle (sizzle within the sizzle)
+A control (button **+ `G` key**) toggles `body.grid-on`; overlay fades 0→1. Overlay draws: translucent **numbered column fields**, the **baseline** (major line every `--lh`, faint minor every `--bl`), and **margin lines**. Showing the real grid the page is built on IS the demo.
+
+### 2.6 OPTICAL ALIGNMENT — display ink, not its box  ← the subtle bug
+A 180px headline whose layout box is exactly on line 1 still looks misaligned against body text, because the letterform's **ink** is inset by its **left side-bearing**. Cure at runtime:
+```js
+// after document.fonts.ready and on resize:
+var cvs=document.createElement('canvas'),ctx=cvs.getContext('2d');
+document.querySelectorAll('.masthead,.numeral,.shead h2,.h2b').forEach(function(el){
+  el.style.marginLeft='0px';
+  var cs=getComputedStyle(el),ch=(el.textContent||'').trim()[0]; if(!ch) return;
+  if(cs.textTransform==='uppercase') ch=ch.toUpperCase();
+  ctx.font=cs.fontStyle+' '+cs.fontWeight+' '+cs.fontSize+' '+cs.fontFamily; ctx.textAlign='left';
+  var abl=ctx.measureText(ch).actualBoundingBoxLeft;     // +ve = ink overhangs left of box
+  if(isFinite(abl)) el.style.marginLeft=abl.toFixed(2)+'px'; // shift box so INK lands on the line
+});
+```
+Apply to the masthead, big numerals, and section headlines. It scales with fluid type (re-runs on resize) and uses the **actually-loaded** font, so it's correct in the user's browser.
+**CRITICAL measurement caveat:** side-bearing is **font-specific**. If you measure with the wrong font you get the wrong nudge. Headless/sandbox Chrome usually lacks the webfont, so canvas falls back to a different grotesque (measured **−16px on the fallback vs −7px on real Inter** for the same `H`). To verify optics offline you must **embed the real webfont** via `@font-face` (local TTF). In production the runtime JS measures the loaded font and is correct.
+
+---
+
+## PART 3 — VERIFY (don't trust, measure)  → `verify_grid.js`
+Render with headless Chrome (Puppeteer) and assert, at **several widths including > and < `--maxw`** (to catch centered-container drift, e.g. 1440 / 1180 / 900):
+1. **Column adherence** — every placed `.band > *` left snaps to a column START and right to a column END (~0px). **Exclude the optically-aligned display elements** from this box check (their box is intentionally side-bearing-offset; they're validated in step 4). **Gotcha:** build BOTH the column-start set and the column-end set — a grid item spanning "to line N" ends at the *far* side of the gutter, so single-edge math falsely reports a one-gutter error.
+2. **Overlay match** — each `.guides .col` rect equals the computed column rect (~0px).
+3. **Baseline** — text tops modulo the baseline ≈ 0 (tolerance ≈ half a baseline; the box-top is a proxy — the leading does the real work).
+4. **Optical ink** — each display element's ink-left (box − `actualBoundingBoxLeft`, real font) equals **its own** column line (nearest column-start to its box), not always line 1.
+
+Sandbox Chrome flags that work: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`. `file://` works for non-ES-module pages; the CLI `--screenshot` can hang on tall pages — drive via Puppeteer and screenshot per viewport. Read PNGs back with the image-capable Read tool to eyeball a **zoom crop of the top-left corner** (masthead vs body vs column line) — the fastest human check.
+
+A clean run looks like: `col=0px overlay=0px baseline≤4px ink=0px` → `GRID VERIFY: PASS`.
+
+---
+
+## PART 4 — CRAFT DEFAULTS (so it looks excellent, not just aligned)
+- **Palette:** white `#fff`, ink `#111`, one accent (Swiss red `#e4002b`). No warm-cream Claude look; no blue/purple gradients.
+- **Type:** a real grotesque webfont (Inter / Helvetica Now / Archivo) for display + body; a **mono** (Space Mono / IBM Plex Mono) for folios, captions, grid annotations — reinforces the technical register. Non-Latin via Noto Sans JP etc.
+- **Hierarchy** through scale + weight + white space, not color. Treat key data as **large numerals**. Kicker labels in mono caps. Per-spread folios.
+- **Real photography.** Ground real subjects in real photos (`SearchImages`). **Host each image via `PublishFilePublicly` and embed the `pub.hyperagent.com` URL** — a `PublishWebpage` artifact runs in a sandboxed iframe that can't authenticate thread-scoped `/api/files/...` URLs (broken-image trap).
+- **Type fidelity if you ever rasterize art** (cairosvg / headless screenshots / image-gen reference): a `Helvetica`/`Arial` CSS stack silently falls back to **Noto Sans** (reads like Calibri). Render in **Liberation Sans** or an embedded Helvetica/Arimo TTF before trusting it. (Same trap as the optical-measurement caveat: wrong font in → wrong result out.)
+- **Spread model:** full-width sections, each its own per-spread `.grid` + `.guides`, consistent margins/folios.
+
+---
+
+## PART 5 — WORKFLOW
+1. Pick the subject; gather real photos; host them publicly.
+2. Generate the scaffold: `python3 grid_tokens.py` (or `--scaffold` for a full page; `--cols/--baseline/--gutter/--margin/--maxw/--accent` to taste; it warns if gutter/margin aren't baseline multiples).
+3. Build spreads as **subgrid bands**; place everything by **column line**; lock spacing/line-heights/media heights to the **baseline**.
+4. Add the overlay (same content box) + toggle + optical-alignment JS (already in the scaffold; point its selector list at your display elements).
+5. Publish, then **verify**: `CHROME=… PUP=… node verify_grid.js <file-or-url> --widths=1440,1180,900`. Eyeball a top-left zoom crop. Fix, republish.
+
+## SCRIPTS
+- **`grid_tokens.py`** — deterministic scaffold generator. Emits the `:root` tokens, `.grid`/`.band` (subgrid) scaffold, `.guides` overlay CSS, toggle JS, and the optical-alignment JS — all wired to one source of truth. `--scaffold` emits a full minimal HTML page. No network/credentials.
+- **`verify_grid.js`** — Puppeteer harness implementing all four checks above with the corrected both-edges column math, the optical-exclusion, per-element column-line ink targeting, and PASS/FAIL output at multiple widths. Env: `CHROME` (chrome binary), `PUP` (puppeteer-core module path).
+
+## CREED
+A grid you can't toggle on and measure is a mood board, not a system. Build it from one source of truth, prove it at 0px, and align the **ink**.

package/.agents/skills/assess-impact/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: assess-impact
+model: sonnet
+description: "Analyze the blast radius of a proposed change before any code is written. Maps dependents, affected stories, and test coverage. Produces specs/IMPACT_LATEST.md. Use before plan-work on any non-trivial change, when touching a shared module, or when the user asks \"what does this break?\"."
+---
+
+# Assess Impact
+
+> **HARD GATE** — Run this skill before `plan-work` whenever a change touches an existing module, symbol, or file used by more than one caller. Skip only for net-new code with no existing dependents.
+
+Find the blast radius of the proposed change before a single line is written.
+
+## Modes
+
+- Default: full impact analysis (dependents + affected stories + test coverage mapping)
+- --lightweight: Fast fan-in/fan-out only (<10s). Maps callers and imports without test coverage mapping. Used by build-epic step 2 as a pre-plan gate. Risk score > 7 triggers a mandatory grill-me session before proceeding.
+
+## Process
+
+### 1. Identify the target
+
+Name the symbol, module, or file being changed. If the user hasn't specified, ask one question: "What exactly are you changing?"
+
+### 2. Find dependents
+
+```
+grep -rn "[symbol-name]" . --include="*.ts" | grep -v node_modules
+git log --oneline -10 -- [file-path]
+```
+
+→ verify: `grep -rn "[target]" . | wc -l`
+
+### 3. Map to release plan stories
+
+Read `specs/release-plan.yaml + epic capsule directories` (if it exists). For each dependent found in Step 2, identify which story owns that module. List stories that will be affected by the change.
+
+→ verify: `grep -c "Story" specs/release-plan.yaml + epic capsule directories 2>/dev/null || echo "no release plan"`
+
+### 4. List test coverage
+
+Find tests that exercise the target:
+
+```
+grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
+```
+
+→ verify: `grep -rn "[target]" . --include="*.test.*" | wc -l`
+
+### 5. Classify risk
+
+| Level | Condition |
+|-------|-----------|
+| Low   | ≤ 2 callers, all covered by tests |
+| Medium | 3–10 callers, partial test coverage |
+| High  | > 10 callers, or shared API/interface, or no tests |
+
+### 6. Write specs/IMPACT_LATEST.md
+
+```
+## Target
+[symbol or file being changed]
+
+## Dependents ([count])
+- [file]: [caller or usage]
+
+## Affected Stories
+- Story [X.Y]: [title]
+
+## Test Coverage
+- [test file]: covers [scenario]
+- Gap: [untested behavior]
+
+## Risk: Low / Medium / High
+[One-sentence rationale]
+
+## Recommended action
+[Proceed / Add tests first / Discuss design]
+```
+
+→ verify: `grep "Risk:" specs/IMPACT_LATEST.md`
+
+Suggest `plan-work` once risk is understood and any test gaps are noted.
+
+## Risk score gating
+
+In `--lightweight` mode (used by build-epic step 2), assign a numeric risk score (1–10):
+- Fan-in (how many callers): 0–4 points
+- Fan-out (how many dependencies the module itself uses): 0–3 points  
+- Recent churn (git log --oneline -5 count): 0–3 points
+
+**Risk score > 7**: Gate — require a `grill-me` session before proceeding to implementation. Document the grill-me result in the impact report at `specs/IMPACT-<epic>-<story>.md`.

package/.agents/skills/audit-code/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: audit-code
+model: haiku
+description: "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check."
+---
+
+# Audit Code
+> **HARD GATE** — **HARD GATE** — Audit must check for: bugs (correctness), security, performance, and clarity. Do NOT skip security review if the code touches user data, auth, or external APIs.
+
+
+Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene.
+
+**Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes.
+
+## Look-here-first (churn heuristic)
+
+Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size.
+
+```bash
+bash scripts/bp-churn-rank.sh --since 90.days --limit 15
+```
+
+Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope.
+
+## Modes
+
+- Default: full checklist
+- --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.
+- --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.
+- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree:
+
+```bash
+bash scripts/lib/parallel-review-worktrees.sh audit-code
+```
+
+
+## Checklist
+
+### Supply Chain & Security
+
+- [ ] slopcheck run for new dependencies; packages tagged in plan-work: `[OK]`, `[SUS]`, or `[SLOP]`
+- [ ] No `[SLOP]` packages without documented human approval
+- [ ] No secrets in diff (`sk-`, `ghp_`, `AKIA`, `.env` values) — see `guard-git` patterns
+- [ ] OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see `docs/references/security-threats.md`)
+- [ ] Security: diff scanned — no unaddressed HIGH findings (or deviations documented in `specs/security/EXCEPTIONS.md`)
+
+### Provenance & Metadata
+
+- [ ] New plan artefacts include `type:` and `context:` metadata
+- [ ] Implementation steps reference ADR or commit SHA where decisions were made
+
+### Law of Demeter
+
+- [ ] No method chains through unrelated objects (e.g. `a.getB().getC().doX()`)
+- [ ] Collaborators talk to immediate neighbors only; law violations need explicit justification
+
+### CONVENTIONS.md Compliance
+
+- [ ] All output files are in `specs/` (no docs written to project root)
+- [ ] No `gh issue create` calls anywhere in new/modified skills or scripts
+- [ ] `gh` used only for PRs and repo clone operations
+- [ ] No GitHub REST API called directly (no curl/fetch to api.github.com)
+
+### Scope
+
+- [ ] Changes are limited to what was asked — nothing extra refactored or reorganized
+- [ ] No speculative features added
+- [ ] No files touched outside the stated scope
+- [ ] **Discovered defects:** Reproducible gate failures (Preflight, CI, golden suite) require fix-or-log — `quick-fix` or `fix-bug` — even when "outside" the story scope. Scope-minimization does not waive Always Green.
+- [ ] Boy Scout Rule applies to files opened to fix a gate failure; it does not excuse skipping red Preflight
+
+### Boy Scout Rule
+
+- [ ] Every file I touched is cleaner than when I found it
+- [ ] No dead code left behind
+- [ ] No commented-out code blocks
+
+### Types and Safety
+
+- [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.)
+- [ ] No `@ts-ignore` or `// eslint-disable` added
+- [ ] No `as unknown as X` casts that bypass type safety
+
+### Test Coverage
+
+- [ ] Every new function has at least one test
+- [ ] Every bug fix has a regression test
+- [ ] Tests verify behavior through public interfaces (not implementation details)
+- [ ] Tests are F.I.R.S.T compliant (per CONVENTIONS.md §Tests; use `enforce-first` if unsure)
+
+### SOLID and Heuristics
+
+- [ ] Single Responsibility: no function or module doing two unrelated things
+- [ ] Open/Closed: extended through interfaces, not by modifying stable code
+- [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable
+- [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)
+
+### Code Style (CONVENTIONS.md)
+
+- [ ] Functions: 4–20 lines; split if longer
+- [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)
+- [ ] Files: under 300 lines (ideally 200–300)
+- [ ] Names: specific and unique (grep returns < 5 hits for each name)
+- [ ] No duplication — shared logic extracted (DRY / G5)
+- [ ] Early returns over nested ifs; max 2 levels of indentation
+- [ ] Conditionals: expressed as positives (G29)
+- [ ] Comments explain WHY, not WHAT
+
+### Agent Readability (Akita's Lens)
+
+- [ ] Functions are small enough to fit in a standard context window (4–20 lines)
+- [ ] Names are unique and specific enough to be `grep`-able (grep returns < 5 hits)
+- [ ] Types are explicit (no `any`, no inferred return types for public APIs)
+- [ ] Code avoids deep nesting (max 2 levels) and uses early returns
+
+### Red Flags
+
+Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.
+
+## Output
+
+Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.
+
+If all items pass: suggest running `request-review` for an independent second opinion.
+If any items fail: fix them before proceeding.
+
+In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT-<epic>-<story>.md`.
+
+## Verify
+
+→ verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review && echo "OK: audit-code dependencies present" || echo "FAIL"`
+
+## Handoff
+
+Gate: READY -> next: commit-message
+Writes: state.yaml handoff.next_skill = commit-message
+
+
+<!-- story: e01s02 -->
+<!-- story: e06s03 -->
+<!-- story: e07s01 -->
+
+---
+
+# Clean Code Heuristics (Chapter 17)
+
+A summary of Robert C. Martin's catalogue of code smells and heuristics, used as the technical benchmark for `audit-code`.
+
+## Comments (C)
+- **C1: Inappropriate Information**: Comments should only hold technical notes. Metadata (author, change history) belongs in Git.
+- **C2: Obsolete Comment**: Update or delete comments that are no longer accurate.
+- **C3: Redundant Comment**: Don't describe code that adequately describes itself (e.g., `i++; // increment i`).
+- **C4: Poorly Written Comment**: If you write a comment, spend time making it the best it can be.
+- **C5: Commented-Out Code**: Delete it. Git remembers it.
+
+## Environment (E)
+- **E1: Build Requires More Than One Step**: Building should be a single trivial operation (e.g., `bash install.sh`).
+- **E2: Tests Require More Than One Step**: Running all tests should be one simple command (e.g., `npm test`).
+
+## Functions (F)
+- **F1: Too Many Arguments**: 0 is ideal, 1-2 is fine, 3 requires special justification. Never > 3.
+- **F2: Output Arguments**: Avoid them. If a function changes state, it should change the state of its owning object.
+- **F3: Flag Arguments**: Boolean arguments are a smell that the function does > 1 thing.
+- **F4: Dead Function**: Discard methods that are never called.
+
+## General (G)
+- **G1: Multiple Languages in One Source File**: Try to minimize the mixing of languages (e.g., HTML inside Java).
+- **G5: Duplication (DRY)**: **The root of all evil.** Every time you see duplication, it's a missed opportunity for abstraction.
+- **G6: Code at Wrong Level of Abstraction**: High-level concepts in base classes; low-level details in derivatives.
+- **G25: Replace Magic Numbers with Named Constants**: No "naked" numbers or strings.
+- **G28: Encapsulate Conditionals**: Prefer `if (shouldBePublished())` over complex boolean logic.
+- **G29: Avoid Negative Conditionals**: Prefer `if (buffer.shouldCompact())` over `if (!buffer.shouldNotCompact())`.
+- **G30: Functions Should Do One Thing**: If a function can be split into sections, it's doing too much.
+- **G31: Hidden Temporal Couplings**: If execution order matters, make the dependency explicit via arguments.
+- **G34: Functions Should Descend Only One Level of Abstraction**: The Stepdown Rule.
+
+## Naming (N)
+- **N1: Choose Descriptive Names**: Names should reveal intent and be updated as code evolves.
+- **N4: Unambiguous Names**: Names should make the working of a function/variable clear.
+- **N7: Names Should Describe Side-Effects**: Describe everything the function is or does.
+
+## Tests (T)
+- **T1: Insufficient Tests**: A test suite should test everything that could possibly break.
+- **T4: An Ignored Test Is a Question about an Ambiguity**: Document the reason for `@Ignore`.
+- **T5: Test Boundary Conditions**: Most bugs happen at the boundaries; test them exhaustively.
+- **T8: Test Coverage Patterns Can Be Revealing**: Analyze what code is *not* executed to find gaps.
+- **T9: Tests Should Be Fast**: Slow tests don't get run.

package/.agents/skills/audit-plan/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: audit-plan
+model: sonnet
+description: "Evaluate an incoming project plan against bigpowers principles and conventions, surface gaps, and produce a READY/NOT READY verdict before engagement begins. Use when a new project arrives, when adapting a foreign plan, or before running seed-conventions on an unfamiliar codebase."
+---
+
+# Audit Plan
+
+> **HARD GATE** — Do NOT start build skills (kickoff-branch, develop-tdd) until audit-plan returns a READY verdict. A plan missing test commands, scope boundaries, or success criteria will produce drift and rework downstream.
+
+Assess an incoming project plan for alignment with bigpowers principles, identify what's missing, and produce a structured readiness report before any skill execution begins.
+
+## Three lenses
+
+### 1. Principles alignment
+- Are stories vertical slices (not horizontal layers)?
+- Is scope bounded — explicit in_scope + out_of_scope?
+- Are success criteria defined (how do we know we're done)?
+- Are HARD GATE candidates identifiable (critical decision points)?
+- Is there a domain language / ubiquitous terminology?
+
+### 2. Conventions completeness
+- Does `CLAUDE.md` or `AGENTS.md` exist?
+- Does `CONVENTIONS.md` exist?
+- Is the `specs/` directory layout in place?
+- Are commit conventions documented (Conventional Commits)?
+- Is the git workflow mode identified (`solo-git` | `team-pr`)?
+
+### 3. Bigpowers pre-flight (must all be answered before build)
+| Question | Why |
+|----------|-----|
+| What is the **test command**? | `develop-tdd` verify steps require it |
+| What is the **build command**? | `verify-work` mechanical gate |
+| What is the **lint command**? | `audit-code` lint gate |
+| What is the **typecheck command**? | `verify-work` typecheck gate |
+| What **CI platform** is in use? | `wire-ci` configuration |
+| **Solo or team**? | `release-branch` integration mode |
+| Primary **language + framework**? | model routing + conventions |
+| **Greenfield or existing** codebase? | determines whether to run `seed-conventions` or `migrate-spec` first |
+
+## Process
+
+1. **Ingest the plan** — accept a file path, pasted PRD text, or existing `specs/` artifacts. Read `CLAUDE.md` and `CONVENTIONS.md` if present.
+
+2. **Score each lens** — for every item above, mark:
+   - ✅ Present and adequate
+   - ⚠️ Present but incomplete — note what's missing
+   - ❌ Absent
+
+3. **Close gaps conversationally** — for each ❌ or ⚠️, ask one question at a time. Record each answer before moving to the next.
+
+4. **Write `specs/PLAN-AUDIT_LATEST.md`**:
+
+```markdown
+# Plan Audit — <project>
+**Date:** YYYY-MM-DD · **Verdict:** READY | NOT READY
+
+## Principles Alignment
+| Check | Status | Note |
+| Vertical slices | ✅ | 4 stories, each shippable |
+| Scope bounded | ⚠️ | in_scope present; out_of_scope missing |
+
+## Conventions Completeness
+| Check | Status | Note |
+
+## Pre-flight Answers
+| Command | Value |
+| test | `npm test` |
+| build | `npm run build` |
+
+## Open Gaps
+- [ ] Add out_of_scope to scope definition (run scope-work)
+- [ ] Create CLAUDE.md (run seed-conventions)
+
+## Verdict
+READY — proceed with survey-context
+NOT READY — N gaps remain; close before proceeding
+```
+
+5. **Recommend next skill**:
+   - READY → `survey-context`
+   - Needs bootstrapping → `seed-conventions`
+   - Needs spec elaboration → `elaborate-spec`
+   - Has foreign spec format → `migrate-spec`
+   - Plan assumptions need challenging → `grill-me`
+
+## Verify
+
+→ verify: `test -f specs/PLAN-AUDIT_LATEST.md && grep -q 'Verdict' specs/PLAN-AUDIT_LATEST.md && echo OK || echo FAIL`

package/.agents/skills/build-epic/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: build-epic
+model: sonnet
+description: "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work."
+---
+
+# story: e20s05
+
+# Build Epic
+
+Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.
+
+Orchestrates the **build** flow for a single epic: survey → plan tasks → kickoff → TDD → verify → audit → commit → release.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: build_epic` and `active_epic: eNN` before starting.
+>
+> **HARD GATE** — Not on `main`/`master` before step 3 (kickoff-branch).
+
+## Nine steps (`epic_cycle` in state.yaml)
+
+| Step | Skill / action |
+|------|----------------|
+| 0 | `security-review` — threat-model epic scope → `specs/security/epics/<id>/THREAT_MODEL.md` |
+| 1 | `survey-context` — confirm epic + story |
+| 2 | `plan-work` — flesh out story `tasks[]` in `specs/epics/eNN-slug/epic.yaml` |
+| 3 | `kickoff-branch` — feature branch + clean baseline |
+| 4 | `develop-tdd` — red-green per task |
+| 5 | `verify-work` — UAT + mechanical gates |
+| 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) |
+| 7 | `commit-message` — Conventional Commits draft |
+| 8 | `release-branch` — PR or solo land (supports `--squash-state`) | |
+
+## Process
+
+1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
+   - **On story start (step 1):** Write `started_at` ISO 8601 timestamp to `execution-status.yaml` under the story's key in the `stories:` section. The `bp-timing.sh` script already tracks skill-level timings — this is story-level.
+2. **Step 0 — Threat Model:** Run `security-review` against the epic's scope (read from the epic capsule). Output `specs/security/epics/<epic-id>/THREAT_MODEL.md` with surface area, vulnerability categories, risk level, and mitigation guidance.
+3. **Assess Impact (Step 2):** Before writing tasks, run `assess-impact --lightweight` on the proposed change. If the risk score exceeds 7, gate — require a `grill-me` session. Write the impact report to `specs/IMPACT-<epic>-<story>.md`. For net-new code with no existing dependents, skip.
+4. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
+5. **BCP Plus (Step 2, optional):** When the epic capsule carries a `bcp_plus_breakdown` (13-dimension sizing), also carry it into `state.yaml` as `epic_cycle.bcp_plus`. The breakdown maps each of the 13 dimensions to an integer count. NFR dimensions (11–13) that are N/A per the NFR Gate may be set to 0.
+6. If `epic_cycle.step` missing, set to `1`.
+6. Run **only the current step** (resume mode) unless user asked for full auto-run.
+7. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
+8. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
+   - **On story complete (step 8):** Write `completed_at` ISO 8601 timestamp to `execution-status.yaml` under the same story key. Format:
+
+     ```yaml
+     stories:
+       e01s01:
+         status: done
+         started_at: "2026-07-12T16:00:00-03:00"
+         completed_at: "2026-07-12T18:45:00-03:00"
+     ```
+9. **Traceability refresh:** Before step 8 (release-branch), run `bash scripts/trace-stories.sh` to regenerate `specs/traceability-matrix.json`, `specs/TRACEABILITY_LATEST.md`, and the `specs/codebase-wiki/` OKF bundle. Surface dark/orphan/stale findings for the just-built epic in your verify summary. If `scripts/trace-stories.sh` is missing or fails, note "trace skipped" and continue — trace failure must be visible, not silent (blocking is gate-trace's job, e38s06).
+
+9b. **OKF wiki refresh (e39s08):** Before step 8, run maintain-wiki INGEST to refresh the OKF wiki bundle:
+   ```bash
+   bash scripts/decompose-conventions.sh
+   bash scripts/generate-agent-guide.sh
+   ```
+   If any script is missing or fails, note "OKF wiki refresh skipped" and continue.
+   This is non-blocking — stale concepts are caught by LINT in verify-work Phase 3.
+
+### Step 6 — audit-code gate (non-optional)
+
+After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
+
+1. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
+2. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
+3. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
+4. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
+5. **Enforce F.I.R.S.T:** After audit-code passes, run `enforce-first --quick` on new/modified tests. Append F.I.R.S.T violations (if any) to the audit report. Failing F.I.R.S.T criteria trigger the same loop-back to step 4.
+
+## --fast mode
+
+Coalesces read-and-report steps to reduce token overhead. Activate with `build-epic --fast`.
+
+| Normal | --fast | Change |
+|--------|--------|--------|
+| Step 1 (survey-context) | 1+2 together | survey + plan in one invocation |
+| Step 2 (plan-work) | (absorbed into 1) | — |
+| Step 3 (kickoff-branch) | Step 2 | unchanged, sequential |
+| Step 4 (develop-tdd) | Step 3 | unchanged, sequential |
+| Step 5 (verify-work) | Step 4 | unchanged, sequential |
+| Step 6 (audit-code) | 5+6 together | audit + commit-message in one invocation |
+| Step 7 (commit-message) | (absorbed into 6) | — |
+| Step 8 (release-branch) | Step 7 | unchanged, sequential |
+
+**Total invocations:** 8 → 6 per story.
+
+**Rules:**
+- Steps 3/4/5/8 (kickoff, develop, verify, release) still run sequentially — they require user interaction or branch state.
+- `--fast` does NOT skip any checklist items; it only coalesces steps that are pure read-and-report.
+- Record `epic_cycle.fast_mode: true` in `state.yaml` when this flag is active.
+
+## Handoff
+
+Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.
+
+## Verify
+
+→ verify: `test -f specs/state.yaml && test -f specs/execution-status.yaml && test -f specs/release-plan.yaml && test -d skills/assess-impact && test -d skills/audit-code && test -d skills/security-review && echo "OK: build-epic dependencies present" || echo "FAIL"`
+
+
+<!-- story: e38s02 -->