bigpowers 2.1.3 → 2.2.0

package/plan-work/SKILL.md

@@ -10,179 +10,43 @@ Produce a detailed, verifiable implementation plan in the **active epic capsule
 
 > **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
 >
-> **RECURSIVE DISCIPLINE** — This lifecycle apply to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
 
 ## Pre-flight
 
-Before writing the plan, check if `define-success` has been run. If the task's success criteria are unclear, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.
+Read: `release-plan.yaml`, `product/SCOPE_LATEST.yaml`, active `epics/<capsule>/epic.yaml`, `tech-architecture/tech-stack.md`, `product/GLOSSARY_LATEST.yaml`.
 
-Read any existing `specs/` files: `release-plan.yaml`, `product/SCOPE_LATEST.yaml`, active epic capsule `epics/<capsule_dir>/epic.yaml`, `tech-architecture/tech-stack.md`, `product/GLOSSARY_LATEST.yaml`.
+> **ZOOM-OUT MANDATE** (v1.17.0) — If modifying an existing module: (1) State the module's **purpose**. (2) Name its **callers**. (3) List its **contracts**. Cannot answer all three? Stop — scope is misunderstood.
 
-> **ZOOM-OUT MANDATE** (v1.17.0 Guardrails) — If this plan modifies an existing module, function, or behavior:
-> 1. State the module's **purpose** — what is it responsible for?
-> 2. Name the **callers** — who depends on it?
-> 3. List the **contracts** — what invariants or interfaces must be preserved?
-> 
-> If you cannot answer all three without deep code archaeology, the scope is misunderstood. Stop and clarify with the user before writing steps.
+If this plan touches an existing module, run `assess-impact` first to understand blast radius.
 
-If this plan touches an existing module or symbol, run `assess-impact` first to understand the blast radius before writing steps.
+> **DISCOVERY MANDATE** (v1.18.0) — For external API integration, verify the API signature via local docs or search and quote at least one technical detail in the step's context.
 
-> **DISCOVERY MANDATE** (v1.18.0 Guardrails) — For any step involving external API integration (e.g., macOS CGEventTap, AWS SDK, Third-party libraries):
-> 1. You MUST perform a `google_web_search` or `grep_search` of local documentation to verify the API signature and constraints.
-> 2. You MUST quote at least one technical detail (method name, parameter, or error case) from your discovery in the step's context.
-> 
-> Plans that skip discovery for complex integrations are [SUS] and should be rejected.
+> **MULTIPLE INTERPRETATIONS (HARD GATE)** — If the task admits ≥2 valid interpretations, list them and get a user decision before drafting any steps.
 
-> **MULTIPLE INTERPRETATIONS (HARD GATE)** — If the task statement admits ≥2 valid interpretations, you must list them and get a decision from the user before drafting any steps. Do not assume intent.
+> **COMPLEXITY PUSHBACK (HARD GATE)** — Every new abstraction MUST include a one-sentence "Reason for Depth." If it can't be filled non-trivially, the abstraction is premature — use inline code instead.
 
-> **COMPLEXITY PUSHBACK (HARD GATE)** — Every step introducing a new abstraction (class, interface, helper, layer) MUST include a one-sentence "Reason for Depth": _"This abstraction is needed because [forcing function]..."_. If the sentence cannot be filled with a non-trivial reason, the abstraction is premature. Delete it and use inline code instead.
-
-> **SLOPCHECK (HARD GATE)** — For every external package proposed in the plan, run slopcheck (or manual registry check) and tag: `[OK]`, `[SUS]`, or `[SLOP]`. `[SUS]` and `[SLOP]` require explicit human approval before the step may execute. Document tags inline next to the package name.
+> **SLOPCHECK (HARD GATE)** — For every external package, tag it `[OK]`, `[SUS]`, or `[SLOP]`. `[SUS]`/`[SLOP]` require human approval before execution.
 
 ## Invocation modes
 
 - Default: full plan with zoom-out mandate, impact assessment, slopcheck
-- --fast (formerly plan-work-fast): Skip zoom-out and impact assessment. Use for tasks under 3 BCPs with no module interface changes.
+- `--fast`: Skip zoom-out and impact assessment. Use for tasks under 3 BCPs with no module interface changes.
 
 ## Process
 
