bigpowers 2.49.0 → 2.51.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.49.0",
+  "version": "2.51.0",
   "description": "72 skills — 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/.pi/prompts/evolve-skill.md

@@ -9,19 +9,20 @@ description: Benchmark-gated skill evolution — consume bigpowers-benchmark rep
 
 ## Loop
 
-1. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
+1. **Regression gate** — Run `bash scripts/run-golden-suite.sh` to catch mechanical regressions (compliance, sync pipeline, size budget) before spending time on benchmark evals. If golden suite fails, fix regressions first — they are pre-requisites for any capability improvement.
+2. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
 
-2. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
+3. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
 
-3. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
+4. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
 
-4. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
+5. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
 
-5. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
+6. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
    - **IMPROVED or STABLE** → advance to step 6.
    - **REGRESSION** (`new pass_at_k < baseline`) → revert the change and loop back to step 3.
 
-6. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
+7. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
 
 ## Verify
 

package/.pi/prompts/plan-release.md

@@ -2,7 +2,6 @@
 description: "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics."
 ---
 
-
 # Plan Release
 
 > **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.

package/.pi/prompts/release-branch.md

@@ -99,11 +99,16 @@ mv specs/epics/eNN-slug specs/epics/archive/
 
 > **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
 
-After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
+After push (solo-local step 5 or team-pr step 7), run the CI polling script:
 
-See [REFERENCE.md](REFERENCE.md)
+```bash
+bash scripts/wait-for-ci.sh --timeout 600 --interval 30
+```
+
+The script auto-discovers workflow runs for the pushed commit and polls until completion.
+See [REFERENCE.md](REFERENCE.md) for exit code semantics and git-only fallback.
 
-- [ ] CI workflow passes after push
+- [ ] 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 the CI failure URL
 
@@ -117,7 +122,17 @@ git branch -d <branch-name>
 
 ### 8a. Cycle-time recording
 
-After landing, record delivery metrics. See [REFERENCE.md](REFERENCE.md) for fields and example row.
+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
+```
+
+This replaces the previous hand-arithmetic approach (story_end minus story_start).
+See [REFERENCE.md](REFERENCE.md) for the git-hours model and field definitions.
 
 ### 9. Return to main
 
@@ -175,22 +190,65 @@ If `git worktree remove` fails due to uncommitted changes, ask: "There are uncom
 
 ## Cycle-time recording
 
-After landing the branch, record delivery metrics for this story:
+After landing the branch, record delivery metrics using the git-derived,
+additive script (replaces hand-arithmetic):
+
+```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
+```
+
+This appends a row to the cycle-times ledger with two separated metrics:
+
+- **effort_hours** — ADDITIVE. Idle-stripped estimated effort from git commit
+  history (git-hours model: 120-min session threshold, 120-min first-commit pad).
+  Sums exactly to whole-repo effort. NO hand-arithmetic, NO wall-clock includes.
+- **lead_time_minutes** — calendar latency from first commit to merge.
+  Median-aggregated across stories; NEVER summed.
+
+The script also runs an additivity self-check: Σ(story effort) == whole-repo effort
+within rounding tolerance.
+
+### Why not story_start minus story_end?
 
-1. Write `metrics.story_end` (ISO 8601) to `specs/state.yaml`
-2. Compute `cycle_minutes`: `story_end` minus `story_start` in minutes
-3. Compute `bcp_per_hour`: `epic_cycle.story_bcps / (cycle_minutes / 60)`
-4. Append a row to `specs/metrics/cycle-times.yaml`:
+The previous hand-arithmetic approach (survey-context writes `story_start`,
+release-branch writes `story_end`, agent hand-computes `cycle_minutes`) was
+retired because:
 
-```yaml
-- id: e01s01
-  bcps: 3
-  start: "2026-06-10T09:45:00Z"
-  end: "2026-06-10T11:15:00Z"
-  cycle_minutes: 90
-  bcp_per_hour: 2.0
+1. It was **agent-self-reported** — trivially fabricated or mis-subtracted.
+2. Wall-clock included **overnight/weekend/UAT gaps** — calendar latency,
+   not coding effort.
+3. The `bcp_per_hour` metric was **computationally meaningless** (velocity
+   derived from a latency measurement).
+
+The new approach derives effort from commit history (objective, reproducible)
+and lead time from first commit → merge (honest calendar latency). See
+`docs/references/bcp.md` for BCP sizing context and
+`scripts/record-cycle-time.sh` for the full algorithm.
+
+---
+
+## CI verification
+
+The CI polling logic has been extracted to `scripts/wait-for-ci.sh`.
+See the script's `--help` for usage. Step 7b of the main SKILL.md invokes it directly:
+
+```bash
+bash scripts/wait-for-ci.sh --timeout 600 --interval 30
 ```
 
