bigpowers 2.73.8 → 2.74.0

package/skills/release-branch/SKILL.md

@@ -1,4 +1,7 @@
 <!-- story: e38s07 -->
+<!-- story: e45s15 -->
+<!-- story: e45s32 -->
+<!-- story: e45s39 -->
 ---
 name: release-branch
 model: haiku
@@ -55,6 +58,8 @@ If REVIEW.md is missing or stale → run `security-review` inline. Findings bloc
 
 Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: <explanation>`). WAIVED if no matrix available.
 
+> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails.
+
 ### 3. Diff review
 
 - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
@@ -75,9 +80,26 @@ bash scripts/land-branch.sh <task-slug> "feat(scope): description"
 
 ### 6. Create PR (team-pr only)
 
-Create the pull request, then merge via `gh`:
+Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently:
+
+```markdown
+<!-- bigpowers-provenance: agent-generated -->
+```
+
+Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`:
 
 ```bash
+gh pr create --title "..." --body "$(cat <<'EOF'
+## Summary
+<!-- bigpowers-provenance: agent-generated -->
+
+- ...
+
+## Test plan
+- [ ] ...
+
+EOF
+)"
 gh pr merge --squash --delete-branch
 ```
 
@@ -93,55 +115,18 @@ mv specs/epics/eNN-slug specs/epics/archive/
 
 ### 7b. CI verification & agent lock release (e39s02)
 
-> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
-
-After push, run CI polling:
+> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release).
 
 ```bash
 bash scripts/wait-for-ci.sh --timeout 600 --interval 30
 ```
 
-Then release the story lock:
-
-```bash
-LOCK="specs/agent-locks.yaml"; STORY="<story-id>"
-[ -f "$LOCK" ] && python3 -c "
-import yaml
-d=yaml.safe_load(open('$LOCK'))
-if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY']
-yaml.dump(d,open('$LOCK','w'),default_flow_style=False)
-print(f'LOCK RELEASED: $STORY')
-"||echo "No lock for $STORY — idempotent"
-```
-
-- [ ] CI workflow passes after push (wait-for-ci.sh exit 0)
-- [ ] `release.ci_verified: true` documented in state.yaml
-- On failure: `handoff.next_skill = fix-bug` with CI failure URL
+- [ ] CI passes; `release.ci_verified: true` in state.yaml
+- On failure: `handoff.next_skill = fix-bug`
 
-### 8. Clean up worktree
+### 8. Clean up & return
 
-```bash
-git worktree prune
-git worktree remove ../<branch-name> 2>/dev/null || true
-git branch -d <branch-name>
-```
-
-### 8a. Cycle-time recording
-
-After landing, record delivery metrics with the git-derived, additive script:
-
-```bash
-bash scripts/record-cycle-time.sh append \
-  --story <story_id> --bcps <bcps> \
-  --range "$(git merge-base main HEAD)..HEAD" \
-  --file specs/metrics/cycle-times.yaml
-```
-
-### 9. Return to main
-
-```bash
-git checkout main && git status && pwd
-```
+Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time).
 
 Report: "Branch released."
 

package/skills/request-review/SKILL.md

@@ -1,3 +1,6 @@
+# story: e45s07
+<!-- story: e45s07 -->
+<!-- story: e45s17 -->
 ---
 name: request-review
 model: opus
@@ -5,21 +8,44 @@ effort: standard
 description: Dispatch a fresh reviewer agent with a clean context to critique the code after audit-code passes. The reviewer has no shared state with the coding agent and gives a genuine second opinion. Use after audit-code passes, before committing, or when user wants an independent code review.
 ---
 
+# story: e45s28
+
 # Request Review
 
-Dispatch a fresh reviewer agent with a clean context. The reviewer has no shared state — it can give a genuine second opinion because it hasn't been involved in writing the code.
+Dispatch fresh reviewer agents with clean contexts. Reviewers have no shared state — they find what the coding agent missed.
+
+**Distinct from `audit-code`:** `audit-code` is self-review (internal). This skill dispatches external agents.
+
+**Solo developer note:** Reviewer agents replace the human reviewer.
+
+**Run `audit-code` first.** Don't waste reviewer attention on hygiene issues you could have caught yourself.
+
+## Santa Method — Dual-Blind AND Gate (e45s07)
+
+Use **two independent reviewers** (Reviewer A and Reviewer B) with **no shared context** between them or the coding agent.
 
