bigpowers 2.34.1 → 2.35.0

package/.pi/skills/publish-package/SKILL.md

@@ -34,6 +34,112 @@ 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`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**crates.io (`Cargo.toml`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**PyPI (`setup.py` / `pyproject.toml`):**
+See [REFERENCE.md](REFERENCE.md)
+
+### 3. Run publish
+
+After all prerequisite checks pass, run the registry-specific command:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 4. Verify publish success
+
+After publish, confirm the version appears on the registry:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 5. Error handling
+
+On failure, surface actionable hints:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 6. Dry-run mode (`--dry-run`)
+
+Run `--dry-run` to verify all prerequisites without actually publishing:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 7. Dry-run mode per registry
+
+See [REFERENCE.md](REFERENCE.md)
+
+## Verify
+
+→ verify: `test -f publish-package/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: publish-package" publish-package/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "npm\|crates.io\|pypi\|publish\|registry" publish-package/SKILL.md | awk '{if($1>=4) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "publish-package" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`
+
+---
+
+# 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
@@ -71,7 +177,10 @@ if [ -f CHANGELOG.md ]; then
 fi
 ```
 
-**crates.io (`Cargo.toml`):**
+---
+
+## Reference block 2
+
 ```bash
 # Check auth token exists
 if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
@@ -90,7 +199,10 @@ if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_
 fi
 ```
 
-**PyPI (`setup.py` / `pyproject.toml`):**
+---
+
+## Reference block 3
+
 ```bash
 # Check auth token exists
 if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
@@ -106,9 +218,9 @@ if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
 fi
 ```
 
-### 3. Run publish
+---
 
-After all prerequisite checks pass, run the registry-specific command:
+## Reference block 4
 
 ```bash
 # npm
@@ -124,9 +236,9 @@ python -m twine upload dist/*  # or: poetry publish
 brew bump-formula-pr --url=<tarball-url> <formula-name>
 ```
 
-### 4. Verify publish success
+---
 
-After publish, confirm the version appears on the registry:
+## Reference block 5
 
 ```bash
 # npm
@@ -139,9 +251,9 @@ cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER
 pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
 ```
 
-### 5. Error handling
+---
 
-On failure, surface actionable hints:
+## Reference block 6
 
 ```bash
 # Generic failure handler
@@ -174,9 +286,9 @@ if [ $? -ne 0 ]; then
 fi
 ```
 
-### 6. Dry-run mode (`--dry-run`)
+---
 
-Run `--dry-run` to verify all prerequisites without actually publishing:
+## Reference block 7
 
 ```bash
 # Example output
@@ -192,7 +304,9 @@ $ publish-package --dry-run
 [DRY-RUN] Exiting without publishing.
 ```
 
-### 7. Dry-run mode per registry
+---
+
+## Reference block 8
 
 ```bash
 # npm dry-run
@@ -204,59 +318,3 @@ 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
-```
-
-## Verify
-
-→ verify: `test -f publish-package/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
-→ verify: `grep -q "name: publish-package" publish-package/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
-→ verify: `grep -ci "npm\|crates.io\|pypi\|publish\|registry" publish-package/SKILL.md | awk '{if($1>=4) print "OK: semantics"; else print "FAIL: missing"}'`
-→ verify: `grep -q "publish-package" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

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

@@ -64,29 +64,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
@@ -118,41 +96,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
@@ -178,21 +122,12 @@ 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
-
 ---
 
 # Release Branch — Reference
 
+# Release Branch — Reference
+
 ## PR body template (team-pr mode)
 
 ```bash
@@ -246,3 +181,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
+```