bigpowers 2.34.1 → 2.35.0

package/deploy/REFERENCE.md

@@ -0,0 +1,82 @@
+# Deploy — Reference
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ARTIFACT_DIR` | `dist` | Build output directory |
+| `DEPLOY_URL` | *(required)* | Live URL for smoke test |
+| `DEPLOY_TIMEOUT` | `300` | Max wait for deploy completion (seconds) |
+| `DEPLOY_POLL_INTERVAL` | `30` | Polling interval (seconds) |
+| `RETRY_MAX` | `3` | Max deploy retry attempts |
+| `BUILD_COMMAND` | *(auto-detect)* | Override build command |
+
+
+---
+
+## Verification
+
+→ verify: `test -f deploy/SKILL.md && grep -q 'name: deploy' deploy/SKILL.md && echo OK`
+→ verify: `grep -qi 'build\|artifact\|deploy\|smoke' deploy/SKILL.md && echo OK`
+→ verify: `grep -ci 'package.json\|Cargo.toml\|Makefile\|manifest' deploy/SKILL.md | awk '{if($1>=1) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'timeout\|poll\|status\|retry\|backoff' deploy/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'curl.*DEPLOY_URL\|smoke\|health' deploy/SKILL.md && echo OK`
+
+---
+
+## Reference block 1
+
+```bash
+DEPLOY_TIMEOUT="${DEPLOY_TIMEOUT:-300}"   # seconds (default 5 minutes)
+DEPLOY_POLL_INTERVAL="${DEPLOY_POLL_INTERVAL:-30}"  # seconds
+
+start_time=$(date +%s)
+while true; do
+  elapsed=$(( $(date +%s) - start_time ))
+  if [ "$elapsed" -ge "$DEPLOY_TIMEOUT" ]; then
+    echo "FAIL: deploy status polling timed out after ${DEPLOY_TIMEOUT}s"
+    exit 1
+  fi
+  
+  status=$(get_deploy_status)  # platform-specific status check
+  if [ "$status" = "ready" ] || [ "$status" = "done" ]; then
+    echo "Deploy completed in ${elapsed}s"
+    break
+  fi
+  
+  sleep "$DEPLOY_POLL_INTERVAL"
+done
+```
+
+---
+
+## Reference block 2
+
+```bash
+RETRY_MAX="${RETRY_MAX:-3}"
+base_delay=2
+for attempt in $(seq 1 "$RETRY_MAX"); do
+  if deploy_command; then
+    break
+  fi
+  if [ "$attempt" -eq "$RETRY_MAX" ]; then
+    echo "FAIL: deploy failed after ${RETRY_MAX} attempts"
+    exit 1
+  fi
+  sleep $(( base_delay * 2 ** (attempt - 1) ))
+done
+```
+
+---
+
+## Reference block 3
+
+```bash
+DEPLOY_URL="${DEPLOY_URL:?DEPLOY_URL must be set}"
+if curl -sSf "$DEPLOY_URL" > /dev/null 2>&1; then
+  echo "OK: $DEPLOY_URL responds with HTTP 200"
+else
+  echo "FAIL: $DEPLOY_URL is not responding with HTTP 200"
+  exit 1
+fi
+```

package/deploy/SKILL.md

@@ -87,56 +87,15 @@ exit 1
 
 After invoking the deploy command, poll for completion:
 
-```bash
-DEPLOY_TIMEOUT="${DEPLOY_TIMEOUT:-300}"   # seconds (default 5 minutes)
-DEPLOY_POLL_INTERVAL="${DEPLOY_POLL_INTERVAL:-30}"  # seconds
-
-start_time=$(date +%s)
-while true; do
-  elapsed=$(( $(date +%s) - start_time ))
-  if [ "$elapsed" -ge "$DEPLOY_TIMEOUT" ]; then
-    echo "FAIL: deploy status polling timed out after ${DEPLOY_TIMEOUT}s"
-    exit 1
-  fi
-  
-  status=$(get_deploy_status)  # platform-specific status check
-  if [ "$status" = "ready" ] || [ "$status" = "done" ]; then
-    echo "Deploy completed in ${elapsed}s"
-    break
-  fi
-  
-  sleep "$DEPLOY_POLL_INTERVAL"
-done
-```
+See [REFERENCE.md](REFERENCE.md)
 
 Use exponential backoff for retries on transient failures:
 