-**Distinct from `audit-code`:** `audit-code` is the coding agent checking its own work (internal). This skill dispatches an external agent whose job is to find what the coding agent missed.
+| Parameter | Value |
+|-----------|-------|
+| Reviewers | 2 (mandatory) |
+| `MAX_REVIEW_ITERATIONS` | **5** (hard cap — e45s28; iteration 6 forbidden) |
+| Pass rule | **AND-gate** — both reviewers must pass independently |
+| Blindness | Neither reviewer sees the other's report until both complete |
 
-**Solo developer note:** This replaces the human reviewer. The reviewer agent IS the reviewer.
+**Iteration loop (max `MAX_REVIEW_ITERATIONS`):**
 
-**Run `audit-code` first.** This skill assumes `audit-code` has already passed. Don't waste a reviewer's attention on hygiene issues you could have caught yourself.
+1. Dispatch Reviewer A and Reviewer B in parallel with identical briefs but separate contexts.
+2. Collect both reports. Each categorizes findings: must-fix / should-fix / consider.
+3. **AND-gate:** If **either** reviewer has must-fix findings → FAIL round. Run `respond-review`, fix, re-dispatch both reviewers.
+4. If both pass (zero must-fix, score ≥ 94% each) → review complete.
+5. After **5** iterations without dual pass → **stop**; report "Review cap exhausted (5/5). Human decision required." Do not merge.
+
+> **HARD GATE** — Single-reviewer pass is insufficient. Partial agreement does not satisfy the AND-gate.
 
 ## Process
 
 ### 1. Prepare the review brief
 
-Write a self-contained brief for the reviewer agent. Include:
+Write a self-contained brief for each reviewer. Include:
 
 - What was built (feature description, not implementation)
 - Which files changed (the diff context)
@@ -29,12 +55,25 @@ Write a self-contained brief for the reviewer agent. Include:
 - What you're most uncertain about (where you want fresh eyes)
 - **Security focus** — If the epic has a `specs/security/epics/<id>/THREAT_MODEL.md`, include the relevant vulnerability categories as reviewer focal points. Also include the false-positive exclusion rules so the reviewer avoids known-safe patterns. Tag the review as `security-sensitive: true` if THREAT_MODEL risk is HIGH+.
 
-### 2. Dispatch the reviewer agent
+### 2. Fan-out parallel reviewers (e45s17)
+
+Beyond the mandatory dual-blind pair (e45s07), optionally dispatch **N dimension-specific subagents in one message** — one check per agent for broader coverage (OpenAI Codex `code-review-*` pattern):
+
+| Agent | Focus |
+|-------|-------|
+| R-correctness | Logic, edge cases, verify command result |
+| R-conventions | CONVENTIONS.md, test quality (F.I.R.S.T) |
+| R-security | Injection, auth, secrets (when `security-sensitive`) |
+| R-design | Simpler alternatives, API shape |
 
-Use the Agent tool with a completely fresh context. The agent prompt must be self-contained — no references to "our conversation" or "what we discussed."
+Santa Method still applies: each agent is blind; AND-gate uses Reviewer A + B scores. Fan-out agents feed findings into `respond-review` but do not replace the dual-blind pair.
+
+### 2b. Dispatch both reviewer agents (parallel)
+
+Use the Agent tool twice with completely fresh contexts. Each prompt must be self-contained — no references to "our conversation" or "what we discussed."
 
 ```
-You are a code reviewer. Review the following code changes.
+You are code reviewer [A|B]. Review the following code changes independently.
 
 Context: [feature description]
 CONVENTIONS.md rules: [paste relevant sections]
@@ -56,19 +95,22 @@ For each finding, categorize as: must-fix / should-fix / consider.
 Run the verify command and report the result.
 ```
 