-### 1. Explore the codebase
-
-Use the Agent tool with subagent_type=Explore to understand:
-- Affected modules and their current interfaces
-- Existing test patterns to follow
-- Any similar features already implemented (prior art)
-- Dependencies that will be needed
-
-### 2. Draft steps
-
-Break the implementation into the smallest possible steps where each step:
-- Leaves the codebase in a working state (tests pass)
-- Has exactly one observable outcome
-- Can be verified with a single runnable command
-
-**Red-flag check**: before moving to Step 3, name any rationalization you caught yourself making — skipping a gate, adding out-of-scope steps, omitting a verify command. Write them out; do not suppress them.
-
-### 3. Write capsule story spec + tasks
-
-Output two files inside the active epic capsule directory:
-
-**Story spec:** `specs/epics/<capsule>/eNNsYY-<slug>.md` — populated [countable-story-format](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.
-
-**Task checklist:** `specs/epics/<capsule>/eNNsYY-tasks.yaml` — decoupled execution steps:
-
-```yaml
-story_id: e01s01
-title: Login
-status: todo
-bcps: 3
-tasks:
-  - id: 1
-    description: "Add login form component tests"
-    verify: "npm test -- login-form.test.tsx"
-    status: todo
-```
-
-Update `specs/epics/<capsule>/epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
-
-<plan-template>
-
-### Story [X.Y]: [title] — Implementation Steps
-
-**type:** feat | fix | refactor  
-**context:** domain | infra  
-**Context**: [One paragraph: what this story implements and why]
-
-## Steps
-
-1. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
-
-2. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
-
-3. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
-
-...
-
-## Verification Script (Step-by-Step)
-
-[A human-readable, step-by-step script for the user to verify the story's outcome. Focus on user-observable behavior.]
+1. **Explore** — Use `Explore` subagent to understand affected modules, existing test patterns, similar prior art, and dependencies.
 
-1. [Action 1: e.g. Start the server]
-2. [Action 2: e.g. Open browser to http://localhost:3000]
-3. [Action 3: e.g. Click 'Login']
-4. [Observation: e.g. Verify that the login modal appears]
+2. **Draft steps** — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3.
 
-## Out of scope
+3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template.
 
-- [Explicit exclusions]
+4. **Verify step format** — Every step MUST follow: `N. <What to do> → verify: <runnable command>`. See [REFERENCE.md](REFERENCE.md) for good/bad examples.
 
-## Risks
-
-- [Anything that could go wrong and how to detect it early]
-
-</plan-template>
-
-### 4. Verify step format rules
-
-Every step MUST follow this exact format:
-```
-N. <What to do> → verify: <runnable command that proves it worked>
-```
-
-Good examples:
-```
-1. Add User model with email and name fields → verify: npm test -- user.test.ts
-2. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
-3. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts
-```
-
-Bad examples (no verify command):
-```
-1. Implement the user creation flow
-2. Write tests for the API
-```
-
-### 5. Review with user
-
-Before finalizing, confirm:
-- Does the step order make sense?
-- Is the granularity right (not too coarse, not too fine)?
-- Are the verify commands actually runnable in this project?
+5. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project.
 
 After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.
 
-## Sub-operations
-
-### Define Success (absorbed)
-
-Before planning, convert task statements into observable "step → verify: <cmd>" pairs:
-
-- Break the task into observable outcomes (behaviors) rather than implementation steps
-- Write pairs in the format: [What must be true] → verify: <runnable command>
-- Challenge completeness: are there any required behaviors not covered?
-- Get user confirmation: "Does this capture everything the task requires?"
-- Once confirmed, these pairs become the skeleton for plan-work steps
-
-### Zoom-Out Check (absorbed)
-
-When modifying an existing module, confirm scope is understood:
-
-- State the module's **purpose** — what is it responsible for?
-- Name the **callers** — who depends on it?
-- List the **contracts** — what invariants or interfaces must be preserved?
-
-If you cannot answer all three without deep code archaeology, scope is misunderstood. Clarify with the user before writing steps.
-
-### Slopcheck (absorbed)
-
-For every external package proposed in the plan, tag each with one of:
-
-- `[OK]` — package is mature, actively maintained, appropriate scope
-- `[SUS]` — package is suspiciously broad, has maintenance concerns, or unclear fit
-- `[SLOP]` — package is unmaintained, has known security issues, or out of scope
-
-`[SUS]` and `[SLOP]` require explicit human approval before the step may execute. Document tags inline next to the package name.
-
 ## Handoff
 
 Gate: READY -> next: kickoff-branch

package/release-branch/REFERENCE.md

@@ -0,0 +1,55 @@
+# Release Branch — Reference
+
+## PR body template (team-pr mode)
+
+```bash
+PR_TITLE="<type>(<scope>): <description>"
+echo "$PR_TITLE" | grep -vE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ ERROR: PR Title must follow Conventional Commits"
+
+gh pr create \
+  --title "$PR_TITLE" \
+  --body "$(cat <<'EOF'
+## Summary
+- [What this PR does]
+- [Key decisions made]
+
+## Verify
+- [ ] All tests pass
+- [ ] Coverage gates met (≥80% overall, ≥95% business logic)
+- [ ] CONVENTIONS.md compliance verified
+- [ ] PR Title follows Conventional Commits (for automated release)
+
+## specs/ artifacts
+- [List any specs/ files produced or updated]
+EOF
+)"
+```
+
+## Worktree cleanup details
+
+```bash
+# From the main repo root
+git worktree prune
+git worktree remove ../<branch-name> 2>/dev/null || true
+git branch -d <branch-name>
+```
+
+If `git worktree remove` fails due to uncommitted changes, ask: "There are uncommitted changes in the worktree. Force remove? (y/n)". If yes: `git worktree remove -f ../<branch-name>`.
+
+## Cycle-time recording
+
+After landing the branch, record delivery metrics for this story:
+
+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`:
+
+```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
+```

