bigpowers 2.86.5 → 2.86.6

package/.copilot/skills/wire-observability/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: wire-observability
+model: sonnet
+description: "Add structured JSON logging, observability commands, and idempotent setup scripts to a project. Use when a project needs production-readiness instrumentation, when user wants structured logging, or as a production-readiness gate at any phase of development."
+---
+
+# Wire Observability
+> **HARD GATE** — **HARD GATE** — Observability is not optional. Before shipping, verify: structured logging is in place, key metrics are instrumented, error cases emit signals. 'We'll add metrics later' becomes 'never.'
+
+
+Add structured logging, observability commands, and idempotent setup scripts. Can be invoked at any phase — recommended at the end of the first working slice, before the first deploy.
+
+## What this sets up
+
+1. **Structured JSON logging** — machine-readable logs for debugging and observability
+2. **Observability commands** — how to check the system's health documented in CLAUDE.md
+3. **Idempotent setup scripts** — scripts that can be run repeatedly without side effects
+
+## Process
+
+### 1. Assess current state
+
+Check what's already in place:
+- Is there a logging library? (pino, winston, structlog, zap, slog, etc.)
+- Is logging JSON or plain text?
+- Is there a health check endpoint or command?
+- Are there setup scripts? Are they idempotent?
+
+### 2. Add structured JSON logging
+
+**For user-facing CLI output:** plain text is fine.
+**For everything else:** structured JSON.
+
+Structured log entry format:
+```json
+{
+  "level": "info",
+  "timestamp": "2025-01-15T10:23:45.123Z",
+  "message": "User created",
+  "userId": "usr_abc123",
+  "requestId": "req_xyz789"
+}
+```
+
+Guidelines:
+- Include `level`, `timestamp`, `message` in every entry
+- Add context fields relevant to the operation (userId, requestId, traceId)
+- Log at boundaries: HTTP requests in/out, DB queries, external API calls, background job start/end
+- Log errors with stack traces: `logger.error({ err, context }, "Operation failed")`
+- **Never log secrets, passwords, tokens, or PII**
+
+### 3. Document observability commands in CLAUDE.md
+
+Add an "Observability" section to the project's CLAUDE.md:
+
+```markdown
+## Observability
+
+| What | Command |
+|------|---------|
+| View logs | `<log tail command>` |
+| Health check | `<health check command>` |
+| Check DB connection | `<db ping command>` |
+| View metrics | `<metrics command>` |
+```
+
+### 4. Write idempotent setup scripts
+
+An idempotent script can be run multiple times and always produces the same result (no errors on re-run).
+
+Pattern: check if the thing already exists before creating it.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Idempotent: only create if not exists
+if ! psql -c "SELECT 1 FROM pg_database WHERE datname = 'myapp'" | grep -q 1; then
+  createdb myapp
+  echo "Database created"
+else
+  echo "Database already exists, skipping"
+fi
+```
+
+Place setup scripts in `scripts/setup.sh` (or language-appropriate equivalent). Document the command in CLAUDE.md under Commands.
+
+### 5. Verify
+
+- [ ] Run the app and confirm JSON logs appear in the correct format
+- [ ] Run `scripts/setup.sh` twice — second run should produce no errors
+- [ ] Health check command returns success
+- [ ] No sensitive data in log output
+
+## BCP Plus Integration
+
+This skill maps to **BCP Plus dimension 11 (Quality Attributes)** — specifically performance, reliability, and availability instrumentation. Structured logging, health checks, and idempotent setup scripts are observable manifestations of quality-attribute requirements. The NFR Gate rule applies: standard-expectation items (e.g., "the app should log errors") score 0 with a one-line rationale; only above-standard quality requirements (e.g., p99 latency tracking, SLO-based alerting) contribute to the dimension 11 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern.

package/.copilot/skills/write-document/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: write-document
+model: sonnet
+description: "Write, organize, and sync high-integrity technical documents using the BMAD methodology. Ensures every document is Bold, Minimal, Actionable, and Durable. Use when creating architectural docs, technical guides, or organizing the specs/ directory."
+---
+
+# Write Document (BMAD)
+
+Create high-signal technical documentation that serves as an expert collaborator for both humans and AI. This skill enforces the BMAD principles to prevent context rot and ensure architectural durability.
+
+**Distinct from `edit-document`:** Use this skill to create a document that does not yet exist. Use `edit-document` when a document already exists and needs restructuring, clarity, or prose improvements.
+
+> **HARD GATE** — Every document must have a clear "Reason for Existence." If a document doesn't provide actionable leverage for a caller or test, do not create it.
+
+## The BMAD Principles
+
+| Principle | Execution |
+| :--- | :--- |
+| **B**old | Make strong assertions. Define clear boundaries and "Never" rules. No "it might" or "usually." |
+| **M**inimal | High-density, low-filler. **Circuit Breaker**: If the file exceeds 300 lines or the session exceeds 20 turns, you MUST run `terse-mode` and compact state before saving. |
+| **A**ctionable | Link every doc to a verifiable outcome. **Architectural Docs**: Verify via Gherkin features (`specs/verifications/features/`) or grep-based structure checks (`grep -c "pattern" file`) that prove the design's *constraints* are present. |
+| **D**urable | Design for the long-term. **Scalability**: Use "Nested Indexing"—root files link to module-level `GEMINI.md` indexes; do not list individual sub-files in the root. |
+
+## Process
+
+### 1. Identify the Artifact Type & Scope
+
+Choose the correct BMAD-BigPowers artifact:
+- **Decision Record (ADR)**: For "Why" decisions (saved to `specs/adr/`).
+- **Context Map**: For system-wide architectural mapping (`specs/tech-architecture/tech-stack.md`).
+- **Technical Guide**: For "How-to" with verification (saved to `<module>/REFERENCE.md`).
+- **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/verifications/features/`).
+- **Project README**: Project-facing documentation (saved to `README.md` at project root).
+
+**Cross-Cutting Concerns**: If a doc affects multiple modules, place the authoritative source in the lowest common ancestor directory and use "Delegates" (one-line pointers) in sub-directories to maintain the Single Source of Truth without violating the Stepdown Rule.
+
+### 2. Draft with Semantic Velocity
+
+> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
+
+Write the document focusing on "Expert Collaboration":
+- **Instructions over Descriptions**: Tell the reader (human or AI) exactly how to interact with the system.
+- **Provenance Links**: Link to ADRs, Issues, or Commits to preserve intent.
+- **The Stepdown Rule**: Information should descend exactly one level of abstraction. If a root doc needs to explain a leaf-level detail, it must point to a sub-index first.
+
+### Quick README (Project READMEs only)
+
+1. Ask: "Project name? One-sentence description?"
+2. Generate `README.md` at project root using the template in [REFERENCE.md](REFERENCE.md) — no TOC, no second interview round.
+3. Fill gaps from `CLAUDE.md` commands if available; use `TODO` markers otherwise.
+4. Output and suggest `edit-document` for polish.
+
+→ verify: `test -f README.md && [ "$(grep -c '^## ' README.md)" -ge 7 ]`
+
+### 3. Apply the 94% Quality Gate
+
+Before finalizing, audit the document against these red flags:
+- [ ] **Filler Language**: Are there pleasantries or "I hope this helps"? (Delete them).
+- [ ] **Ambiguity**: Are there "usually," "often," or "it depends" without specific conditions?
+- [ ] **Dead Ends**: Does the document end without a "Next Step" or "Verification" command?
+- [ ] **Shallow Content**: Does it restate the code without explaining the *intent* or *contracts*?
+
+### 4. Sync and Organize
+
+- **Big Powers Hierarchy**: Place the document in the correct tier (Global -> Project -> Sub-directory). Project READMEs are an exception — they go to project root (`README.md`), not `specs/`.
+- **Nested Indexing**: If adding a module-level doc, ensure the module's `GEMINI.md` is updated. If the module's index is new, add it to the root `GEMINI.md`.
+- **Sync**: Run `scripts/sync-skills.sh` if the document is a `SKILL.md` or affects generated artifacts.
+
+## Rules
+
+- **Minimalism is a requirement**: If a document can be a 5-line table, do not make it a 5-line essay.
+- **Verifiable outcomes**: Every technical document must include at least one `verify:` command. For architecture, this can be a `grep` or `run_shell_command` that validates the existence of required files or patterns.
+- **No speculative docs**: Do not write documentation for features that do not exist yet unless explicitly doing `elaborate-spec`.
+
+
+Suggest next skill: `audit-code` or `sync-skills.sh`.
+
+---
+
+# Project README Template
+
+Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 5–16 | Navigation |
+| 18–24 | Sections intro |
+| 26–178 | README section templates (1–15) |
+| 180–183 | Verify |
+
+## Sections
+
+### 1. Title + Badges
+
+```markdown
+# Project Name
+
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+![npm version](https://img.shields.io/npm/v/your-package.svg)
+
+```
+
+Fill badges from CLAUDE.md stack info if available. Default to license + version badges.
+
+### 2. Tagline
+
+```markdown
+> One-line description of what this project does and why it matters.
+```
+
+### 3. Description
+
+2-3 paragraphs: what problem it solves, who it's for, and what makes it different.
+
+### 4. Prerequisites
+
+```markdown
+## Prerequisites
+
+- **Runtime**: Node.js v18+ (from CLAUDE.md)
+- **Package manager**: npm (or pnpm/yarn)
+```
+
+Auto-fill from CLAUDE.md commands section when possible.
+
+### 5. Installation
+
+```markdown
+## Installation
+
+```bash
+npm install -g your-package
+# or
+npx your-package
+```
+```
+
+Prefer npx one-shot if applicable; list global install as alternative.
+
+### 6. Usage
+
+```markdown
+## Usage
+
+```bash
+your-command --help
+your-command do-something
+```
+```
+
+Include the most common 1-2 commands. Link to full docs if they exist.
+
+### 7. Features
+
+```markdown
+## Features
+
+- Feature 1: short description
+- Feature 2: short description
+```
+
+3-6 bullet points of what the project does. Derived from the project's purpose.
+
+### 8. Configuration
+
+```markdown
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VAR_NAME` | `value` | What it controls |
+```
+
+Use `TODO` markers if unknown.
+
+### 9. Development Setup
+
+```markdown
+## Development
+
+```bash
+git clone <repo-url>
+cd project
+npm install
+```
+```
+
+Auto-fill from CLAUDE.md `Run` and `Build` commands.
+
+### 10. Running Tests
+
+```markdown
+## Tests
+
+```bash
+npm test
+npm run lint
+```
+```
+
+Auto-fill from CLAUDE.md `Test` and `Lint` commands.
+
+### 11. Contributing
+
+```markdown
+## Contributing
+
+1. Fork the repo.
+2. Create a feature branch (`git checkout -b feature/my-thing`).
+3. Commit changes (`git commit -am 'Add my thing'`).
+4. Push (`git push origin feature/my-thing`).
+5. Open a Pull Request.
+```
+
+### 12. Changelog
+
+```markdown
+## Changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).
+```
+
+### 13. Links
+
+```markdown
+## Links
+
+- Repository: https://github.com/user/repo
+- Issue tracker: https://github.com/user/repo/issues
+```
+
+### 14. License
+
+```markdown
+## License
+
+MIT — see [LICENSE](../../LICENSE) for details.
+```
+
+Detect from CLAUDE.md or project LICENSE file.
+
+### 15. Credits (optional)
+
+```markdown
+## Credits
+
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
+```
+
+## Verify
+
+After generation, run: `grep -c "^## " README.md` — expect ≥ 7 section headings.

package/.hermes/skills/commit-message/SKILL.md

@@ -137,4 +137,4 @@ This table reflects the **out-of-the-box** behavior of `semantic-release` using
 
 - [Conventional Commits — specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
 - [semantic-release — README (commit format & flow)](https://github.com/semantic-release/semantic-release#commit-message-format)
-- Fork pointer: [semantic-release-baby](https://github.com/danielvm-git/semantic-release-baby) (automation and docs align with upstream semantic-release)
+- Automation and docs align with [semantic-release](https://github.com/semantic-release/semantic-release) upstream; a fork may be substituted without changing this guidance.

package/.hermes/skills/evolve-skill/SKILL.md

@@ -52,4 +52,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template.
 **Evidence:** path/to/benchmark-report.md
 ```
 
-Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine; clone it from wherever your fork lives if absent. Never assume a hard-coded absolute path or a specific owner.

package/.hermes/skills/write-document/SKILL.md

@@ -247,7 +247,7 @@ Detect from CLAUDE.md or project LICENSE file.
 ```markdown
 ## Credits
 
-Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
 ```
 
 ## Verify

package/.kilocode/rules/commit-message.md

@@ -137,4 +137,4 @@ This table reflects the **out-of-the-box** behavior of `semantic-release` using
 
 - [Conventional Commits — specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
 - [semantic-release — README (commit format & flow)](https://github.com/semantic-release/semantic-release#commit-message-format)
-- Fork pointer: [semantic-release-baby](https://github.com/danielvm-git/semantic-release-baby) (automation and docs align with upstream semantic-release)
+- Automation and docs align with [semantic-release](https://github.com/semantic-release/semantic-release) upstream; a fork may be substituted without changing this guidance.

package/.kilocode/rules/evolve-skill.md

@@ -52,4 +52,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template.
 **Evidence:** path/to/benchmark-report.md
 ```
 
-Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine; clone it from wherever your fork lives if absent. Never assume a hard-coded absolute path or a specific owner.

package/.kilocode/rules/write-document.md

@@ -247,7 +247,7 @@ Detect from CLAUDE.md or project LICENSE file.
 ```markdown
 ## Credits
 
-Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
 ```
 
 ## Verify

package/.mimocode/skills/commit-message/SKILL.md

@@ -137,4 +137,4 @@ This table reflects the **out-of-the-box** behavior of `semantic-release` using
 
 - [Conventional Commits — specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
 - [semantic-release — README (commit format & flow)](https://github.com/semantic-release/semantic-release#commit-message-format)
-- Fork pointer: [semantic-release-baby](https://github.com/danielvm-git/semantic-release-baby) (automation and docs align with upstream semantic-release)
+- Automation and docs align with [semantic-release](https://github.com/semantic-release/semantic-release) upstream; a fork may be substituted without changing this guidance.

package/.mimocode/skills/evolve-skill/SKILL.md

@@ -52,4 +52,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template.
 **Evidence:** path/to/benchmark-report.md
 ```
 
-Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine; clone it from wherever your fork lives if absent. Never assume a hard-coded absolute path or a specific owner.

package/.mimocode/skills/write-document/SKILL.md

@@ -247,7 +247,7 @@ Detect from CLAUDE.md or project LICENSE file.
 ```markdown
 ## Credits
 
-Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
 ```
 
 ## Verify

package/.opencode/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/.opencode/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: `test -f specs/IMPACT_LATEST.md || test -d specs/bugs`
+
+### 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: `test -f specs/release-plan.yaml && grep -ci "stor" specs/release-plan.yaml`
+
+### 4. List test coverage
+
+Find tests that exercise the target:
+
+```
+grep -rn "[symbol-name]" . --include="*.test.*" --include="*.spec.*"
+```
+
+→ verify: `test -d specs/epics || test -d skills`
+
+### 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`.