-### 3. Collect the report
+### 3. Collect both reports
 
-When the reviewer returns:
-- Read every finding before acting on any
-- Note the verify command result
-- Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items`
-- Report the score to the user
+When reviewers return:
+- Read every finding from **both** reports before acting on any
+- Note each verify command result
+- Compute quality score per reviewer: `100 × (total_items − must_fix − should_fix) / total_items`
+- **AND-gate check:** both scores ≥ 94% and zero must-fix from **both**?
 
-> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first. The 94% threshold also applies to the compliance SCORE computed by `npm run compliance` (scripts/audit-compliance.sh): SCORE = passing Gherkin scenarios / total × 100.
+> **HARD GATE** — If either score < 94% or either has must-fix → FAIL round. Run `respond-review` first. The 94% threshold also applies to `npm run compliance` (scripts/audit-compliance.sh).
 
 ### 4. Hand off to respond-review
 
-Pass the reviewer's report to `respond-review` to categorize findings and apply fixes.
+Pass combined findings to `respond-review` to categorize and apply fixes. Increment iteration counter. Re-dispatch both reviewers until AND-gate passes or iteration 3 exhausted.
+
+Report to user: "Review round [N/3]. Reviewer A: [score], Reviewer B: [score]. AND-gate: [PASS|FAIL]."
 
-Report to user: "Review complete. [N] findings: [X] must-fix, [Y] should-fix, [Z] consider. Running respond-review."
+## Verify
 
+→ verify: `grep -q 'AND-gate' skills/request-review/SKILL.md && grep -q 'max 3' skills/request-review/SKILL.md && echo OK`

package/skills/run-benchmark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-benchmark
-# story: e48s01
+# story: e45s01
 model: haiku
 effort: standard
 description: Run skill quality benchmarks from specs/benchmarks/ definitions — N-run with/without-skill delta grading, train/validation split, pass@k + benchmark.json reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions.
@@ -30,9 +30,9 @@ Benchmark definitions partition scenarios into two sets:
 ## Usage
 
 ```bash
-run-benchmark <skill-name>           # benchmark single skill
-run-benchmark --all                  # benchmark all with definitions
-run-benchmark <skill-name> --baseline # pin results as baseline
+bash scripts/run-benchmark.sh <skill-name>           # benchmark single skill
+bash scripts/run-benchmark.sh --all                  # benchmark all with definitions
+bash scripts/run-benchmark.sh <skill-name> --baseline # pin results as baseline
 ```
 
 ## Process

package/skills/run-evals/REFERENCE.md

@@ -1,15 +1,25 @@
 # Run Evals — Reference
 
+## Strictness tiers (e45s37)
+
+Add a `tier:` column to each eval row:
+
+| Tier | Gate behaviour |
+|------|----------------|
+| `EXPERIMENTAL` | Log only — does not block |
+| `USUALLY_PASSES` | Warn on failure; blocks only when paired with failing `ALWAYS_PASSES` |
+| `ALWAYS_PASSES` | Hard block on any failure |
+
 ## EVALS template
 
 ```markdown
 # EVALS: <feature>
 
 ## Capability
-| ID | Eval | Grader | verify / rubric |
-|----|------|--------|-----------------|
-| C1 | ... | code | `verify: npm test -- <file>` |
-| C2 | ... | model | Rubric: [ ] criterion A [ ] criterion B |
+| ID | Eval | Grader | Tier | verify / rubric |
+|----|------|--------|------|-----------------|
+| C1 | ... | code | ALWAYS_PASSES | `verify: npm test -- <file>` |
+| C2 | ... | model | USUALLY_PASSES | Rubric: [ ] criterion A [ ] criterion B |
 
 ## Regression
 | ID | Eval | Grader | verify / rubric |

package/skills/run-evals/SKILL.md

@@ -1,3 +1,4 @@
+# story: e45s37
 ---
 name: run-evals
 description: Eval-Driven Development — define capability and regression evals before building; code graders use verify commands, model graders use explicit rubrics; log pass@k. Use before develop-tdd on new features, or when measuring agent capability over runs.