package/release-branch/SKILL.md

@@ -12,16 +12,14 @@ Finalize a completed feature branch: verify coverage gates, integrate onto `main
 
 ## Additional modes
 
-- --hotfix: Emergency fix. Cherry-pick to main plus immediate tag. Skip PR in solo profile.
+- `--hotfix`: Emergency fix. Cherry-pick to main plus immediate tag. Skip PR in solo profile.
 
 ## Integrate mode
 
-Choose mode from project profile or explicit user request:
-
 | Mode | When | Ship path |
 |------|------|-----------|
-| **solo-local** | `profiles/solo-git.md` or `specs/WORKFLOW-solo-git.md` active | `bash scripts/land-branch.sh <branch> "<conventional message>"` — no PR |
-| **team-pr** | Default, or collaboration / remote CI required | `gh pr create` → `gh pr merge --squash` (§6–7) |
+| **solo-local** | `profiles/solo-git.md` active | `bash scripts/land-branch.sh <branch> "<conventional message>"` |
+| **team-pr** | Default / remote CI required | `gh pr create` → `gh pr merge --squash` |
 
 If unsure and working alone, prefer **solo-local**.
 
@@ -29,168 +27,70 @@ If unsure and working alone, prefer **solo-local**.
 
 ### 1. Final verification
 
-Run the full suite one last time on the feature branch:
-
 ```bash