-```bash
-RETRY_MAX="${RETRY_MAX:-3}"
-base_delay=2
-for attempt in $(seq 1 "$RETRY_MAX"); do
-  if deploy_command; then
-    break
-  fi
-  if [ "$attempt" -eq "$RETRY_MAX" ]; then
-    echo "FAIL: deploy failed after ${RETRY_MAX} attempts"
-    exit 1
-  fi
-  sleep $(( base_delay * 2 ** (attempt - 1) ))
-done
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 6. Baseline smoke test
 
-```bash
-DEPLOY_URL="${DEPLOY_URL:?DEPLOY_URL must be set}"
-if curl -sSf "$DEPLOY_URL" > /dev/null 2>&1; then
-  echo "OK: $DEPLOY_URL responds with HTTP 200"
-else
-  echo "FAIL: $DEPLOY_URL is not responding with HTTP 200"
-  exit 1
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 For comprehensive health-checking, chain to the `smoke-test` skill:
 
@@ -144,22 +103,3 @@ For comprehensive health-checking, chain to the `smoke-test` skill:
 # After deploy success
 bash scripts/run-smoke.sh "$DEPLOY_URL"
 ```
-
-## Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ARTIFACT_DIR` | `dist` | Build output directory |
-| `DEPLOY_URL` | *(required)* | Live URL for smoke test |
-| `DEPLOY_TIMEOUT` | `300` | Max wait for deploy completion (seconds) |
-| `DEPLOY_POLL_INTERVAL` | `30` | Polling interval (seconds) |
-| `RETRY_MAX` | `3` | Max deploy retry attempts |
-| `BUILD_COMMAND` | *(auto-detect)* | Override build command |
-
-## Verification
-
-→ verify: `test -f deploy/SKILL.md && grep -q 'name: deploy' deploy/SKILL.md && echo OK`
-→ verify: `grep -qi 'build\|artifact\|deploy\|smoke' deploy/SKILL.md && echo OK`
-→ verify: `grep -ci 'package.json\|Cargo.toml\|Makefile\|manifest' deploy/SKILL.md | awk '{if($1>=1) print "OK"; else print "FAIL"}'`
-→ verify: `grep -ci 'timeout\|poll\|status\|retry\|backoff' deploy/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
-→ verify: `grep -q 'curl.*DEPLOY_URL\|smoke\|health' deploy/SKILL.md && echo OK`

package/develop-tdd/SKILL.md

@@ -70,70 +70,15 @@ After all tests pass: extract duplication, deepen modules, apply SOLID principle
 
 After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
 
-### 6a. CI dry-run sub-step (when modifying workflows)
-
-If this cycle modified files in `.github/workflows/`, run a CI dry-run before pushing:
-
-```bash
-# 1. Check for workflow file changes
-CHANGED_WORKFLOWS=$(git diff --name-only HEAD | grep '\.github/workflows/' || true)
-if [ -n "$CHANGED_WORKFLOWS" ]; then
-  echo "==> CI dry-run: workflow files changed"
-  echo "    $CHANGED_WORKFLOWS"
-
-  # 2. Validate YAML syntax
-  if command -v yamllint &>/dev/null; then
-    for f in $CHANGED_WORKFLOWS; do
-      yamllint "$f" && echo "  OK: $f passes YAML lint" || echo "  WARN: $f has YAML issues"
-    done
-  else
-    # Fallback: Python YAML parse
-    for f in $CHANGED_WORKFLOWS; do
-      python3 -c "import yaml; yaml.safe_load(open('$f'))" 2>/dev/null && \
-        echo "  OK: $f YAML syntax valid" || \
-        echo "  FAIL: $f has YAML syntax errors"
-    done
-  fi
-
-  # 3. Run actionlint if available
-  if command -v actionlint &>/dev/null; then
-    for f in $CHANGED_WORKFLOWS; do
-      actionlint "$f" && echo "  OK: $f passes actionlint" || echo "  WARN: $f has actionlint issues"
-    done
-  fi
-
-  # 4. Check common pitfalls
-  for f in $CHANGED_WORKFLOWS; do
-    # Missing permissions block
-    if ! grep -q 'permissions:' "$f"; then
-      echo "  WARNING: $f missing permissions block — add one for security"
-    fi
-    # npm publish without NPM_TOKEN
-    if grep -q 'npm publish\|npx semantic-release' "$f" && ! grep -q 'NPM_TOKEN' "$f"; then
-      echo "  WARNING: $f has npm publish/semantic-release but no NPM_TOKEN in secrets"
-    fi
-    # Hardcoded Node versions
-    if grep -q 'node-version: [0-9]' "$f"; then
-      echo "  NOTE: $f has hardcoded Node version — consider node-version-file: .nvmrc"
-    fi
-  done
-
-  # 5. Suggest local dry-run
-  if command -v act &>/dev/null; then
-    echo "  SUGGESTION: Run 'act push --dry-run' to test workflows locally"
-  fi
-fi
-```
-
-Checklist:
-- [ ] YAML syntax validated for all changed workflow files
-- [ ] No missing permissions, secrets, or hardcoded versions flagged
-- [ ] Local dry-run suggested if `act` is available
-
 ### 7. Manual Verification Handover
 
 Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.
 
+
+### 6a. CI dry-run sub-step
+
+If this cycle modified files in `.github/workflows/`, run the CI dry-run procedure documented in [REFERENCE.md](REFERENCE.md#ci-dry-run).
+
 ## Checklist Per Cycle
 
 ```