@@ -16,8 +17,18 @@ effort: standard
    - **Capability evals** (does it do the job?)
    - **Regression evals** (did we break anything?)
 3. Assign grader type per eval: `code` (shell verify) or `model` (rubric).
-4. Run evals; log results table with pass@k (e.g. 3/3 runs).
-5. Block BUILD phase until capability evals pass at agreed k.
+4. Assign **strictness tier** per eval (graduated promotion — e45s37):
+
+   | Tier | Meaning | Promotion rule |
+   |------|---------|------------------|
+   | `EXPERIMENTAL` | New eval, may flake | Not gating |
+   | `USUALLY_PASSES` | Stable in dev; ≥2/3 recent runs pass | Blocks BUILD only when combined with ALWAYS_PASSES suite |
+   | `ALWAYS_PASSES` | Zero tolerance; required for release | Any single failure blocks BUILD and merge |
+
+   Promote: `EXPERIMENTAL → USUALLY_PASSES` after 3 consecutive passes; `USUALLY_PASSES → ALWAYS_PASSES` after 5 consecutive passes with zero flakes documented in `specs/state.yaml`.
+
+5. Run evals; log results table with pass@k (e.g. 3/3 runs) and tier per eval.
+6. Block BUILD phase until all `ALWAYS_PASSES` evals pass at agreed k. `USUALLY_PASSES` failures warn; `EXPERIMENTAL` failures log only.
 
 ## Artefact
 

package/skills/security-review/REFERENCE-false-positives.md

@@ -19,14 +19,15 @@ Automatically exclude findings matching these patterns:
 | 8 | **Race conditions / timing attacks** that are theoretical | Only report if concretely problematic |
 | 9 | **Outdated third-party libraries** | Managed separately by dependency scanners |
 | 10 | **Memory safety** in Rust or other memory-safe languages | Impossible by language guarantees |
-| 11 | **Unit test files only** | Not production risk |
-| 12 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln |
-| 13 | **SSRF that only controls path** | Only host/protocol control is exploitable |
-| 14 | **User-controlled content in AI system prompts** | Not a security vulnerability |
-| 15 | **Regex injection** | Injecting untrusted content into regex is not a vuln |
-| 16 | **Regex DOS** | Excluded alongside general DOS |
-| 17 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities |
-| 18 | **Lack of audit logs** | Not a vulnerability |
+| 11 | **Hardcoded SQL with proven authorship** — migrations, seeds, static admin queries with no user interpolation | Developer-authored SQL is safe per SQL-safety doctrine (e45s41) |
+| 12 | **Unit test files only** | Not production risk |
+| 13 | **Log spoofing** | Outputting unsanitized input to logs is not a vuln |
+| 14 | **SSRF that only controls path** | Only host/protocol control is exploitable |
+| 15 | **User-controlled content in AI system prompts** | Not a security vulnerability |
+| 16 | **Regex injection** | Injecting untrusted content into regex is not a vuln |
+| 17 | **Regex DOS** | Excluded alongside general DOS |
+| 18 | **Documentation files** (.md, .txt) | Insecure docs are not code vulnerabilities |
+| 19 | **Lack of audit logs** | Not a vulnerability |
 
 ## Precedent Rules
 

package/skills/security-review/REFERENCE-vuln-categories.md

@@ -7,6 +7,8 @@ Each category: vulnerable pattern → safe pattern → code example.
 | Aspect | Detail |
 |--------|--------|
 | **Vulnerable** | String interpolation in SQL queries: `f"SELECT * FROM users WHERE id = {uid}"` |
+| **CWE** | CWE-89 (SQL Injection) |
+| **Fixtures** | `fixtures/CWE-89-sqli-positive.py` (flag) · `fixtures/CWE-89-sqli-negative.py` (pass) |
 | **Safe** | Parameterized queries / ORM: `cursor.execute("SELECT * FROM users WHERE id = %s", (uid,))` |
 | **Look for** | f-strings, `+` concatenation, `format()` in query builders; raw SQL in ORM `.raw()` / `.execute()` |
 | **False-positive guard** | Not a FP if the input is user-controlled (HTTP param, file, env var, CLI arg). Env vars are trusted (see exclusion rules). |