+**Exit codes:**
+- **0** — all workflows green. Set `release.ci_verified: true` in state.yaml.
+- **1** — at least one workflow failed. Prints failure URLs. Set `handoff.next_skill = fix-bug`.
+- **2** — timeout. CI did not complete. Retry or investigate.
+- **0 with warning** — `gh` CLI not available, git-only fallback confirmed push landed but CI status unverified.
+
+The script handles: auto-discovery of all workflows for the current
+branch/commit, polling until completion, success/failure/timeout exit codes,
+and git-only fallback when `gh` CLI is unavailable.
+
 ---
 
 ## Solo-local fallback detail
@@ -231,43 +289,3 @@ git push origin "$DEFAULT_BRANCH"
 # Clean up local feature branch
 git branch -d "$FEATURE_BRANCH"
 ```
-
----
-
-## Reference block 2
-
-```bash
-echo "==> Polling CI for main branch..."
-TIMEOUT=600   # 10 minutes
-INTERVAL=30   # poll every 30 seconds
-ELAPSED=0
-
-while [ $ELAPSED -lt $TIMEOUT ]; do
-  CI_JSON=$(gh run list --limit 1 --branch main --workflow CI --json status,conclusion,headSha,databaseId 2>/dev/null)
-  CI_STATUS=$(echo "$CI_JSON" | jq -r '.[0].status // "unknown"')
-  CI_CONCLUSION=$(echo "$CI_JSON" | jq -r '.[0].conclusion // ""')
-  CI_SHA=$(echo "$CI_JSON" | jq -r '.[0].headSha // ""')
-  CI_ID=$(echo "$CI_JSON" | jq -r '.[0].databaseId // ""')
-
-  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "success" ]; then
-    echo "OK: CI passed for $(git rev-parse --short HEAD)"
-    bp-yaml-set.sh specs/state.yaml release.ci_verified true 2>/dev/null || \
-      echo "  (bp-yaml-set not available — manually set release.ci_verified: true in state.yaml)"
-    break
-  fi
-
-  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "failure" ]; then
-    echo "FAIL: CI failed for $(git rev-parse --short HEAD)"
-    echo "  Run URL: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$CI_ID"
-    echo "  Handoff to fix-bug with the failure URL above."
-    return 1
-  fi
-
-  sleep $INTERVAL
-  ELAPSED=$((ELAPSED + INTERVAL))
-  echo "  Waiting... (${ELAPSED}s / ${TIMEOUT}s)"
-done
-
-echo "FAIL: CI did not complete within ${TIMEOUT}s timeout"
-return 1
-```

package/.pi/prompts/session-state.md

@@ -9,6 +9,8 @@ description: Track implementation decisions and progress in specs/state.yaml to
 
 Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
 
+Session-state implements the **isolate** strategy from the context-engineering framework (docs/references/context-engineering.md): each agent gets exactly the context it needs — no more — by recording decisions so the next agent can cold-start without replaying history. The four strategies (write, select, compress, isolate) work together: session-state handles isolation, terse-mode handles compression, survey-context handles selection, and CONVENTIONS.md ensures token-efficient writing.
+
 ## Goal
 
 Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.

package/.pi/prompts/survey-context.md

@@ -113,7 +113,7 @@ Report blockers first, before recommendations.
 
 ### 8. Record story start timestamp
 
-At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` for cycle-time tracking.
+At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` as an **informational progress marker only** — not a measurement input. Cycle-time metrics are now derived from git commit history via `scripts/record-cycle-time.sh` (see `skills/release-branch/REFERENCE.md` §Cycle-time recording).
 
 ## Utility outputs
 

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

@@ -11,19 +11,20 @@ model: opus
 
 ## Loop
 
-1. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
+1. **Regression gate** — Run `bash scripts/run-golden-suite.sh` to catch mechanical regressions (compliance, sync pipeline, size budget) before spending time on benchmark evals. If golden suite fails, fix regressions first — they are pre-requisites for any capability improvement.
+2. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
 
-2. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
+3. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
 
-3. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
+4. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
 
-4. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
+5. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
 
-5. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
+6. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
    - **IMPROVED or STABLE** → advance to step 6.
    - **REGRESSION** (`new pass_at_k < baseline`) → revert the change and loop back to step 3.
 
-6. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
+7. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
 
 ## Verify
 

package/.pi/skills/plan-release/SKILL.md

@@ -4,7 +4,6 @@ description: "\"RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/r
 model: sonnet
 ---
 
-
 # Plan Release
 
 > **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.

package/.pi/skills/release-branch/SKILL.md

@@ -101,11 +101,16 @@ mv specs/epics/eNN-slug specs/epics/archive/
 
 > **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
 
-After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
+After push (solo-local step 5 or team-pr step 7), run the CI polling script:
 
-See [REFERENCE.md](REFERENCE.md)
+```bash
+bash scripts/wait-for-ci.sh --timeout 600 --interval 30
+```
+
+The script auto-discovers workflow runs for the pushed commit and polls until completion.
+See [REFERENCE.md](REFERENCE.md) for exit code semantics and git-only fallback.
 
-- [ ] CI workflow passes after push
+- [ ] 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 the CI failure URL
 
@@ -119,7 +124,17 @@ git branch -d <branch-name>
 
 ### 8a. Cycle-time recording
 
-After landing, record delivery metrics. See [REFERENCE.md](REFERENCE.md) for fields and example row.
+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
+```
+
+This replaces the previous hand-arithmetic approach (story_end minus story_start).
+See [REFERENCE.md](REFERENCE.md) for the git-hours model and field definitions.
 
 ### 9. Return to main
 
