bigpowers 2.34.0 → 2.34.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.34.0",
-  "description": "61 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.34.2",
+  "description": "70 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
     "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh",
@@ -44,7 +44,8 @@
     "url": "https://github.com/danielvm-git/bigpowers.git"
   },
   "bin": {
-    "bigpowers": "./bin/bigpowers.js"
+    "bigpowers": "./bin/bigpowers.js",
+    "bigpowers-dashboard": "./dashboard/bin/dashboard.js"
   },
   "engines": {
     "node": ">=14.0.0"

package/publish-package/REFERENCE.md

@@ -0,0 +1,239 @@
+# Publish Package — Reference
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Verify prerequisites and show publish command without executing |
+| `--registry <type>` | Force registry type (skip auto-detection) |
+| `--otp <code>` | One-time password for npm 2FA |
+| `--no-verify` | Skip prerequisite checks (use with caution) |
+
+
+---
+
+## Examples
+
+### Publish an npm package
+
+```bash
+# Verify first
+publish-package --dry-run
+
+# Publish
+publish-package
+
+# Output:
+#   [npm] Publishing my-package v0.4.0...
+#   OK: npm publish confirmed (my-package@0.4.0 on registry)
+```
+
+### Publish a Rust crate
+
+```bash
+export CARGO_REGISTRY_TOKEN=<token>
+publish-package --dry-run
+publish-package
+```
+
+### Missing token scenario
+
+```bash
+$ publish-package
+FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
+```
+
+
+---
+
+## Integration with release-branch
+
+When wired into `release-branch`, add a step after git push:
+
+```
+6a. Run publish-package to publish to package registries
+    → verify: publish-package --dry-run && publish-package
+```
+
+---
+
+## Reference block 1
+
+```bash
+# Check auth token exists
+if [ -z "${NPM_TOKEN:-}" ]; then
+  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
+    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+PACKAGE_NAME=$(node -p "require('./package.json').name")
+CURRENT_VER=$(node -p "require('./package.json').version")
+if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
+  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
+  exit 1
+fi
+
+# Check build artifacts are fresh
+if [ -d dist ] || [ -d lib ]; then
+  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
+  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
+  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
+    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
+    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
+      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
+    fi
+  fi
+fi
+
+# Check CHANGELOG is updated
+if [ -f CHANGELOG.md ]; then
+  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
+    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
+  fi
+fi
+```
+
+---
+
+## Reference block 2
+
+```bash
+# Check auth token exists
+if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
+  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
+    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
+  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
+  exit 1
+fi
+```
+
+---
+
+## Reference block 3
+
+```bash
+# Check auth token exists
+if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
+  if [ ! -f ~/.pypirc ]; then
+    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
+    exit 1
+  fi
+fi
+
+# Check for build artifacts
+if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
+  echo "WARNING: No .whl files found in dist/. Run: python -m build"
+fi
+```
+
+---
+
+## Reference block 4
+
+```bash
+# npm
+npm publish --access public
+
+# crates.io
+cargo publish
+
+# PyPI
+python -m twine upload dist/*  # or: poetry publish
+
+# Homebrew (opens PR, does not publish directly)
+brew bump-formula-pr --url=<tarball-url> <formula-name>
+```
+
+---
+
+## Reference block 5
+
+```bash
+# npm
+npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
+
+# crates.io
+cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
+
+# PyPI
+pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
+```
+
+---
+
+## Reference block 6
+
+```bash
+# Generic failure handler
+if [ $? -ne 0 ]; then
+  case "$REGISTRY" in
+    npm)
+      echo "FAIL: npm publish failed."
+      echo "  Common causes:"
+      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
+      echo "  - Version already published: bump version in package.json"
+      echo "  - Two-factor auth required: use --otp=<code> flag"
+      echo "  - Package scoped but not public: add --access public"
+      ;;
+    crates.io)
+      echo "FAIL: cargo publish failed."
+      echo "  Common causes:"
+      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
+      echo "  - Version already published: bump version in Cargo.toml"
+      echo "  - Local changes not committed: cargo publish requires clean working tree"
+      ;;
+    pypi)
+      echo "FAIL: PyPI publish failed."
+      echo "  Common causes:"
+      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
+      echo "  - Build artifacts missing: run python -m build first"
+      echo "  - Version conflict: version already exists on PyPI"
+      ;;
+  esac
+  exit 1
+fi
+```
+
+---
+
+## Reference block 7
+
+```bash
+# Example output
+$ publish-package --dry-run
+
+[DRY-RUN] Detected package type: npm
+[DRY-RUN] Package: my-package v0.4.0
+[DRY-RUN] Checking NPM_TOKEN... OK
+[DRY-RUN] Checking version 0.4.0 not already published... OK
+[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
+[DRY-RUN] Checking CHANGELOG... OK
+[DRY-RUN] Would run: npm publish --access public
+[DRY-RUN] Exiting without publishing.
+```
+
+---
+
+## Reference block 8
+
+```bash
+# npm dry-run
+npm publish --access public --dry-run
+
+# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
+cargo package --list 2>/dev/null
+
+# PyPI dry-run
+python -m twine upload --repository testpypi dist/*  # test.pypi.org
+```

package/publish-package/SKILL.md

@@ -33,225 +33,41 @@ If no manifest is found, prompt the user to specify the type or pass `--type <np
 Before attempting any publish, run all applicable checks:
 
 **npm (`package.json`):**
-```bash
-# Check auth token exists
-if [ -z "${NPM_TOKEN:-}" ]; then
-  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
-    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
-    exit 1
-  fi
-fi
-
-# Check version not already published
-PACKAGE_NAME=$(node -p "require('./package.json').name")
-CURRENT_VER=$(node -p "require('./package.json').version")
-if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
-  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
-  exit 1
-fi
-
-# Check build artifacts are fresh
-if [ -d dist ] || [ -d lib ]; then
-  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
-  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
-  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
-    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
-    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
-      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
-    fi
-  fi
-fi
-
-# Check CHANGELOG is updated
-if [ -f CHANGELOG.md ]; then
-  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
-    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
-  fi
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 **crates.io (`Cargo.toml`):**
-```bash
-# Check auth token exists
-if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
-  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
-    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
-    exit 1
-  fi
-fi
-
-# Check version not already published
-CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
-CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
-if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
-  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
-  exit 1
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 **PyPI (`setup.py` / `pyproject.toml`):**
-```bash
-# Check auth token exists
-if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
-  if [ ! -f ~/.pypirc ]; then
-    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
-    exit 1
-  fi
-fi
-
-# Check for build artifacts
-if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
-  echo "WARNING: No .whl files found in dist/. Run: python -m build"
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 3. Run publish
 
 After all prerequisite checks pass, run the registry-specific command:
 
-```bash
-# npm
-npm publish --access public
-
-# crates.io
-cargo publish
-
-# PyPI
-python -m twine upload dist/*  # or: poetry publish
-
-# Homebrew (opens PR, does not publish directly)
-brew bump-formula-pr --url=<tarball-url> <formula-name>
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 4. Verify publish success
 
 After publish, confirm the version appears on the registry:
 
-```bash
-# npm
-npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
-
-# crates.io
-cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
-
-# PyPI
-pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 5. Error handling
 
 On failure, surface actionable hints:
 
-```bash
-# Generic failure handler
-if [ $? -ne 0 ]; then
-  case "$REGISTRY" in
-    npm)
-      echo "FAIL: npm publish failed."
-      echo "  Common causes:"
-      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
-      echo "  - Version already published: bump version in package.json"
-      echo "  - Two-factor auth required: use --otp=<code> flag"
-      echo "  - Package scoped but not public: add --access public"
-      ;;
-    crates.io)
-      echo "FAIL: cargo publish failed."
-      echo "  Common causes:"
-      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
-      echo "  - Version already published: bump version in Cargo.toml"
-      echo "  - Local changes not committed: cargo publish requires clean working tree"
-      ;;
-    pypi)
-      echo "FAIL: PyPI publish failed."
-      echo "  Common causes:"
-      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
-      echo "  - Build artifacts missing: run python -m build first"
-      echo "  - Version conflict: version already exists on PyPI"
-      ;;
-  esac
-  exit 1
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 6. Dry-run mode (`--dry-run`)
 
 Run `--dry-run` to verify all prerequisites without actually publishing:
 
-```bash
-# Example output
-$ publish-package --dry-run
-
-[DRY-RUN] Detected package type: npm
-[DRY-RUN] Package: my-package v0.4.0
-[DRY-RUN] Checking NPM_TOKEN... OK
-[DRY-RUN] Checking version 0.4.0 not already published... OK
-[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
-[DRY-RUN] Checking CHANGELOG... OK
-[DRY-RUN] Would run: npm publish --access public
-[DRY-RUN] Exiting without publishing.
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 7. Dry-run mode per registry
 
-```bash
-# npm dry-run
-npm publish --access public --dry-run
-
-# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
-cargo package --list 2>/dev/null
-
-# PyPI dry-run
-python -m twine upload --repository testpypi dist/*  # test.pypi.org
-```
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `--dry-run` | Verify prerequisites and show publish command without executing |
-| `--registry <type>` | Force registry type (skip auto-detection) |
-| `--otp <code>` | One-time password for npm 2FA |
-| `--no-verify` | Skip prerequisite checks (use with caution) |
-
-## Examples
-
-### Publish an npm package
-
-```bash
-# Verify first
-publish-package --dry-run
-
-# Publish
-publish-package
-
-# Output:
-#   [npm] Publishing my-package v0.4.0...
-#   OK: npm publish confirmed (my-package@0.4.0 on registry)
-```
-
-### Publish a Rust crate
-
-```bash
-export CARGO_REGISTRY_TOKEN=<token>
-publish-package --dry-run
-publish-package
-```
-
-### Missing token scenario
-
-```bash
-$ publish-package
-FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
-```
-
-## Integration with release-branch
-
-When wired into `release-branch`, add a step after git push:
-
-```
-6a. Run publish-package to publish to package registries
-    → verify: publish-package --dry-run && publish-package
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ## Verify
 

package/release-branch/REFERENCE.md

@@ -1,5 +1,7 @@
 # Release Branch — Reference
 
+# Release Branch — Reference
+
 ## PR body template (team-pr mode)
 
 ```bash
@@ -53,3 +55,84 @@ After landing the branch, record delivery metrics for this story:
   cycle_minutes: 90
   bcp_per_hour: 2.0
 ```
+
+---
+
+## Solo-local fallback detail
+
+The fallback sequence (Path B above) handles the "remote has moved" case with `git pull --rebase`. Use when `scripts/land-branch.sh` is absent.
+
+**Acceptance:** When fallback runs, main is updated, feature branch is deleted locally, and output states `"used fallback merge (land-branch.sh not found)"`.
+
+## Handoff
+
+Gate: READY -> next: survey-context
+Writes: state.yaml handoff.next_skill = survey-context
+
+---
+
+## Reference block 1
+
+```bash
+# Fallback: manual squash-merge when land-branch.sh is absent
+FEATURE_BRANCH=<task-slug>
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
+
+# Ensure we're on the feature branch
+if [ "$(git branch --show-current)" != "$FEATURE_BRANCH" ]; then
+  git checkout "$FEATURE_BRANCH"
+fi
+
+# Checkout default branch and update
+git checkout "$DEFAULT_BRANCH"
+git pull --rebase origin "$DEFAULT_BRANCH" 2>/dev/null || git pull origin "$DEFAULT_BRANCH"
+
+# Squash-merge the feature branch
+git merge --no-ff "$FEATURE_BRANCH" -m "<conventional-commit-message>"
+
+# Push
+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/release-branch/SKILL.md

@@ -63,29 +63,7 @@ bash scripts/land-branch.sh <task-slug> "feat(scope): description"
 ```
 
 **Path B — `scripts/land-branch.sh` missing (fallback):**
-```bash
-# Fallback: manual squash-merge when land-branch.sh is absent
-FEATURE_BRANCH=<task-slug>
-DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
-
-# Ensure we're on the feature branch
-if [ "$(git branch --show-current)" != "$FEATURE_BRANCH" ]; then
-  git checkout "$FEATURE_BRANCH"
-fi
-
-# Checkout default branch and update
-git checkout "$DEFAULT_BRANCH"
-git pull --rebase origin "$DEFAULT_BRANCH" 2>/dev/null || git pull origin "$DEFAULT_BRANCH"
-
-# Squash-merge the feature branch
-git merge --no-ff "$FEATURE_BRANCH" -m "<conventional-commit-message>"
-
-# Push
-git push origin "$DEFAULT_BRANCH"
-
-# Clean up local feature branch
-git branch -d "$FEATURE_BRANCH"
-```
+See [REFERENCE.md](REFERENCE.md)
 
 **Report which path was taken.** Print exactly:
 - `"used land-branch.sh"` if Path A
@@ -117,41 +95,7 @@ mv specs/epics/eNN-slug specs/epics/archive/
 
 After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
 
-```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
-```
+See [REFERENCE.md](REFERENCE.md)
 
 - [ ] CI workflow passes after push
 - [ ] `release.ci_verified: true` documented in state.yaml
@@ -176,14 +120,3 @@ git checkout main && git status && pwd
 ```
 
 Report: "Branch released. Integrate mode: <solo-local|team-pr>. cwd: $(pwd) on $(git branch --show-current)."
-
-## Solo-local fallback detail
-
-The fallback sequence (Path B above) handles the "remote has moved" case with `git pull --rebase`. Use when `scripts/land-branch.sh` is absent.
-
-**Acceptance:** When fallback runs, main is updated, feature branch is deleted locally, and output states `"used fallback merge (land-branch.sh not found)"`.
-
-## Handoff
-
-Gate: READY -> next: survey-context
-Writes: state.yaml handoff.next_skill = survey-context

package/scripts/generate-reference-tables.sh

@@ -6,6 +6,7 @@ set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 TARGET="$REPO_ROOT/docs/references/model-profiles.md"
+mkdir -p "$(dirname "$TARGET")"
 
 cd "$REPO_ROOT"
 

package/scripts/sync-skills.sh

@@ -231,6 +231,9 @@ if [[ -f "$validate_script" ]] && command -v python3 &>/dev/null; then
 fi
 
 # Regenerate derived reference tables from live SKILL.md frontmatter
-bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
+# Only in dev context (with .git) — not during consumer npm install where docs/ is excluded
+if [[ -d "$REPO_ROOT/.git" ]]; then
+  bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
+fi
 
 exit 0