@@ -16,6 +18,8 @@ Each category: vulnerable pattern → safe pattern → code example.
 | Aspect | Detail |
 |--------|--------|
 | **Vulnerable** | `element.innerHTML = userInput`, `dangerouslySetInnerHTML={{__html: userInput}}` |
+| **CWE** | CWE-79 (Cross-site Scripting) |
+| **Fixtures** | `fixtures/CWE-79-xss-positive.js` (flag) · `fixtures/CWE-79-xss-negative.js` (pass) |
 | **Safe** | `element.textContent = userInput`, React JSX (auto-escaped), template engines with auto-escaping |
 | **Look for** | `.innerHTML`, `document.write()`, `dangerouslySetInnerHTML`, `v-html` (Vue), `bypassSecurityTrustHtml` (Angular) |
 | **False-positive guard** | React/Angular components without unsafe methods are NOT vulnerable (see exclusion rules). |

package/skills/security-review/SKILL.md

@@ -1,3 +1,5 @@
+# story: e45s41
+<!-- story: e45s18 -->
 ---
 name: security-review
 model: sonnet
@@ -10,12 +12,24 @@ description: >
   the user says "security review" or "scan for vulns".
 ---
 
+# story: e45s26
+
 # Security Review
 
 > **HARD GATE** — Requires git context (branch with merge-base or diff). Never
 > writes files outside `specs/security/`. Findings below confidence 8/10 are
 > suppressed. **→ verify:** `git rev-parse HEAD >/dev/null 2>&1 && echo "ok" || echo "BLOCKED"`
 
+## Parallel worktree mode (e45s18)
+
+When running alongside `audit-code`, use isolated worktrees so scans do not race on the same index:
+
+```bash
+bash scripts/lib/parallel-review-worktrees.sh security-review
+```
+
+Each check gets a detached worktree at `.bigpowers/worktrees/review-<name>/`; reports still write only under `specs/security/`.
+
 ## 5-phase scan
 
 | # | Phase | What |
@@ -30,6 +44,37 @@ description: >
 
 Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi
 