@@ -177,22 +192,65 @@ If `git worktree remove` fails due to uncommitted changes, ask: "There are uncom
 
 ## Cycle-time recording
 
-After landing the branch, record delivery metrics for this story:
+After landing the branch, record delivery metrics using the git-derived,
+additive script (replaces hand-arithmetic):
+
+```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
+```
+
+This appends a row to the cycle-times ledger with two separated metrics:
+
+- **effort_hours** — ADDITIVE. Idle-stripped estimated effort from git commit
+  history (git-hours model: 120-min session threshold, 120-min first-commit pad).
+  Sums exactly to whole-repo effort. NO hand-arithmetic, NO wall-clock includes.
+- **lead_time_minutes** — calendar latency from first commit to merge.
+  Median-aggregated across stories; NEVER summed.
+
+The script also runs an additivity self-check: Σ(story effort) == whole-repo effort
+within rounding tolerance.
+
+### Why not story_start minus story_end?
 
-1. Write `metrics.story_end` (ISO 8601) to `specs/state.yaml`
-2. Compute `cycle_minutes`: `story_end` minus `story_start` in minutes
-3. Compute `bcp_per_hour`: `epic_cycle.story_bcps / (cycle_minutes / 60)`
-4. Append a row to `specs/metrics/cycle-times.yaml`:
+The previous hand-arithmetic approach (survey-context writes `story_start`,
+release-branch writes `story_end`, agent hand-computes `cycle_minutes`) was
+retired because:
 
-```yaml
-- id: e01s01
-  bcps: 3
-  start: "2026-06-10T09:45:00Z"
-  end: "2026-06-10T11:15:00Z"
-  cycle_minutes: 90
-  bcp_per_hour: 2.0
+1. It was **agent-self-reported** — trivially fabricated or mis-subtracted.
+2. Wall-clock included **overnight/weekend/UAT gaps** — calendar latency,
+   not coding effort.
+3. The `bcp_per_hour` metric was **computationally meaningless** (velocity
+   derived from a latency measurement).
+
+The new approach derives effort from commit history (objective, reproducible)
+and lead time from first commit → merge (honest calendar latency). See
+`docs/references/bcp.md` for BCP sizing context and
+`scripts/record-cycle-time.sh` for the full algorithm.
+
+---
+
+## CI verification
+
+The CI polling logic has been extracted to `scripts/wait-for-ci.sh`.
+See the script's `--help` for usage. Step 7b of the main SKILL.md invokes it directly:
+
+```bash
+bash scripts/wait-for-ci.sh --timeout 600 --interval 30
 ```
 
+**Exit codes:**
+- **0** — all workflows green. Set `release.ci_verified: true` in state.yaml.
+- **1** — at least one workflow failed. Prints failure URLs. Set `handoff.next_skill = fix-bug`.
+- **2** — timeout. CI did not complete. Retry or investigate.
+- **0 with warning** — `gh` CLI not available, git-only fallback confirmed push landed but CI status unverified.
+
+The script handles: auto-discovery of all workflows for the current
+branch/commit, polling until completion, success/failure/timeout exit codes,
+and git-only fallback when `gh` CLI is unavailable.
+
 ---
 
 ## Solo-local fallback detail
@@ -233,43 +291,3 @@ git push origin "$DEFAULT_BRANCH"
 # Clean up local feature branch
 git branch -d "$FEATURE_BRANCH"
 ```