@@ -149,26 +94,6 @@ Once all tests pass: locate the Verification Script in the active epic capsule,
 [ ] verify: command passes
 ```
 
-## --config mode
-
-For pure-config tasks (update package.json, edit YAML, tweak manifest) where there is no test infrastructure to write against. The RED state is "verify command fails"; GREEN is "verify command passes."
-
-**When to use:** task has a runnable `verify:` command and the deliverable is a config file change with no new behavior to unit-test. Invoke as `develop-tdd --config`.
-
-**Cycle:**
-
-```
-RED:    Run verify command → it fails (expected)
-GREEN:  Apply config change → verify passes
-COMMIT: commit: chore(<scope>): <change>
-```
-
-**Rules:**
-- Skips test-writing phase entirely — do NOT write a test file for config tasks.
-- `verify:` command is **required** and must be runnable (no placeholder).
-- Commit message follows Conventional Commits (`chore:` or `feat:` as appropriate).
-- Still runs full `verify-work` after all tasks complete.
-
 ## Handoff
 
 Gate: READY -> next: verify-work

package/migrate-spec/REFERENCE.md

@@ -1,3 +1,5 @@
+# Migrate Spec — Reference
+
 # migrate-spec Reference — spec-kit, BMAD, Learnings
 
 Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.
@@ -332,3 +334,269 @@ two_pass_spec:  # Optional: only if user activates two-pass spec writing gate
   technical_pass: pending
   approved_at: null
 ```
