bigpowers 2.77.1 → 2.78.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.77.1",
-  "description": "79 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
+  "version": "2.78.0",
+  "description": "80 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/find-way.md

@@ -0,0 +1,190 @@
+---
+name: find-way
+description: "Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building."
+---
+
+# Find Way
+
+## Concept
+
+A large effort arrives — too big for one session, wrapped in fog. **Find-way** charts the way as a **shared map** on the repo's issue tracker, then works **decision tickets** — questions whose resolution is a decision, not build slices — one at a time until the route is clear.
+
+**Plan, don't do.** Each ticket resolves a decision. The map is done when the way is clear — nothing left to decide before someone executes.
+
+**Refer by name.** Every map and ticket is an issue with a title. Always use the name, never bare ids or numbers.
+
+## The Map
+
+A single issue labelled `wayfinder:map` — the canonical artifact. Child issues are its tickets.
+
+```markdown
+## Destination
+<what reaching the end looks like — one or two lines>
+
+## Notes
+<domain, skills to consult, standing preferences>
+
+## Decisions so far
+- [closed ticket title](link) — one-line gist
+
+## Not yet specified
+<in-scope fog you can't ticket yet>
+
+## Out of scope
+<work ruled beyond the destination>
+```
+
+## Ticket Types
+
+| Type | Label | Mode | Purpose |
+|------|-------|------|---------|
+| Research | `wayfinder:research` | AFK | Surface facts from docs/APIs |
+| Prototype | `wayfinder:prototype` | HITL | Cheap artifact to react to |
+| Grilling | `wayfinder:grilling` | HITL | One-question-at-a-time dialogue |
+| Task | `wayfinder:task` | Either | Manual work unblocking a decision |
+
+**HITL** = human in the loop. **AFK** = agent alone.
+
+## Two Modes
+
+### Chart the Map
+
+User invokes with a loose idea.
+
+1. **Name the destination** — grill to pin down what this map finds its way to
+2. **Map the frontier** — breadth-first: surface open decisions and first steps. If no fog emerges, the effort fits one session — skip the map
+3. **Create the map** issue (label `wayfinder:map`)
+4. **Create tickets** as child issues, then wire blocking edges in a second pass
+5. **Fire research subagents** for each `research` ticket in parallel
+6. Stop — charting resolves nothing
+
+### Work Through the Map
+
+User invokes with a map (URL/number). Ticket optional — without one, pick the next frontier ticket.
+
+1. Load the map (low-res view)
+2. **Choose & claim** — assign ticket before any work
+3. **Resolve** — zoom into related/closed tickets as needed
+4. **Record** — post resolution comment, close issue, append to Decisions-so-far
+5. **Graduate fog** — create new tickets from newly-specifiable fog, clear from Not-yet-specified
+6. **Rule out of scope** if resolution reveals something past the destination
+
+**Never resolve more than one ticket per session** (except research).
+
+## Fog of War
+
+Beyond live tickets lies the **fog** — decisions you can tell are coming but can't pin down yet. The **Not yet specified** section holds this dim view.
+
+**Fog or ticket?** Test: can you state the question precisely now?
+
+- **Ticket** when the question is sharp (even if blocked)
+- **Not yet specified** when you can't phrase it sharply yet
+
+## Out of Scope
+
+Work beyond the destination. Ruling something out is a scoping act, not a route step. Never graduates — returns only if destination is redrawn.
+
+If an existing ticket sits past the destination, close it and note in Out of scope.
+
+## Blocking & Frontier
+
+- **Blocking**: tracker's native dependency relationship
+- **Unblocked**: every blocker is closed
+- **Frontier**: open, unblocked, unclaimed children — the edge of the known
+
+## Detailed Reference
+
+See [REFERENCE.md](REFERENCE.md) for ticket anatomy, resolution protocol, and examples.
+
+---
+
+# Find-Way Reference
+
+## Ticket Anatomy
+
+Each ticket holds one question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+**Labels:** `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`
+
+**Claim:** Assign to yourself before any work — claim blocks concurrent sessions.
+
+**Blocking:** Use tracker's native dependency relationship so the frontier renders visually.
+
+**Resolution:** Post answer as a comment, close the issue, append to map's Decisions-so-far.
+
+## Resolution Protocol
+
+1. **Load the map** — read low-res view, not every ticket body
+2. **Choose & claim** — assign ticket to yourself (or take first frontier ticket if not named)
+3. **Resolve** — zoom into related/closed tickets as needed; invoke skills the Notes block names
+4. **Record** — post resolution comment with the answer, close the issue
+5. **Update map** — append to Decisions-so-far with one-line gist + link
+6. **Graduate fog** — create new tickets from newly-specifiable fog; clear from Not-yet-specified
+7. **Rule out of scope** if resolution reveals something past the destination
+
+## Ticket Types in Detail
+
+### Research (AFK)
+Surfacing facts from docs, APIs, or knowledge bases that a decision waits on.
+- Resolved by a `/research` subagent
+- Use when knowledge outside the working directory is required
+- **Label:** `wayfinder:research`
+
+### Prototype (HITL)
+Raise fidelity by building cheap, rough, concrete artifact to react to — outline, stub, UI/logic code.
+- Use the `/prototype` skill
+- Links the prototype as an asset
+- Use when "how should it look" or "how should it behave" is key
+- **Label:** `wayfinder:prototype`
+
+### Grilling (HITL)
+Conversation via `/grilling` and `/domain-modeling` skills, one question at a time.
+- The default case for clarifying decisions
+- **Label:** `wayfinder:grilling`
+
+### Task (HITL or AFK)
+Manual work unblocking a decision — signing up for service, provisioning access, moving data.
+- This is the **only** type that does rather than decides
+- Earns its place by unblocking a decision, not by delivering the destination
+- Agent drives AFK tasks alone; HITL tasks get precise checklist
+- **Label:** `wayfinder:task`
+
+## Fog-to-Ticket Graduation
+
+When resolving a ticket clears fog, graduate the newly-specifiable bits into fresh tickets:
+
+1. **Identify the fog** in Not-yet-specified that the resolution illuminates
+2. **Create new tickets** with crisp question statements
+3. **Wire blocking edges** if the new tickets depend on each other or existing ones
+4. **Clear from fog** — remove the graduated patch from Not-yet-specified so it lives only as its ticket
+
+## Out-of-Scope Close Protocol
+
+If a ticket turns out to sit past the destination:
+
+1. **Close the ticket** — mark it resolved or won't-fix
+2. **Add one line to Out of scope** — gist + why it's out of scope, linking the closed ticket
+3. **Never append to Decisions so far** — scope boundaries aren't steps on the route
+
+## Map State Transitions
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| **Open, unblocked, unclaimed** | Frontier — ready to take | Claim and resolve |
+| **Open, blocked** | Waiting on something | Wait for blockers to close |
+| **Open, claimed** | Concurrent session working | Skip for now |
+| **Closed** | Decided — lives in Decisions so far | Reference, don't re-open |
+
+## Concurrency
+
+Users may run unblocked tickets in parallel, so expect the tracker to be edited concurrently. Always:
+
+- Refresh the map before picking a ticket
+- Claim immediately before starting work
+- Never assume state hasn't changed since last read