+## CWE mapping mandate (e45s26)
+
+Every **new detection rule** added to this skill MUST:
+
+1. Map to a [CWE](https://cwe.mitre.org/) ID in `REFERENCE-vuln-categories.md` (e.g. SQLi → CWE-89, XSS → CWE-79).
+2. Ship **two fixture pairs** under `skills/security-review/fixtures/`:
+   - **Positive** — minimal code the rule MUST flag (vulnerable pattern present).
+   - **Negative** — structurally similar code the rule MUST NOT flag (safe pattern / false-positive guard).
+
+| Rule | CWE | Positive fixture | Negative fixture |
+|------|-----|------------------|------------------|
+| SQL injection | CWE-89 | `fixtures/CWE-89-sqli-positive.py` | `fixtures/CWE-89-sqli-negative.py` |
+| XSS (DOM) | CWE-79 | `fixtures/CWE-79-xss-positive.js` | `fixtures/CWE-79-xss-negative.js` |
+
+Before merging a new category, run both fixtures through the detection guidance and confirm positive flags / negative passes.
+
+## SQL-safety doctrine (e45s41 — proven authorship)
+
+Formal rule for SQL injection classification:
+
+| SQL source | Attacker-reachable input? | Verdict |
+|------------|---------------------------|---------|
+| Hardcoded / compile-time constant string | N/A | **Safe** — proven authorship |
+| Developer-authored query with bound parameters only | No dynamic fragments from user input | **Safe** |
+| String concatenation / template with user-controlled values | Yes | **Unsafe** — report as SQLi |
+| ORM query builder with user input in WHERE/JOIN | Yes | **Unsafe** unless parameterized |
+| Stored procedure call with bound args | Args from trusted constants only | **Safe** |
+| Stored procedure with dynamic SQL inside | User input reaches EXEC | **Unsafe** |
+
+**Provenance test:** If the agent cannot prove the query string was authored entirely by the developer (no attacker-reachable interpolation), treat as vulnerable. Hardcoded SQL in migrations, seeds, and admin scripts is safe; anything reachable from HTTP/CLI/user input is not.
+
 ## BCP Plus Integration
 
 This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern.

package/skills/security-review/fixtures/CWE-79-xss-negative.js

@@ -0,0 +1,6 @@
+// story: e45s26
+// fixture: CWE-79 negative — MUST NOT be flagged (textContent auto-escapes)
+function renderComment(el, userInput) {
+  // SAFE: text-only assignment — no HTML parsing
+  el.textContent = userInput;
+}

package/skills/security-review/fixtures/CWE-79-xss-positive.js

@@ -0,0 +1,6 @@
+// story: e45s26
+// fixture: CWE-79 positive — MUST be flagged as XSS
+function renderComment(el, userInput) {
+  // VULNERABLE: unsanitized HTML assignment
+  el.innerHTML = userInput;
+}

package/skills/security-review/fixtures/CWE-89-sqli-negative.py

@@ -0,0 +1,8 @@
+# story: e45s26
+# fixture: CWE-89 negative — MUST NOT be flagged (parameterized query)
+import sqlite3
+
+def get_user(user_id: str) -> dict:
+    conn = sqlite3.connect("app.db")
+    # SAFE: bound parameter — proven authorship, no attacker-reachable interpolation
+    return conn.execute("SELECT * FROM users WHERE id = ?", (user_id,)).fetchone()

package/skills/security-review/fixtures/CWE-89-sqli-positive.py

@@ -0,0 +1,9 @@
+# story: e45s26
+# fixture: CWE-89 positive — MUST be flagged as SQL injection
+import sqlite3
+
+def get_user(user_id: str) -> dict:
+    conn = sqlite3.connect("app.db")
+    # VULNERABLE: user-controlled string interpolated into SQL
+    query = f"SELECT * FROM users WHERE id = {user_id}"
+    return conn.execute(query).fetchone()

package/skills/seed-conventions/REFERENCE.md

@@ -1,6 +1,46 @@
 # story: e51s02 e37s01 e37s03 e37s14
+# story: e45s21
 # Seed Conventions — Reference Templates
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1–4 | Title + story tags |
+| 6–22 | Navigation (this table) |
+| 24–35 | AGENTS.md spine |
+| 37–76 | Agent config template |
+| 78–85 | opencode.json template |
+| 87–96 | Aider bridge |
+| 98–108 | Codex CLI wiring |
+| 110–118 | CONVENTIONS.md |
+| 120–122 | Stack profile fragments |
+| 124–153 | Local tool wiring |
+
+## Fenced markers (e45s21)
+
+Self-installing blocks prevent skills from overwriting user-authored prose. Pattern:
+
+```markdown
+<!-- BEGIN bigpowers:section-id -->
+…managed content…
+<!-- END bigpowers:section-id -->
+```
+
+**Merge algorithm:**
+
+1. If `BEGIN bigpowers:<id>` exists → replace inner content only.
+2. If missing → append new fenced block at EOF.
+3. Never delete content outside fences.
+
+Seed these marker IDs in generated `AGENTS.md`:
+
+| ID | Initial content |
+|----|-----------------|
+| `project` | Project, Commands, Architecture, Conventions, Never, Agent Rules |
+| `context-routing` | Glob → sub-AGENTS.md table (see CLAUDE.md e45s22) |
+| `learned-preferences` | Empty Learned User Preferences + Workspace Facts lists |
+
 ## AGENTS.md spine (Reach Template — e37s01)
 
 Canonical source: copy from `docs/templates/AGENTS.md` in the bigpowers repo (Reach Template).

package/skills/seed-conventions/SKILL.md

@@ -1,4 +1,5 @@
 # story: e51s02
+# story: e45s21
 ---
 name: seed-conventions
 model: sonnet
@@ -64,7 +65,28 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 
 When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`).
 
+### Self-installing fenced markers (e45s21)
 
+Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment markers** so handwritten content outside the fence is never clobbered:
+
+```markdown
+<!-- BEGIN bigpowers:section-id -->
+…agent-managed content only…
+<!-- END bigpowers:section-id -->
+```
+
+**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file.
+
+**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
+
+| Marker ID | Owner skill | Purpose |
+|-----------|-------------|---------|
+| `project` | seed-conventions | Project, Commands, Architecture |
+| `context-routing` | seed-conventions | Glob → sub-AGENTS.md routing table |
+| `learned-preferences` | session-state | Learned User Preferences + Workspace Facts |
+| `tooling` | setup-environment, guard-git | sqz/rtk/hook blocks installed by tooling skills |
+
+Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/templates/AGENTS.md`. User prose outside fences is sacred.
 
 - [ ] CLAUDE.md exists and is populated
 - [ ] CONVENTIONS.md exists and includes specs/ output convention

package/skills/session-state/SKILL.md

@@ -5,6 +5,8 @@ effort: standard
 description: Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
 ---
 
+# story: e45s23
+
 # Session State
 > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct.
 
@@ -19,6 +21,8 @@ Maintain a single source of truth for the *current* session in `specs/state.yaml
 
 Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
 
+When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21.
+
 ## Handoff block (cold start)
 
 When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
@@ -65,6 +69,7 @@ When starting a new session or after a significant context flush:
 Whenever a significant decision is made or a milestone is reached:
 
 - [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
+- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23).
 - [ ] Update `handoff.open_decisions` with rationale.
 - [ ] Update `epic_cycle` when advancing `ship-epic` steps.
 - [ ] Record open questions under `handoff.open_decisions` or an ADR.
@@ -131,16 +136,6 @@ handoff:
   next_skill: survey-context
 ```
 
-## Tracking commit ratio
-
-After `release-branch` lands, compute fix-to-feature ratio via:
-```bash
-FEAT_COUNT=$(git log main --oneline --grep="^feat" | wc -l | tr -d ' ')
-FIX_COUNT=$(git log main --oneline --grep="^fix" | wc -l | tr -d ' ')
-FIX_PCT=$((FIX_COUNT * 100 / (FEAT_COUNT + FIX_COUNT)))
-```
-Update `specs/state.yaml` `metrics.commit_ratio` with counts. If `fix_pct > 30%`, emit: `"High fix rate (N%) — deploy + smoke-test recommended"`.
-
 ## Anti-Patterns
 
 - **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.

package/skills/slice-tasks/SKILL.md

@@ -5,6 +5,8 @@ model: sonnet
 effort: standard
 ---
 
+# story: e45s29
+
 # Slice Tasks
 
 > **Spine position:** Step 2 — scope-work → slice-tasks → plan-work.
@@ -37,6 +39,7 @@ Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical sli
    - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`)
    - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md
    - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs
+   - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text.
 
 5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest.
 

package/skills/smoke-test/REFERENCE.md

@@ -1,5 +1,16 @@
 # Smoke Test — Reference
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–12 | Navigation |
+| 14–31 | Runner script |
+| 33–42 | Configuration reference |
+| 44–53 | Verification |
+| 55–160 | Reference blocks 1–5 |
+
 ## Runner script
 
 A ready-to-use runner is provided for standalone operation:

package/skills/stocktake-skills/SKILL.md

@@ -1,3 +1,4 @@
+<!-- story: e45s12 -->
 ---
 name: stocktake-skills
 description: Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.
@@ -21,6 +22,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 
 ## Process
 
+0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
 2. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
@@ -52,6 +54,6 @@ Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls withi
 
 ## Verify
 
-→ verify: `test -f specs/STOCKTAKE-*.md && echo OK || echo MISSING`
+→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING`
 
 See [REFERENCE.md](REFERENCE.md) for checklist.

package/skills/validate-contracts/REFERENCE.md

@@ -1,5 +1,17 @@
 # Validate Contracts — Reference
 
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–14 | Navigation |
+| 16–24 | Integration |
+| 26–35 | Configuration |
+| 37–46 | Verification |
+| 48–170 | Reference blocks + Examples 1–6 |
+| 172–190 | Integration (duplicate) + Configuration + Verification |
+
 ## Integration
 
 - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.