-<full test command>
-<typecheck command>
-<lint command>
-# Verify Conventional Commits history
-git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ ERROR: Non-conventional commits found" || echo "✅ Commits verified"
+<full test command> && <typecheck command> && <lint command>
+git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ Non-conventional commits found" || echo "✅ Commits verified"
 ```
 
-- [ ] All tests pass
-- [ ] No type errors
-- [ ] No lint violations
-- [ ] All commits in branch history follow Conventional Commits 1.0.0
+- [ ] All tests pass, no type errors, no lint violations, all commits follow Conventional Commits
 
 ### 2. Coverage check
 
-Verify coverage meets the project gates:
-
-- [ ] Overall coverage ≥ 80%
-- [ ] Business logic / domain layer coverage ≥ 95%
-
-If coverage is below the gate, stop and return to `develop-tdd` to add missing tests.
+- [ ] Overall coverage ≥ 80%; business logic coverage ≥ 95%
 
 ### 3. Diff review
 
-```bash
-git diff main...HEAD --stat
-git log main...HEAD --oneline
-```
-
-Confirm:
-- [ ] All commits are intentional — no debug commits, no "WIP" commits
-- [ ] No secrets, credentials, or personal data in the diff
-- [ ] CONVENTIONS.md compliance across all changes
+- [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
 
 ### 4. Decision
 
-Present the user with the options:
-
-| Option | When to choose |
-|--------|---------------|
-| **Release (solo-local)** | Feature complete; solo profile active — land via script |
-| **Open PR for Release** | Feature complete; team-pr mode or remote CI gate needed |
-| **Keep branch** | More work needed; preserve for later |
-| **Discard** | Approach was wrong; start over |
+Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
 
 ### 5. Solo-local integrate
 
-From the **primary** repository root (not the feature worktree):
-
-1. Run `commit-message` to produce the squash commit subject.
-2. Land:
-
+Run `commit-message` to produce the squash commit subject, then:
 ```bash
 bash scripts/land-branch.sh <task-slug> "feat(scope): description"
 ```
 
-The script will: update `main`, squash-merge, commit, push, remove worktree, delete branch, and leave you on `main`.
-
-Skip duplicate cleanup in §8 if the script succeeded.
-
 ### 6. Create PR (team-pr only)
 
-The PR title is the **single source of truth** for the version bump. It MUST follow Conventional Commits.
-
-```bash
-PR_TITLE="<type>(<scope>): <description>"
-echo "$PR_TITLE" | grep -vE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$" && echo "❌ ERROR: PR Title must follow Conventional Commits"
-
-gh pr create \
-  --title "$PR_TITLE" \
-  --body "$(cat <<'EOF'
-## Summary
-- [What this PR does]
-- [Key decisions made]
-
-## Verify
-- [ ] All tests pass
-- [ ] Coverage gates met (≥80% overall, ≥95% business logic)
-- [ ] CONVENTIONS.md compliance verified
-- [ ] PR Title follows Conventional Commits (for automated release)
-
-## specs/ artifacts
-- [List any specs/ files produced or updated]
-EOF
-)"
-```
+See [REFERENCE.md](REFERENCE.md) for the full PR body template and gh commands.
 
 ### 7. Merge (team-pr only)
 
-Wait for CI to pass. Merge using **Squash and Merge** so the PR title becomes the commit message on `main`.
-
 ```bash
 gh pr merge --squash --delete-branch
 ```
 
-`semantic-release` will automatically:
-1. Detect the commit on `main`.
-2. Determine the SemVer bump from the commit type.
-3. Tag the repo (e.g., `v2.1.0`).
-4. Generate release notes.
+`semantic-release` auto-detects the commit, bumps SemVer, tags the repo, generates release notes.
 
 ### 7a. Archive completed epic capsule
 
-> **HARD GATE** — When an epic's stories are all complete (all marked `done` in `execution-status.yaml`), move the epic capsule directory to the archive.
+> **HARD GATE** — When all epic stories are done (all `done` in `execution-status.yaml`), archive the capsule:
 
 ```bash
-EPIC_CAPSULE="specs/epics/eNN-slug"
-if [ -d "$EPIC_CAPSULE" ]; then
-  mkdir -p specs/epics/archive
-  mv "$EPIC_CAPSULE" "specs/epics/archive/"
-  echo "Archived: $EPIC_CAPSULE → specs/epics/archive/"
-fi
+mv specs/epics/eNN-slug specs/epics/archive/
 ```
 
-**Rationale:** Archiving completed epics removes inactive context from the agent workspace, preserving token budget (C2/C6). The capsule directory (epic.yaml + stories + tasks + epic-local ADRs) moves as a unit — nothing is orphaned.
-
-### 8. Clean up worktree (if not done by land-branch.sh)
+### 8. Clean up worktree
 
 ```bash
-# From the main repo root
 git worktree prune
 git worktree remove ../<branch-name> 2>/dev/null || true
 git branch -d <branch-name>
 ```
 
-- If `git worktree remove` fails due to uncommitted changes, ask the user: "There are uncommitted changes in the worktree. Force remove? (y/n)". If yes: `git worktree remove -f ../<branch-name>`.
-- If the directory `../<branch-name>` is already missing, `git worktree remove` might fail; the `|| true` ensures the process continues to branch deletion.
-
 ### 8a. Cycle-time recording
 
-After landing the branch, record delivery metrics for this story:
-
-1. Write `metrics.story_end` with the current ISO 8601 timestamp to `specs/state.yaml`
-2. Compute `cycle_minutes`: `story_end` minus `story_start` in minutes
-3. Compute `bcp_per_hour`: `epic_cycle.story_bcps` divided by `(cycle_minutes / 60)`
-4. Append a row to `specs/metrics/cycle-times.yaml` with fields: `id`, `bcps`, `start`, `end`, `cycle_minutes`, `bcp_per_hour`
-
-Example row:
-```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
-```
+After landing, record delivery metrics. See [REFERENCE.md](REFERENCE.md) for fields and example row.
 
-### 9. Return to main (primary worktree)
+### 9. Return to main
 
 ```bash