package/.pi/prompts/gate-trace.md

@@ -69,7 +69,9 @@ gate_trace:
 ## Integration Points
 
 - **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
-- **sync-skills.yml** — CI gate (FAIL blocks pipeline).
+- **sync-skills.yml** — runs `trace-stories.sh --strict` as its "Traceability gate" step (FAIL
+  blocks pipeline), which shares this skill's coverage data (`traceability-matrix.json`) but
+  does not invoke a gate-trace PASS/CONCERNS/FAIL/WAIVED verdict directly.
 - **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
 
 ## References

package/.pi/skills/find-way/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: find-way
+model: sonnet
+description: "Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building."
+---
+
+# Find Way
+
+## Concept
+
+A large effort arrives — too big for one session, wrapped in fog. **Find-way** charts the way as a **shared map** on the repo's issue tracker, then works **decision tickets** — questions whose resolution is a decision, not build slices — one at a time until the route is clear.
+
+**Plan, don't do.** Each ticket resolves a decision. The map is done when the way is clear — nothing left to decide before someone executes.
+
+**Refer by name.** Every map and ticket is an issue with a title. Always use the name, never bare ids or numbers.
+
+## The Map
+
+A single issue labelled `wayfinder:map` — the canonical artifact. Child issues are its tickets.
+
+```markdown
+## Destination
+<what reaching the end looks like — one or two lines>
+
+## Notes
+<domain, skills to consult, standing preferences>
+
+## Decisions so far
+- [closed ticket title](link) — one-line gist
+
+## Not yet specified
+<in-scope fog you can't ticket yet>
+
+## Out of scope
+<work ruled beyond the destination>
+```
+
+## Ticket Types
+
+| Type | Label | Mode | Purpose |
+|------|-------|------|---------|
+| Research | `wayfinder:research` | AFK | Surface facts from docs/APIs |
+| Prototype | `wayfinder:prototype` | HITL | Cheap artifact to react to |
+| Grilling | `wayfinder:grilling` | HITL | One-question-at-a-time dialogue |
+| Task | `wayfinder:task` | Either | Manual work unblocking a decision |
+
+**HITL** = human in the loop. **AFK** = agent alone.
+
+## Two Modes
+
+### Chart the Map
+
+User invokes with a loose idea.
+
+1. **Name the destination** — grill to pin down what this map finds its way to
+2. **Map the frontier** — breadth-first: surface open decisions and first steps. If no fog emerges, the effort fits one session — skip the map
+3. **Create the map** issue (label `wayfinder:map`)
+4. **Create tickets** as child issues, then wire blocking edges in a second pass
+5. **Fire research subagents** for each `research` ticket in parallel
+6. Stop — charting resolves nothing
+
+### Work Through the Map
+
+User invokes with a map (URL/number). Ticket optional — without one, pick the next frontier ticket.
+
+1. Load the map (low-res view)
+2. **Choose & claim** — assign ticket before any work
+3. **Resolve** — zoom into related/closed tickets as needed
+4. **Record** — post resolution comment, close issue, append to Decisions-so-far
+5. **Graduate fog** — create new tickets from newly-specifiable fog, clear from Not-yet-specified
+6. **Rule out of scope** if resolution reveals something past the destination
+
+**Never resolve more than one ticket per session** (except research).
+
+## Fog of War
+
+Beyond live tickets lies the **fog** — decisions you can tell are coming but can't pin down yet. The **Not yet specified** section holds this dim view.
+
+**Fog or ticket?** Test: can you state the question precisely now?
+
+- **Ticket** when the question is sharp (even if blocked)
+- **Not yet specified** when you can't phrase it sharply yet
+
+## Out of Scope
+
+Work beyond the destination. Ruling something out is a scoping act, not a route step. Never graduates — returns only if destination is redrawn.
+
+If an existing ticket sits past the destination, close it and note in Out of scope.
+
+## Blocking & Frontier
+
+- **Blocking**: tracker's native dependency relationship
+- **Unblocked**: every blocker is closed
+- **Frontier**: open, unblocked, unclaimed children — the edge of the known
+
+## Detailed Reference
+
+See [REFERENCE.md](../../../skills/find-way/REFERENCE.md) for ticket anatomy, resolution protocol, and examples.
+
+---
+
+# Find-Way Reference
+
+## Ticket Anatomy
+
+Each ticket holds one question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+**Labels:** `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`
+
+**Claim:** Assign to yourself before any work — claim blocks concurrent sessions.
+
+**Blocking:** Use tracker's native dependency relationship so the frontier renders visually.
+
+**Resolution:** Post answer as a comment, close the issue, append to map's Decisions-so-far.
+
+## Resolution Protocol
+
+1. **Load the map** — read low-res view, not every ticket body
+2. **Choose & claim** — assign ticket to yourself (or take first frontier ticket if not named)
+3. **Resolve** — zoom into related/closed tickets as needed; invoke skills the Notes block names
+4. **Record** — post resolution comment with the answer, close the issue
+5. **Update map** — append to Decisions-so-far with one-line gist + link
+6. **Graduate fog** — create new tickets from newly-specifiable fog; clear from Not-yet-specified
+7. **Rule out of scope** if resolution reveals something past the destination
+
+## Ticket Types in Detail
+
+### Research (AFK)
+Surfacing facts from docs, APIs, or knowledge bases that a decision waits on.
+- Resolved by a `/research` subagent
+- Use when knowledge outside the working directory is required
+- **Label:** `wayfinder:research`
+
+### Prototype (HITL)
+Raise fidelity by building cheap, rough, concrete artifact to react to — outline, stub, UI/logic code.
+- Use the `/prototype` skill
+- Links the prototype as an asset
+- Use when "how should it look" or "how should it behave" is key
+- **Label:** `wayfinder:prototype`
+
+### Grilling (HITL)
+Conversation via `/grilling` and `/domain-modeling` skills, one question at a time.
+- The default case for clarifying decisions
+- **Label:** `wayfinder:grilling`
+
+### Task (HITL or AFK)
+Manual work unblocking a decision — signing up for service, provisioning access, moving data.
+- This is the **only** type that does rather than decides
+- Earns its place by unblocking a decision, not by delivering the destination
+- Agent drives AFK tasks alone; HITL tasks get precise checklist
+- **Label:** `wayfinder:task`
+
+## Fog-to-Ticket Graduation
+
+When resolving a ticket clears fog, graduate the newly-specifiable bits into fresh tickets:
+
+1. **Identify the fog** in Not-yet-specified that the resolution illuminates
+2. **Create new tickets** with crisp question statements
+3. **Wire blocking edges** if the new tickets depend on each other or existing ones
+4. **Clear from fog** — remove the graduated patch from Not-yet-specified so it lives only as its ticket
+
+## Out-of-Scope Close Protocol
+
+If a ticket turns out to sit past the destination:
+
+1. **Close the ticket** — mark it resolved or won't-fix
+2. **Add one line to Out of scope** — gist + why it's out of scope, linking the closed ticket
+3. **Never append to Decisions so far** — scope boundaries aren't steps on the route
+
+## Map State Transitions
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| **Open, unblocked, unclaimed** | Frontier — ready to take | Claim and resolve |
+| **Open, blocked** | Waiting on something | Wait for blockers to close |
+| **Open, claimed** | Concurrent session working | Skip for now |
+| **Closed** | Decided — lives in Decisions so far | Reference, don't re-open |
+
+## Concurrency
+
+Users may run unblocked tickets in parallel, so expect the tracker to be edited concurrently. Always:
+
+- Refresh the map before picking a ticket
+- Claim immediately before starting work
+- Never assume state hasn't changed since last read