-
----
-
-## Reference block 2
-
-```bash
-echo "==> Polling CI for main branch..."
-TIMEOUT=600   # 10 minutes
-INTERVAL=30   # poll every 30 seconds
-ELAPSED=0
-
-while [ $ELAPSED -lt $TIMEOUT ]; do
-  CI_JSON=$(gh run list --limit 1 --branch main --workflow CI --json status,conclusion,headSha,databaseId 2>/dev/null)
-  CI_STATUS=$(echo "$CI_JSON" | jq -r '.[0].status // "unknown"')
-  CI_CONCLUSION=$(echo "$CI_JSON" | jq -r '.[0].conclusion // ""')
-  CI_SHA=$(echo "$CI_JSON" | jq -r '.[0].headSha // ""')
-  CI_ID=$(echo "$CI_JSON" | jq -r '.[0].databaseId // ""')
-
-  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "success" ]; then
-    echo "OK: CI passed for $(git rev-parse --short HEAD)"
-    bp-yaml-set.sh specs/state.yaml release.ci_verified true 2>/dev/null || \
-      echo "  (bp-yaml-set not available — manually set release.ci_verified: true in state.yaml)"
-    break
-  fi
-
-  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "failure" ]; then
-    echo "FAIL: CI failed for $(git rev-parse --short HEAD)"
-    echo "  Run URL: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$CI_ID"
-    echo "  Handoff to fix-bug with the failure URL above."
-    return 1
-  fi
-
-  sleep $INTERVAL
-  ELAPSED=$((ELAPSED + INTERVAL))
-  echo "  Waiting... (${ELAPSED}s / ${TIMEOUT}s)"
-done
-
-echo "FAIL: CI did not complete within ${TIMEOUT}s timeout"
-return 1
-```

package/.pi/skills/session-state/SKILL.md

@@ -11,6 +11,8 @@ model: haiku
 
 Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
 
+Session-state implements the **isolate** strategy from the context-engineering framework (docs/references/context-engineering.md): each agent gets exactly the context it needs — no more — by recording decisions so the next agent can cold-start without replaying history. The four strategies (write, select, compress, isolate) work together: session-state handles isolation, terse-mode handles compression, survey-context handles selection, and CONVENTIONS.md ensures token-efficient writing.
+
 ## Goal
 
 Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.

package/.pi/skills/survey-context/SKILL.md

@@ -115,7 +115,7 @@ Report blockers first, before recommendations.
 
 ### 8. Record story start timestamp
 