+
+---
+
+## Reference block 1
+
+```
+Detected: GSD
+Found:
+  ✓ .planning/ROADMAP.md
+  ✓ .planning/REQUIREMENTS.md  (12 REQ-XX items)
+  ✓ .planning/state.yaml
+  ✓ .planning/phases/01-auth/01-CONTEXT.md
+  ✗ .planning/METHODOLOGY.md  (not present)
+
+Skipping:
+  .planning/phases/01-auth/01-01-SUMMARY.md  (execution record; archived only)
+
+Proceed with migration? [yes / skip <artifact> / abort]
+```
+
+---
+
+## Reference block 2
+
+```yaml
+# CORRECT — first-class id: field
+in_scope:
+  - id: REQ-001
+    description: "User can register with email/password"
+    source: "REQUIREMENTS.md"
+
+# DEPRECATED — comment-only
+in_scope:
+  - "User can register with email/password"  # REQ-001
+```
+
+---
+
+## Reference block 3
+
+```yaml
+trace:
+  - id: FR-001
+    type: functional_requirement
+    description: "User can register with email/password"
+    epic: e02-auth-ui
+    story: e02s01
+    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"
+  - id: UJ-001
+    type: user_journey
+    description: "New user completes registration flow"
+    epic: e02-auth-ui
+    story: e02s01
+```
+
+---
+
+## Reference block 4
+
+```yaml
+active_flow: null
+active_epic_id: null
+active_story_id: null
+
+# ... other state fields ...
+
+handoff:
+  last_step_completed: "Migrated from <framework> on <date>"
+  open_decisions:
+    - "decision text here"
+  required_reading:
+    - specs/product/VISION_LATEST.yaml
+    - specs/product/SCOPE_LATEST.yaml
+    - specs/tech-architecture/TECH_STACK_LATEST.md
+    - specs/release-plan.yaml
+  next_skill: survey-context
+```
+
+---
+
+## Reference block 5
+
+```markdown
+# Migration Audit — <project-name> from <framework>
+
+**Date:** <ISO 8601 timestamp>
+**Status:** Pass / Fail with findings
+
+## Findings
+
+### High Priority
+- Artifact: specs/epics/e02-auth-ui/epic.yaml
+  Finding: No verify: commands in story tasks
+  Recommendation: Add `verify:` to each task before develop-tdd
+
+### Information
+- Count of TODO markers: 3 (normal for fresh migration)
+```
+
+---
+
+## Reference block 6
+
+```
+Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?
+
+[x] Cost of Delay (CD3)           — Priority & trade-off assessment
+[ ] STRIDE                        — Security threat modeling
+[ ] F.I.R.S.T                     — Test quality principles
+[ ] Bayesian Updating            — Probabilistic decision-making
+[ ] OWASP Top 10                 — Web security framework
+```
+
+---
+
+### Step 7 — Post-migration: Optional two-pass spec writing gate
+
+After Steps 1–6, offer the user an optional two-pass spec writing workflow (spec-kit learning):
+
+Prompt: "Use two-pass spec writing (user journeys first, then technical)? [yes / no]"
+
+If **yes**, initialize the gate in `specs/state.yaml`:
+
+```yaml
+two_pass_spec:
+  journey_pass: pending
+  technical_pass: pending
+  approved_at: null
+```
+
+The journey pass must be marked "complete" by the user (after stakeholder approval of user-journey specs) before the technical pass begins:
+
+```yaml
+two_pass_spec:
+  journey_pass: complete
+  approved_at: "2026-06-26T12:00:00Z"
+  technical_pass: pending
+```
+
+Inform the user: "Journey pass is pending. Run `elaborate-spec` for user journeys, get stakeholder approval, then update `two_pass_spec.journey_pass: complete` in state.yaml before proceeding to technical specs."
+
+If **no**, skip the two-pass gate. Proceed directly to plan-work.
+
+→ verify: `grep -q 'two_pass_spec:' specs/state.yaml && echo "two-pass gate initialized" || echo "two-pass gate not activated"`
+
+
+---
+
+### Step 8 — Post-migration: Optional methodology doc template
+
+After Steps 1–7, offer the user an optional analytical framework scaffold (GSD learning):
+
+Prompt: "Create a methodology doc? [yes / no]"
+
+If **yes**, present a checklist of analytical lenses:
+
+```
+Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?
+
+[x] Cost of Delay (CD3)           — Priority & trade-off assessment
+[ ] STRIDE                        — Security threat modeling
+[ ] F.I.R.S.T                     — Test quality principles
+[ ] Bayesian Updating            — Probabilistic decision-making
+[ ] OWASP Top 10                 — Web security framework
+```
+
+Copy the template from `migrate-spec/templates/METHODOLOGY_LATEST.md` to `specs/tech-architecture/METHODOLOGY_LATEST.md`.
+- Active lenses remain uncommented
+- Unselected lenses are left commented out
+- Populate `{{project_name}}` with the migrated project's name
+
+If **no**, skip. Add note to handoff: "Methodology doc: skipped — can be added later via `cp migrate-spec/templates/METHODOLOGY_LATEST.md specs/tech-architecture/`"
+
+→ verify: `test -f specs/tech-architecture/METHODOLOGY_LATEST.md && echo "methodology doc created" || echo "methodology doc skipped"`
+
+---
+
+
+---
+
+## Artifact Mapping Summary
+
+Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./REFERENCE.md) (spec-kit, BMAD, learnings).
+
+| Source | Target |
+|--------|--------|
+| GSD `ROADMAP.md` | `specs/release-plan.yaml + epic shards` |
+| GSD `REQUIREMENTS.md` | `specs/product/SCOPE_LATEST.yaml` |
+| GSD `CONTEXT.md` (phases) | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |
+| GSD `PLAN.md` | `specs/epics/eNN-slug/epic.yaml` (tasks with verify in `-tasks.yaml`) |
+| GSD `METHODOLOGY.md` | `specs/tech-architecture/tech-stack.md` |
+| spec-kit `spec.md` | `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/tech-stack.md` |
+| spec-kit `plan.md` | `specs/tech-architecture/tech-stack.md` + `specs/release-plan.yaml` + `specs/epics/` |
+| spec-kit `tasks.md` | `specs/epics/ (see slice-tasks)` |
+| BMAD `prd.md` | `specs/product/SCOPE_LATEST.yaml` |
+| BMAD `architecture.md` | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |
+| BMAD `epic-*.md` | `specs/release-plan.yaml + epic shards` |
+| BMAD `story-*.md` | `specs/epics/ (see slice-tasks)` |
+| BMAD `project-context.md` | `CLAUDE.md` (append project-specific section) |
+| BMAD `decision-log.md` | `specs/adr/` (one ADR per logged decision) |
+
+---
+
+
+---
+
+## Rules
+
+- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX are emitted as first-class `id:` fields in bigpowers YAML targets (e.g., `in_scope` entries). Never silently renumber. See Step 3 ID Tracking subsection for details.
+- **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
+- **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG.md`.
+- **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
+- **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.
+
+---
+
+### Step 5 — Surface learnings (optional)
+
+After migration, offer the user a brief analysis of what the source framework did that bigpowers doesn't have yet.
+
+Use the learnings table from [REFERENCE.md](./REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt.
+
+→ verify: `grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"`
+
+
+---
+
+### Step 6 — Adversarial review (optional)
+
+Before the user runs `plan-work`, offer an optional lightweight audit of the migrated artifacts. This catches common migration errors early — incomplete specs, missing verification commands, unresolved decisions.
+
+Prompt: "Run adversarial review of migrated artifacts? [yes / skip]"
+
+If yes, perform these checks:
+
+1. **Scan for incomplete markers** — Find TODO, FIXME, MISSING in specs/
+2. **Verify every epic has `verify:` commands** — Parse all `eNN-*/epic.yaml` files
+3. **Check state.yaml handoff** — Ensure `open_decisions` is documented (even if empty)
+
+Collect findings and write to `specs/archive/MIGRATION-AUDIT.md`:
+
+```markdown
+# Migration Audit — <project-name> from <framework>
+
+**Date:** <ISO 8601 timestamp>
+**Status:** Pass / Fail with findings
+
+
+---
+
+## Findings
+
+### High Priority
+- Artifact: specs/epics/e02-auth-ui/epic.yaml
+  Finding: No verify: commands in story tasks
+  Recommendation: Add `verify:` to each task before develop-tdd
+
+### Information
+- Count of TODO markers: 3 (normal for fresh migration)
+```
+
+If findings exist, the handoff block should note: "Adversarial review: N findings — see `specs/archive/MIGRATION-AUDIT.md`"
+
+If skip is chosen, add to handoff: "Adversarial review: skipped — review manually before plan-work"
+
+→ verify: `test -f specs/archive/MIGRATION-AUDIT.md && echo "audit completed" || echo "audit skipped or not performed"`