-cd <primary-repo-root>
-git checkout main   # or master
-git status
-pwd
+git checkout main && git status && pwd
 ```
 
-Confirm:
-- [ ] Current branch is `main` (or project default)
-- [ ] cwd is the primary repository root, not `../<task-slug>`
-
 Report: "Branch released. Integrate mode: <solo-local|team-pr>. cwd: $(pwd) on $(git branch --show-current)."
 
 ## Handoff

package/request-review/SKILL.md

@@ -62,7 +62,7 @@ When the reviewer returns:
 - Compute the quality score: `100 × (total_items − must_fix − should_fix) / total_items`
 - Report the score to the user
 
-> **HARD GATE** — If score < 94%, do NOT merge. Run `respond-review` to resolve must-fix and should-fix findings first.
+> **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.
 
 ### 4. Hand off to respond-review
 

package/scripts/audit-compliance.sh

@@ -157,7 +157,7 @@ process_step() {
 
   local sanitized_step
   sanitized_step=$(echo "$step" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  local step_script="specs/audit/steps/${sanitized_step}.sh"
+  local step_script="specs/verifications/steps/${sanitized_step}.sh"
 
   if [[ -f "$step_script" ]]; then
     echo "    [EXEC] Gathering evidence: $step_script"
@@ -182,8 +182,8 @@ run_audit_file() {
   echo "------------------------------------------------------------"
   echo "FEATURE: $FEATURE_FILE"
   
-  local REPORT_FILE="specs/audit/reports/audit-$(basename "$FEATURE_FILE" .feature)-$(date +%Y%m%d-%H%M%S).md"
-  mkdir -p specs/audit/reports
+  local REPORT_FILE="specs/verifications/reports/audit-$(basename "$FEATURE_FILE" .feature)-$(date +%Y%m%d-%H%M%S).md"
+  mkdir -p specs/verifications/reports
 
   echo "# Audit Report: $FEATURE_FILE" > "$REPORT_FILE"
   echo "Date: $(date)" >> "$REPORT_FILE"
@@ -249,6 +249,18 @@ echo "============================================================"
 echo "Global Audit Summary:"
 echo "  TOTAL PASS: $TOTAL_GLOBAL_PASS"
 echo "  TOTAL FAIL: $TOTAL_GLOBAL_FAIL"
+TOTAL_GLOBAL_ALL=$((TOTAL_GLOBAL_PASS + TOTAL_GLOBAL_FAIL))
+if [[ $TOTAL_GLOBAL_ALL -gt 0 ]]; then
+  SCORE=$(awk "BEGIN { printf \"%d\", $TOTAL_GLOBAL_PASS * 100 / $TOTAL_GLOBAL_ALL }")
+else
+  SCORE=0
+fi
+echo "  SCORE: ${SCORE}% (threshold 94%)"
+if [[ $SCORE -ge 94 ]]; then
+  echo "  GATE: PASS"
+else
+  echo "  GATE: FAIL (below 94%)"
+fi
 echo "============================================================"
 
 if [[ $TOTAL_GLOBAL_FAIL -gt 0 ]]; then

package/scripts/check-skill-size.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Skill size guard — enforces tiered line caps on every */SKILL.md file.
+# Run after any SKILL.md edits to validate size compliance.
+# Critical-path skills: 150 lines max. All others: 120 lines max.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+ERRORS=0
+
+report_oversize() {
+  echo "FAIL: $*" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+# Critical-path skills with 150-line cap
+CRITICAL_PATH=(
+  "survey-context"
+  "run-planning"
+  "scope-work"
+  "slice-tasks"
+  "plan-work"
+  "plan-release"
+  "define-success"
+  "kickoff-branch"
+  "develop-tdd"
+  "execute-plan"
+  "build-epic"
+  "verify-work"
+  "audit-code"
+  "request-review"
+  "release-branch"
+  "orchestrate-project"
+  "investigate-bug"
+  "diagnose-root"
+  "fix-bug"
+  "session-state"
+  "seed-conventions"
+  "migrate-spec"
+  "elaborate-spec"
+  "grill-me"
+  "grill-with-docs"
+)
+
+# Check all */SKILL.md files
+for skill_file in */SKILL.md; do
+  skill_name="${skill_file%/SKILL.md}"
+  line_count=$(wc -l < "$skill_file")
+
+  # Determine cap based on critical-path membership
+  is_critical=0
+  for critical in "${CRITICAL_PATH[@]}"; do
+    if [[ "$skill_name" == "$critical" ]]; then
+      is_critical=1
+      break
+    fi
+  done
+
+  if [[ $is_critical -eq 1 ]]; then
+    CAP=150
+  else
+    CAP=120
+  fi
+
+  if [[ $line_count -gt $CAP ]]; then
+    report_oversize "$skill_name/SKILL.md is $line_count lines (cap $CAP)"
+  fi
+done
+
+# Summary
+echo "---"
+if [[ "$ERRORS" -eq 0 ]]; then
+  echo "check-skill-size: ALL within cap"
+  exit 0
+else
+  echo "check-skill-size: $ERRORS file(s) over cap" >&2
+  exit 1
+fi

package/scripts/generate-reference-tables.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Regenerates the auto-generated catalog section in docs/references/model-profiles.md
+# from live */SKILL.md frontmatter. Run after any SKILL.md addition/rename.
+# Called by sync-skills.sh and npm version hooks.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TARGET="$REPO_ROOT/docs/references/model-profiles.md"
+
+cd "$REPO_ROOT"
+
+# --- 1. Collect live skill→model pairs ---
+declare -a ROWS=()
+while IFS= read -r line; do
+  skill_dir="${line%%/SKILL.md*}"
+  model_raw="${line##*model: }"
+  model="${model_raw// /}"
+  ROWS+=("$skill_dir $model")
+done < <(grep -r "^model:" */SKILL.md | sed 's|/SKILL.md:model:||' | sort)
+
+TOTAL=${#ROWS[@]}
+
+# --- 2. Build replacement block ---
+BLOCK="<!-- AUTO-GENERATED-CATALOG: begin — do not edit manually; run scripts/generate-reference-tables.sh -->
+| Skill | Model |
+|-------|-------|"
+for row in "${ROWS[@]}"; do
+  skill="${row%% *}"
+  model="${row##* }"
+  # capitalise first letter for display
+  model_cap="$(echo "${model:0:1}" | tr '[:lower:]' '[:upper:]')${model:1}"
+  BLOCK+="
+| \`$skill\` | **$model_cap** |"
+done
+BLOCK+="
+
+Total: **$TOTAL** skills — verify with \`ls -d \*/SKILL.md | wc -l\`
+<!-- AUTO-GENERATED-CATALOG: end -->"
+
+# --- 3. Splice block into target file ---
+# Replace between marker comments if they exist; otherwise append.
+if grep -q "AUTO-GENERATED-CATALOG: begin" "$TARGET"; then
+  python3 - "$TARGET" "$BLOCK" <<'PYEOF'
+import sys, re
+path = sys.argv[1]
+block = sys.argv[2]
+text = open(path).read()
+new_text = re.sub(
+    r'<!-- AUTO-GENERATED-CATALOG: begin.*?<!-- AUTO-GENERATED-CATALOG: end -->',
+    block,
+    text,
+    flags=re.DOTALL
+)
+open(path, 'w').write(new_text)
+PYEOF
+else
+  printf '\n\n## Full Skill Catalog (auto-generated)\n\n%s\n' "$BLOCK" >> "$TARGET"
+fi
+
+# --- 4. Update the "expect N" count assertion (legacy line) ---
+# Replaces "expect NN" with the live count so the prose stays accurate.
+sed -i.bak "s/expect [0-9]*/expect $TOTAL/" "$TARGET" && rm -f "${TARGET}.bak"
+
+echo "generate-reference-tables: updated $TARGET ($TOTAL skills)"

package/scripts/project-survey.sh

@@ -13,7 +13,7 @@ specs_files=""
 if [[ "$has_specs" == "true" ]]; then
   specs_files=$( {
     ls specs/*.yaml 2>/dev/null || true
-    ls specs/requirements/*.yaml 2>/dev/null || true
+    ls specs/product/*.yaml 2>/dev/null || true
     ls specs/*.md 2>/dev/null || true
   } | xargs -n1 basename 2>/dev/null | sort -u | tr '\n' ',' | sed 's/,$//')
 fi
@@ -34,7 +34,7 @@ if [[ -f "specs/state.yaml" ]]; then
   esac
 elif [[ -f "specs/release-plan.yaml" ]]; then
   phase="Plan"
-elif [[ -f "specs/requirements/SCOPE_LATEST.yaml" ]] || [[ -f "specs/SCOPE.md" ]]; then
+elif [[ -f "specs/product/SCOPE_LATEST.yaml" ]] || [[ -f "specs/SCOPE.md" ]]; then
   phase="Design"
 elif [[ "$current_branch" != "main" && "$current_branch" != "master" ]]; then
   phase="Initiate"