-At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` for cycle-time tracking.
+At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` as an **informational progress marker only** — not a measurement input. Cycle-time metrics are now derived from git commit history via `scripts/record-cycle-time.sh` (see `skills/release-branch/REFERENCE.md` §Cycle-time recording).
 
 ## Utility outputs
 

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# [2.51.0](https://github.com/danielvm-git/bigpowers/compare/v2.50.0...v2.51.0) (2026-07-03)
+
+
+### Bug Fixes
+
+* **compliance:** exit 0 when score meets threshold regardless of known failures ([ab165a6](https://github.com/danielvm-git/bigpowers/commit/ab165a6ee4e0c7caf0c6e6e237fe8fa07e94c306))
+* **e34:** regenerate artifacts and trim plan-release SKILL.md to 150 lines ([6112dcb](https://github.com/danielvm-git/bigpowers/commit/6112dcbade1e0ac8189af94f382ca005edd85663))
+* **release-branch:** poll CI before declaring success ([484c394](https://github.com/danielvm-git/bigpowers/commit/484c3949c48482f8e5ed6dc11890ef48c2f1929a))
+* **release-branch:** trim SKILL.md to 149 lines under 150-line cap ([1cd3cea](https://github.com/danielvm-git/bigpowers/commit/1cd3ceac6991d806730f7a22bece5cddf9a024ee))
+
+
+### Features
+
+* **e34:** context engineering layer — reference doc, effort frontmatter, vocabulary ([8ae8faa](https://github.com/danielvm-git/bigpowers/commit/8ae8faabe4d484dbc8cefb994858593362e92ede))
+* **e40:** metrics integrity — git-derived effort, OKF provenance gate ([c590397](https://github.com/danielvm-git/bigpowers/commit/c5903973e06d81a4c67252556558c015469e4beb))
+
+# [2.50.0](https://github.com/danielvm-git/bigpowers/compare/v2.49.0...v2.50.0) (2026-07-03)
+
+
+### Features
+
+* **e31:** size budget, pre-merge mandate, evolve-skill integration ([#46](https://github.com/danielvm-git/bigpowers/issues/46)) ([fa1dd52](https://github.com/danielvm-git/bigpowers/commit/fa1dd52276d0b6476b892f6fd6eed77eac7c5d41))
+
 # [2.49.0](https://github.com/danielvm-git/bigpowers/compare/v2.48.0...v2.49.0) (2026-07-03)
 
 

package/CLAUDE.md

@@ -20,6 +20,17 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 | Typecheck | N/A (Markdown / Bash project) |
 | CI platform | GitHub Actions (`.github/workflows/publish.yml`, `sync-skills.yml`) |
 | Compliance | `npm run compliance` |
+| Golden Suite | `bash scripts/run-golden-suite.sh` |
+
+### Pre-Merge Checklist
+
+Before opening a PR or landing a branch, run:
+
+```bash
+npm run compliance && bash scripts/run-golden-suite.sh
+```
+
+If any gate fails, fix before merging. Run `--baseline` after any intentional increase in skill count or structure.
 
 ## Architecture
 
@@ -41,6 +52,15 @@ Collection of verb-noun skills under `skills/`, each with a SKILL.md source file
 
 ## Token Management
 
+Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`):
+
+- **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless tests. Don't restate code in comments.
+- **Select (include only what's relevant):** Use `bts_map` for ranked file lists, `survey-context` for phase bootstrap. Don't read files you don't need.
+- **Compress (reduce without losing structure):** Use `bts_compress` or pipe through `sqz compress`. Use `rtk` for build/test/git output (60-99% savings). Prefer `terse-mode` when context is heavy.
+- **Isolate (partition work):** Use `kickoff-branch` for isolated worktrees, `dispatch-agents` for parallel tasks with disjoint scopes, `session-state` for cold-start handoff.
+
+**Effort classification:** Skills carry an `effort:` frontmatter field (`light` | `standard` | `heavy`). Prefer `light` skills for bootstrap/status checks; reserve `heavy` for epic builds and multi-phase planning.
+
 - **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.
 - **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.
 - **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.

package/CONVENTIONS.md

@@ -28,6 +28,17 @@ All changes to this repository MUST follow the [Conventional Commits 1.0.0](http
 - Never call GitHub REST API directly (curl, fetch, etc.)
 - Never create GitHub issues from automated workflows — produce local .md files in specs/ instead
 
+### Pre-Merge Golden Gate
+
+Before merging any branch, run the deterministic golden suite:
+
+```bash
+bash scripts/run-golden-suite.sh
+```
+
+This runs compliance → G-04 self-test. If any gate fails, the merge is blocked.
+Pin a fresh baseline with `--baseline` after major structure changes.
+
 ## Agent Workflow Mandates
 
 **AGENTS MUST NEVER BYPASS THE BIGPOWERS WORKFLOW.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.49.0",
+  "version": "2.51.0",
   "description": "72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/audit-compliance.sh

@@ -258,11 +258,8 @@ fi
 echo "  SCORE: ${SCORE}% (threshold 94%)"
 if [[ $SCORE -ge 94 ]]; then
   echo "  GATE: PASS"
+  exit 0
 else
   echo "  GATE: FAIL (below 94%)"
-fi
-echo "============================================================"
-
-if [[ $TOTAL_GLOBAL_FAIL -gt 0 ]]; then
   exit 1
 fi