package/.pi/skills/gate-trace/SKILL.md

@@ -70,7 +70,9 @@ gate_trace:
 ## Integration Points
 
 - **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
-- **sync-skills.yml** — CI gate (FAIL blocks pipeline).
+- **sync-skills.yml** — runs `trace-stories.sh --strict` as its "Traceability gate" step (FAIL
+  blocks pipeline), which shares this skill's coverage data (`traceability-matrix.json`) but
+  does not invoke a gate-trace PASS/CONCERNS/FAIL/WAIVED verdict directly.
 - **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
 
 ## References

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+# [2.78.0](https://github.com/danielvm-git/bigpowers/compare/v2.77.2...v2.78.0) (2026-07-23)
+
+
+### Bug Fixes
+
+* **ci:** make G-11 venv-ignore check independent of .venv's on-disk existence ([91f550d](https://github.com/danielvm-git/bigpowers/commit/91f550d79e408e5734820fb896e8c942fabbf41d))
+* **scripts:** defer type-hint evaluation in blind-spots.py for Python 3.9 ([6356b87](https://github.com/danielvm-git/bigpowers/commit/6356b87167d59422ed75eea0e933229a13b78c12))
+* **scripts:** repair completeness-critic's story-tag check ([5e336ea](https://github.com/danielvm-git/bigpowers/commit/5e336eadc260cb6752cc260f58946b1eddf2c1ee))
+* **scripts:** stop sync-status-from-epics.sh corrupting status on multi-line epic entries ([e23a3be](https://github.com/danielvm-git/bigpowers/commit/e23a3be1a1338ebb2f4393801fb3c74fbdae49ca))
+* **scripts:** unblock compliance gate and repair silently-passing capsule validator ([608d76a](https://github.com/danielvm-git/bigpowers/commit/608d76a428dc3d1d9015236577905a446d8155b8))
+* **skills:** add missing model: frontmatter to find-way, resolving skill-count divergence ([ddb7655](https://github.com/danielvm-git/bigpowers/commit/ddb76556e56c269fca6380e0b94d7d53d90c1ccf))
+
+
+### Features
+
+* **e53:** kick off establish-migration-baseline epic ([e74aeca](https://github.com/danielvm-git/bigpowers/commit/e74aecad771284841a59f226fd6c2eb827922553))
+* **planning:** elaborate e55-e59 migration epics into scoped planning-context ([25fb6ff](https://github.com/danielvm-git/bigpowers/commit/25fb6ff5e5cbb1d83acc0341be679666fd57adbd))
+* **release-plan:** sequence e54-e59, the remaining bigspec migration epics ([b6af03d](https://github.com/danielvm-git/bigpowers/commit/b6af03dbc7d19f9ac56b0abf2fa9997c83bacddc))
+* **skills:** add find-way skill for large effort planning ([6b7d27e](https://github.com/danielvm-git/bigpowers/commit/6b7d27e9d007b45b5dba4db688cfd3b135ca72d5))
+* **skills:** add find-way skill with complete reference documentation ([7aa9e0d](https://github.com/danielvm-git/bigpowers/commit/7aa9e0d769aca621071e2a719a0dc12db5a9c28f))
+
+## [2.77.2](https://github.com/danielvm-git/bigpowers/compare/v2.77.1...v2.77.2) (2026-07-19)
+
+
+### Bug Fixes
+
+* **scripts:** fall back to simple_yaml when PyYAML is absent during setup ([#81](https://github.com/danielvm-git/bigpowers/issues/81)) ([2608c64](https://github.com/danielvm-git/bigpowers/commit/2608c645e1143f1bbf96c3174341b107c672ae8e))
+
 ## [2.77.1](https://github.com/danielvm-git/bigpowers/compare/v2.77.0...v2.77.1) (2026-07-19)
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 ![npm version](https://img.shields.io/npm/v/bigpowers.svg)
-![Skills](https://img.shields.io/badge/skills-79-brightgreen.svg)
+![Skills](https://img.shields.io/badge/skills-80-brightgreen.svg)
 
 **Agent skills synthesizing 17 years of software engineering discipline — from Clean Code to AI-native architecture — into a single, prescriptive methodology for solo developers.**
 

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Skills:** 79
+**Skills:** 80
 
 ---
 

package/package.json

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

package/scripts/golden-g11-gitignore-venv.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# story: e53s01
 # golden-g11-gitignore-venv.sh — Python venv gitignore gate (G-11)
 #
 # Prevents recurrence of BUG-2026-07-03-venv-not-gitignored: a root .venv/
@@ -38,12 +39,25 @@ for pattern in "${required_patterns[@]}"; do
   fi
 done
 
+# git check-ignore on a directory-only pattern (.venv/) only matches when the
+# path is confirmed to be a directory — a nonexistent .venv (e.g. a fresh
+# kickoff-branch worktree, before setup-environment runs) reports as "not
+# ignored" even when the pattern is correct. Create it if absent so the check
+# is independent of prior local setup; remove it again only if we created it.
+CREATED_VENV=0
+if [ ! -e .venv ]; then
+  mkdir .venv
+  CREATED_VENV=1
+fi
+
 if git check-ignore -q .venv 2>/dev/null; then
   g11_pass "git check-ignore .venv"
 else
   g11_fail "git check-ignore .venv (path not ignored)"
 fi
 
+[ "$CREATED_VENV" -eq 1 ] && rmdir .venv 2>/dev/null || true
+
 echo ""
 echo "G-11 summary: $PASS passed, $FAIL failed"
 if [[ "$FAIL" -gt 0 ]]; then

package/scripts/lib/blind-spots.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# story: e53s01
 """story: e38s04 — TEA-inspired heuristic blind-spot detector (Python engine).
 
 Reads execution-status.yaml + traceability-matrix.json, runs 7 structural
@@ -9,6 +10,8 @@ Usage: called by scripts/check-blind-spots.sh with positional args:
       <exec_status_yaml> <matrix_json> <verifications_dir> <epics_dir>
 """
 
+from __future__ import annotations
+
 import json, os, re, sys
 from pathlib import Path
 from datetime import datetime, timezone

package/scripts/lib/completeness-critic.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# story: e45s05
+# story: e45s05 e53s01
 # Adversarial gap-finding completeness critic — post gate-trace.
 # Classifications: BLOCKER | WARNING | FILLED
 set -euo pipefail
@@ -28,8 +28,18 @@ classify() {
   || classify BLOCKER "Missing specs/blind-spots.json — run check-blind-spots.sh"
 
 if [[ -f specs/traceability-matrix.json ]]; then
-  UNDONE="$(jq '[.stories[]? | select(.status != "done" and (.code_tags // 0) == 0)] | length' specs/traceability-matrix.json 2>/dev/null || echo 0)"
-  (( UNDONE > 0 )) && classify BLOCKER "$UNDONE active story(ies) with zero code tags"
+  # verify-work runs per-story (build-epic builds one story at a time), so this
+  # check must scope to the story currently being verified — not its
+  # not-yet-built siblings (which have no code tags by definition until their
+  # own turn) and not unrelated epics (which may be plan-worked-to-build-ready
+  # but not yet kicked off).
+  ACTIVE_STORY="$(grep '^active_story:' specs/state.yaml 2>/dev/null | awk '{print $2}')"
+  if [[ -n "$ACTIVE_STORY" ]]; then
+    UNDONE="$(jq --arg s "$ACTIVE_STORY" \
+      '[.stories[]? | select(.id == $s and .status != "done" and ((.links // []) | map(select(.method == "explicit_tag")) | length) == 0)] | length' \
+      specs/traceability-matrix.json 2>/dev/null || echo 0)"
+    (( UNDONE > 0 )) && classify BLOCKER "active story $ACTIVE_STORY has zero explicit story-tag links"
+  fi
   COVERAGE="$(jq -r '.summary.coverage_percent // .coverage_percent // empty' specs/traceability-matrix.json 2>/dev/null)"
   if [[ -n "$COVERAGE" && "$COVERAGE" != "null" ]]; then
     awk -v c="$COVERAGE" 'BEGIN{if(c+0 < 60) exit 1}' || classify WARNING "Trace coverage ${COVERAGE}% below 60% target"

package/scripts/lib/plan-consistency-check.sh

@@ -25,13 +25,21 @@ report() {
   esac
 }
 
+# bash-3.2-portable membership test (no associative arrays — macOS ships bash 3.2)
+in_array() {
+  local needle="$1"; shift
+  local x
+  for x in "$@"; do [[ "$x" == "$needle" ]] && return 0; done
+  return 1
+}
+
 [[ -f "$EPIC_YAML" ]] || report CRITICAL "Missing epic.yaml in $CAPSULE"
 
 # Story IDs declared in epic.yaml
-declare -A EPIC_STORIES=()
+EPIC_STORIES=()
 if [[ -f "$EPIC_YAML" ]]; then
   while IFS= read -r sid; do
-    [[ -n "$sid" ]] && EPIC_STORIES["$sid"]=1
+    [[ -n "$sid" ]] && EPIC_STORIES+=("$sid")
   done < <(grep -E '^[[:space:]]*- id: e[0-9]+s[0-9]+' "$EPIC_YAML" | awk '{print $3}')
 fi
 
@@ -43,32 +51,35 @@ shopt -u nullglob
 (( ${#SPECS[@]} > 0 )) || report CRITICAL "No story spec .md files in capsule (run slice-tasks first)"
 (( ${#TASKS[@]} > 0 )) || report CRITICAL "No *-tasks.yaml files in capsule (run plan-work first)"
 
-declare -A SPEC_IDS=()
-for spec in "${SPECS[@]}"; do
+SPEC_IDS=()
+for spec in "${SPECS[@]+"${SPECS[@]}"}"; do
   base="$(basename "$spec" .md)"
   sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)"
   [[ -n "$sid" ]] || continue
-  SPEC_IDS["$sid"]=1
-  [[ -n "${EPIC_STORIES[$sid]+x}" ]] || report HIGH "Story $sid in spec file but missing from epic.yaml manifest"
-  grep -qE '^## (17\.|Acceptance|Verification Script)' "$spec" \
+  SPEC_IDS+=("$sid")
+  in_array "$sid" "${EPIC_STORIES[@]+"${EPIC_STORIES[@]}"}" \
+    || report HIGH "Story $sid in spec file but missing from epic.yaml manifest"
+  grep -qE '^#{2,3} (17\.|Acceptance|Verification Script)' "$spec" \
     || report HIGH "Story $sid spec missing §17 acceptance criteria or Verification Script"
   grep -qiE 'ambiguous|TBD|TODO|FIXME' "$spec" \
     && report MED "Story $sid spec contains ambiguous/TBD markers"
 done
 
-for tasks in "${TASKS[@]}"; do
+for tasks in "${TASKS[@]+"${TASKS[@]}"}"; do
   base="$(basename "$tasks" -tasks.yaml)"
   sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)"
   [[ -n "$sid" ]] || continue
-  [[ -n "${SPEC_IDS[$sid]+x}" ]] || report CRITICAL "tasks.yaml for $sid without matching story spec .md"
+  in_array "$sid" "${SPEC_IDS[@]+"${SPEC_IDS[@]}"}" \
+    || report CRITICAL "tasks.yaml for $sid without matching story spec .md"
   grep -qE '^[[:space:]]*verify:' "$tasks" \
     || report CRITICAL "Story $sid tasks.yaml missing runnable verify: commands"
   grep -qE '^status:[[:space:]]*(failing|todo|passing)' "$tasks" \
     || report MED "Story $sid tasks.yaml should use status: failing|passing ledger (e45s06)"
 done
 
-for sid in "${!EPIC_STORIES[@]}"; do
-  [[ -n "${SPEC_IDS[$sid]+x}" ]] || report HIGH "epic.yaml lists $sid but no story spec .md exists"
+for sid in "${EPIC_STORIES[@]+"${EPIC_STORIES[@]}"}"; do
+  in_array "$sid" "${SPEC_IDS[@]+"${SPEC_IDS[@]}"}" \
+    || report HIGH "epic.yaml lists $sid but no story spec .md exists"
 done
 
 echo "---"

package/scripts/lib/simple_yaml.py

@@ -7,20 +7,30 @@ def parse_simple_yaml(text: str) -> dict:
     root: dict = {}
     # Each stack entry: (indent, container, parent_dict, key_in_parent)
     stack: list = [(0, root, None, None)]
-    skip_until_indent = None  # skip block scalar continuation lines (| and >)
+    skip_until_indent = None  # indent of an active block scalar's key line
+    block: dict = {}  # active block scalar: {'lines': [...], 'style': str, 'assign': fn}
+
+    def flush_block():
+        if block:
+            block['assign'](_fold_block(block['lines'], block['style']))
+            block.clear()
+
     for i, raw in enumerate(text.splitlines()):
         stripped = raw.strip()
-        if not stripped or stripped.startswith("#"):
-            # Reset block-scalar skip on blank lines
-            continue
         indent = len(raw) - len(raw.lstrip())
-        
-        # Skip block scalar continuation (| and > in YAML)
+
+        # Inside a block scalar: capture continuation lines verbatim. Blank and
+        # '#'-prefixed lines are literal content here, not comments.
         if skip_until_indent is not None:
-            if indent > skip_until_indent:
+            if not stripped or indent > skip_until_indent:
+                if block:
+                    block['lines'].append(raw)
                 continue
-            else:
-                skip_until_indent = None
+            flush_block()
+            skip_until_indent = None
+
+        if not stripped or stripped.startswith("#"):
+            continue
         
         # Pop stack until we're at the right nesting level
         # Don't pop list containers at same indent — sibling items stay in same list
@@ -68,8 +78,11 @@ def parse_simple_yaml(text: str) -> dict:
                 v = v.strip()
                 # Detect block scalars in list items too
                 if v in ("|", ">", "|-", ">-", "|+", ">+"):
-                    item = {k: v}
+                    item = {k: None}
                     container.append(item)
+                    block.clear()
+                    block.update(lines=[], style=v,
+                                 assign=lambda s, _i=item, _k=k: _i.__setitem__(_k, s))
                     skip_until_indent = indent
                     continue
                 item = {k: _yaml_scalar(v) if v else None}
@@ -87,12 +100,18 @@ def parse_simple_yaml(text: str) -> dict:
         key = key.strip()
         val = val.strip()
         
-        # Detect block scalars (|, >, |- etc.)
+        # Detect block scalars (|, >, |- etc.) and capture their folded content.
         if val in ("|", ">", "|-", ">-", "|+", ">+"):
+            tgt = None
             if isinstance(container, list) and container:
-                container[-1][key] = val  # store the marker
+                tgt = container[-1]
             elif isinstance(container, dict):
-                container[key] = val
+                tgt = container
+            if tgt is not None:
+                tgt[key] = None
+                block.clear()
+                block.update(lines=[], style=val,
+                             assign=lambda s, _t=tgt, _k=key: _t.__setitem__(_k, s))
             skip_until_indent = indent
             continue
         
@@ -111,11 +130,43 @@ def parse_simple_yaml(text: str) -> dict:
                 stack.append((indent, nxt, container, key))
             else:
                 container[key] = _yaml_scalar(val)
+    flush_block()
     return root
 
 
+def _fold_block(raw_lines, style):
+    """Fold a YAML block scalar (| literal / > folded) to match PyYAML."""
+    # Strip the common leading indentation of the block's content lines.
+    indents = [len(l) - len(l.lstrip()) for l in raw_lines if l.strip()]
+    ci = min(indents) if indents else 0
+    lines = [l[ci:] if len(l) >= ci else l.strip() for l in raw_lines]
+    if style[0] == "|":  # literal: keep line breaks
+        text = "\n".join(lines)
+    else:  # folded: single break -> space, blank line -> newline
+        parts, prev_blank = [], True
+        for l in lines:
+            if l == "":
+                parts.append("\n")
+                prev_blank = True
+            else:
+                if parts and not prev_blank:
+                    parts.append(" ")
+                parts.append(l)
+                prev_blank = False
+        text = "".join(parts)
+    text = text.rstrip("\n")
+    # Chomping indicator: '-' strip, default clip (single trailing newline).
+    return text if style.endswith("-") else text + "\n"
+
+
 def _yaml_scalar(val: str):
     """Convert a YAML scalar string to Python type."""
+    stripped = val.strip()
+    # Double-quoted scalar: unescape YAML escapes (\" and \\) like PyYAML, and
+    # keep it a string (no bool/int coercion). Keeps the PyYAML-free fallback
+    # byte-identical to PyYAML for quoted descriptions.
+    if len(stripped) >= 2 and stripped[0] == '"' and stripped[-1] == '"':
+        return stripped[1:-1].replace('\\"', '"').replace("\\\\", "\\")
     val = val.strip('"').strip("'")
     if val in ("true", "false"):
         return val == "true"

package/scripts/lib/srp-engine.py

@@ -1,19 +1,30 @@
 #!/usr/bin/env python3
 # story: e48s15
+# story: BUG-2026-07-18-setup-pyyaml-missing
 import os
 import sys
 import json
 import glob
 import subprocess
-import yaml
 
-# Ensure scripts/lib is on the path so link_utils resolves regardless of cwd.
+# Ensure scripts/lib is on the path so sibling modules (link_utils, and the
+# simple_yaml fallback below) resolve regardless of cwd.
 _LIB_DIR = os.path.dirname(os.path.abspath(__file__))
 if _LIB_DIR not in sys.path:
     sys.path.insert(0, _LIB_DIR)
 
 from link_utils import LINK_RE, EXTERNAL_RE, strip_code_spans  # noqa: E402
 
+# End-user setup (bigpowers setup) may run on a python3 without PyYAML.
+# Prefer PyYAML for exact parsing; fall back to the dependency-free
+# simple_yaml.py (story e38s01) so setup never hard-crashes.
+try:
+    import yaml
+    _load_yaml = yaml.safe_load
+except ModuleNotFoundError:
+    from simple_yaml import parse_simple_yaml
+    _load_yaml = parse_simple_yaml
+
 def rewrite_links_for_pi(body, name):
     """Repoint relative links so they resolve from .pi/skills/<name>/.
 
@@ -114,7 +125,7 @@ def parse_skill(skill_md_path):
     skill_body = '---'.join(parts[2:])
 
     try:
-        frontmatter = yaml.safe_load(frontmatter_raw)
+        frontmatter = _load_yaml(frontmatter_raw)
     except Exception as e:
         print(f"Error parsing YAML frontmatter in {skill_md_path}: {e}", file=sys.stderr)
         sys.exit(1)
@@ -160,7 +171,7 @@ def get_active_adapters(repo_root):
         return ["cursor", "gemini", "pi"]
     try:
         with open(targets_file, 'r', encoding='utf-8') as f:
-            data = yaml.safe_load(f)
+            data = _load_yaml(f.read())
         adapters = []
         for target in data.get('targets', []):
             if target.get('skill') is not None:

package/scripts/sync-skills.sh

@@ -74,7 +74,7 @@ if [[ -f "$TARGETS_FILE" ]] && command -v yq >/dev/null 2>&1; then
     [[ -n "$adapter" && "$adapter" != "null" ]] && SKILL_ADAPTERS+=("$adapter")
   done < <(yq -r '.targets[] | select(.skill != null) | .skill.adapter' "$TARGETS_FILE" | sort -u)
 else
-  echo "sync-skills: WARN — targets.yaml missing; using legacy render list" >&2
+  echo "sync-skills: WARN — yq unavailable or targets.yaml missing; using legacy render list (cursor gemini pi)" >&2
   SKILL_ADAPTERS=(cursor gemini pi)
 fi
 

package/scripts/sync-status-from-epics.sh

@@ -46,8 +46,9 @@ keys: dict[str, str] = {}
 existing_path = epics_dir.parent / "execution-status.yaml"
 if existing_path.exists():
     existing = existing_path.read_text(encoding="utf-8")
-    for m in re.finditer(r"^  ([a-z0-9._-]+):\s*(\S+)", existing, re.M):
-        keys[m.group(1)] = m.group(2)
+    for m in re.finditer(r"^  ([a-z0-9._-]+):[ \t]*(\S+)?[ \t]*$", existing, re.M):
+        if m.group(2):
+            keys[m.group(1)] = m.group(2)
 
 # --- Parse release-plan.yaml for wsjf/tier per epic ---
 rp_epics: dict[str, dict[str, object]] = {}

package/scripts/test-setup-no-pyyaml.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# test-setup-no-pyyaml.sh — recurrence guard for BUG-2026-07-18-setup-pyyaml-missing
+#
+# `bigpowers setup` must not crash when the resolved python3 lacks PyYAML.
+# Two setup-path scripts hard-depended on PyYAML: srp-engine.py (import yaml)
+# and validate-skill-yaml.py (sys.exit(2) on ImportError). Both now fall back
+# to scripts/lib/simple_yaml.py. This guard asserts:
+#   1. srp-engine.py parses a skill under a PyYAML-free interpreter.
+#   2. validate-skill-yaml.py runs (does not exit 2) under the same.
+#   3. simple_yaml's output equals PyYAML's for every skill's frontmatter
+#      (covers escaped quotes and folded/literal block scalars).
+#
+# Usage: bash scripts/test-setup-no-pyyaml.sh
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+GREEN='\033[0;32m'; RED='\033[0;31m'; NC='\033[0m'
+FAILURES=0
+pass() { echo -e "${GREEN}PASS${NC} $1"; }
+fail() { echo -e "${RED}FAIL${NC} $1"; FAILURES=$((FAILURES + 1)); }
+
+# Build a throwaway PyYAML-free interpreter — a fresh venv has no PyYAML,
+# reproducing a stock macOS python3 without touching the caller's environment.
+NOYAML_DIR="$(mktemp -d)"
+trap 'rm -rf "$NOYAML_DIR"' EXIT
+if ! python3 -m venv "$NOYAML_DIR/venv" >/dev/null 2>&1; then
+  echo "test-setup-no-pyyaml: SKIP — cannot create venv"; exit 0
+fi
+NOPY="$NOYAML_DIR/venv/bin/python"
+if "$NOPY" -c "import yaml" >/dev/null 2>&1; then
+  echo "test-setup-no-pyyaml: SKIP — fresh venv unexpectedly has PyYAML"; exit 0
+fi
+
+# 1. srp-engine.py must parse a skill's frontmatter without crashing.
+if "$NOPY" scripts/lib/srp-engine.py skills/fix-bug/SKILL.md >/dev/null 2>&1; then
+  pass "srp-engine.py parses frontmatter without PyYAML"
+else
+  fail "srp-engine.py crashed without PyYAML"
+fi
+
+# 2. validate-skill-yaml.py must not bail with exit 2 (the old PyYAML-required path).
+rc=0
+"$NOPY" scripts/validate-skill-yaml.py >/dev/null 2>&1 || rc=$?
+if [[ "$rc" -ne 2 ]]; then
+  pass "validate-skill-yaml.py runs without PyYAML (exit $rc)"
+else
+  fail "validate-skill-yaml.py bailed with exit 2 (PyYAML required)"
+fi
+
+# 3. Fallback fidelity: simple_yaml must equal PyYAML for every skill's
+#    frontmatter. Runs under python3 (CI has PyYAML); skips if PyYAML absent.
+if python3 - <<'PY'; then
+import glob, sys
+sys.path.insert(0, "scripts/lib")
+from simple_yaml import parse_simple_yaml
+try:
+    import yaml
+except ImportError:
+    print("skip: PyYAML not available for comparison"); sys.exit(0)
+bad = []
+for p in sorted(glob.glob("skills/*/SKILL.md")):
+    fm = open(p, encoding="utf-8").read().split("---")[1]
+    a = parse_simple_yaml(fm)
+    b = yaml.safe_load(fm)
+    for k in ("name", "description", "effort", "model"):
+        if a.get(k) != b.get(k):
+            bad.append(f"{p}:{k}")
+if bad:
+    print("mismatch: " + ", ".join(bad)); sys.exit(1)
+sys.exit(0)
+PY
+  pass "simple_yaml matches PyYAML for all skill frontmatter"
+else
+  fail "simple_yaml diverged from PyYAML for some skill frontmatter"
+fi
+
+if [[ "$FAILURES" -gt 0 ]]; then
+  echo "test-setup-no-pyyaml: $FAILURES failure(s)" >&2
+  exit 1
+fi
+echo "test-setup-no-pyyaml: PASS"

package/scripts/validate-skill-yaml.py

@@ -4,11 +4,18 @@ import glob
 import sys
 import os
 
+# Prefer PyYAML; fall back to the dependency-free scripts/lib/simple_yaml.py
+# (story e38s01) so `bigpowers setup` works on a python3 without PyYAML.
+# story: BUG-2026-07-18-setup-pyyaml-missing
+_LIB = os.path.join(os.path.dirname(os.path.abspath(__file__)), "lib")
 try:
     import yaml
-except ImportError:
-    print("ERROR: PyYAML required — pip install pyyaml")
-    sys.exit(2)
+    _load_yaml = yaml.safe_load
+except ModuleNotFoundError:
+    if _LIB not in sys.path:
+        sys.path.insert(0, _LIB)
+    from simple_yaml import parse_simple_yaml
+    _load_yaml = parse_simple_yaml
 
 SKILLS_DIR = ".pi/skills"
 files = sorted(glob.glob(f"{SKILLS_DIR}/*/SKILL.md"))
@@ -30,8 +37,8 @@ for path in files:
     frontmatter = parts[1]
 
     try:
-        data = yaml.safe_load(frontmatter)
-    except yaml.YAMLError as e:
+        data = _load_yaml(frontmatter)
+    except Exception as e:
         parse_failures.append((skill_name, str(e).split("\n")[0]))
         continue
 

package/skills/find-way/REFERENCE.md

@@ -0,0 +1,90 @@
+# Find-Way Reference
+
+## Ticket Anatomy
+
+Each ticket holds one question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+**Labels:** `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`
+
+**Claim:** Assign to yourself before any work — claim blocks concurrent sessions.
+
+**Blocking:** Use tracker's native dependency relationship so the frontier renders visually.
+
+**Resolution:** Post answer as a comment, close the issue, append to map's Decisions-so-far.
+
+## Resolution Protocol
+
+1. **Load the map** — read low-res view, not every ticket body
+2. **Choose & claim** — assign ticket to yourself (or take first frontier ticket if not named)
+3. **Resolve** — zoom into related/closed tickets as needed; invoke skills the Notes block names
+4. **Record** — post resolution comment with the answer, close the issue
+5. **Update map** — append to Decisions-so-far with one-line gist + link
+6. **Graduate fog** — create new tickets from newly-specifiable fog; clear from Not-yet-specified
+7. **Rule out of scope** if resolution reveals something past the destination
+
+## Ticket Types in Detail
+
+### Research (AFK)
+Surfacing facts from docs, APIs, or knowledge bases that a decision waits on.
+- Resolved by a `/research` subagent
+- Use when knowledge outside the working directory is required
+- **Label:** `wayfinder:research`
+
+### Prototype (HITL)
+Raise fidelity by building cheap, rough, concrete artifact to react to — outline, stub, UI/logic code.
+- Use the `/prototype` skill
+- Links the prototype as an asset
+- Use when "how should it look" or "how should it behave" is key
+- **Label:** `wayfinder:prototype`
+
+### Grilling (HITL)
+Conversation via `/grilling` and `/domain-modeling` skills, one question at a time.
+- The default case for clarifying decisions
+- **Label:** `wayfinder:grilling`
+
+### Task (HITL or AFK)
+Manual work unblocking a decision — signing up for service, provisioning access, moving data.
+- This is the **only** type that does rather than decides
+- Earns its place by unblocking a decision, not by delivering the destination
+- Agent drives AFK tasks alone; HITL tasks get precise checklist
+- **Label:** `wayfinder:task`
+
+## Fog-to-Ticket Graduation
+
+When resolving a ticket clears fog, graduate the newly-specifiable bits into fresh tickets:
+
+1. **Identify the fog** in Not-yet-specified that the resolution illuminates
+2. **Create new tickets** with crisp question statements
+3. **Wire blocking edges** if the new tickets depend on each other or existing ones
+4. **Clear from fog** — remove the graduated patch from Not-yet-specified so it lives only as its ticket
+
+## Out-of-Scope Close Protocol
+
+If a ticket turns out to sit past the destination:
+
+1. **Close the ticket** — mark it resolved or won't-fix
+2. **Add one line to Out of scope** — gist + why it's out of scope, linking the closed ticket
+3. **Never append to Decisions so far** — scope boundaries aren't steps on the route
+
+## Map State Transitions
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| **Open, unblocked, unclaimed** | Frontier — ready to take | Claim and resolve |
+| **Open, blocked** | Waiting on something | Wait for blockers to close |
+| **Open, claimed** | Concurrent session working | Skip for now |
+| **Closed** | Decided — lives in Decisions so far | Reference, don't re-open |
+
+## Concurrency
+
+Users may run unblocked tickets in parallel, so expect the tracker to be edited concurrently. Always:
+
+- Refresh the map before picking a ticket
+- Claim immediately before starting work
+- Never assume state hasn't changed since last read

package/skills/find-way/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: find-way
+phase: discover
+effort: standard
+model: sonnet
+description: Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building.
+---
+
+# Find Way
+
+## Concept
+
+A large effort arrives — too big for one session, wrapped in fog. **Find-way** charts the way as a **shared map** on the repo's issue tracker, then works **decision tickets** — questions whose resolution is a decision, not build slices — one at a time until the route is clear.
+
+**Plan, don't do.** Each ticket resolves a decision. The map is done when the way is clear — nothing left to decide before someone executes.
+
+**Refer by name.** Every map and ticket is an issue with a title. Always use the name, never bare ids or numbers.
+
+## The Map
+
+A single issue labelled `wayfinder:map` — the canonical artifact. Child issues are its tickets.
+
+```markdown
+## Destination
+<what reaching the end looks like — one or two lines>
+
+## Notes
+<domain, skills to consult, standing preferences>
+
+## Decisions so far
+- [closed ticket title](link) — one-line gist
+
+## Not yet specified
+<in-scope fog you can't ticket yet>
+
+## Out of scope
+<work ruled beyond the destination>
+```
+
+## Ticket Types
+
+| Type | Label | Mode | Purpose |
+|------|-------|------|---------|
+| Research | `wayfinder:research` | AFK | Surface facts from docs/APIs |
+| Prototype | `wayfinder:prototype` | HITL | Cheap artifact to react to |
+| Grilling | `wayfinder:grilling` | HITL | One-question-at-a-time dialogue |
+| Task | `wayfinder:task` | Either | Manual work unblocking a decision |
+
+**HITL** = human in the loop. **AFK** = agent alone.
+
+## Two Modes
+
+### Chart the Map
+
+User invokes with a loose idea.
+
+1. **Name the destination** — grill to pin down what this map finds its way to
+2. **Map the frontier** — breadth-first: surface open decisions and first steps. If no fog emerges, the effort fits one session — skip the map
+3. **Create the map** issue (label `wayfinder:map`)
+4. **Create tickets** as child issues, then wire blocking edges in a second pass
+5. **Fire research subagents** for each `research` ticket in parallel
+6. Stop — charting resolves nothing
+
+### Work Through the Map
+
+User invokes with a map (URL/number). Ticket optional — without one, pick the next frontier ticket.
+
+1. Load the map (low-res view)
+2. **Choose & claim** — assign ticket before any work
+3. **Resolve** — zoom into related/closed tickets as needed
+4. **Record** — post resolution comment, close issue, append to Decisions-so-far
+5. **Graduate fog** — create new tickets from newly-specifiable fog, clear from Not-yet-specified
+6. **Rule out of scope** if resolution reveals something past the destination
+
+**Never resolve more than one ticket per session** (except research).
+
+## Fog of War
+
+Beyond live tickets lies the **fog** — decisions you can tell are coming but can't pin down yet. The **Not yet specified** section holds this dim view.
+
+**Fog or ticket?** Test: can you state the question precisely now?
+
+- **Ticket** when the question is sharp (even if blocked)
+- **Not yet specified** when you can't phrase it sharply yet
+
+## Out of Scope
+
+Work beyond the destination. Ruling something out is a scoping act, not a route step. Never graduates — returns only if destination is redrawn.
+
+If an existing ticket sits past the destination, close it and note in Out of scope.
+
+## Blocking & Frontier
+
+- **Blocking**: tracker's native dependency relationship
+- **Unblocked**: every blocker is closed
+- **Frontier**: open, unblocked, unclaimed children — the edge of the known
+
+## Detailed Reference
+
+See [REFERENCE.md](REFERENCE.md) for ticket anatomy, resolution protocol, and examples.

package/skills/gate-trace/SKILL.md

@@ -74,7 +74,9 @@ gate_trace:
 ## Integration Points
 
 - **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
-- **sync-skills.yml** — CI gate (FAIL blocks pipeline).
+- **sync-skills.yml** — runs `trace-stories.sh --strict` as its "Traceability gate" step (FAIL
+  blocks pipeline), which shares this skill's coverage data (`traceability-matrix.json`) but
+  does not invoke a gate-trace PASS/CONCERNS/FAIL/WAIVED verdict directly.
 - **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
 
 ## References

package/skills-lock.json

@@ -131,6 +131,11 @@
       "sha256": "bb2bf81b5f948e10",
       "path": "skills/extract-designSKILL.md"
     },
+    "find-way": {
+      "description": "Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building.",
+      "sha256": "dff27aa0dc45c04d",
+      "path": "skills/find-waySKILL.md"
+    },
     "fix-bug": {
       "description": "Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect.",
       "sha256": "8e9e5922211b7e3b",
@@ -138,7 +143,7 @@
     },
     "gate-trace": {
       "description": "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\"",
-      "sha256": "ed37c315dcef6f87",
+      "sha256": "dd52baa85ff939e8",
       "path": "skills/gate-traceSKILL.md"
     },
     "generate-allure-report": {