bigpowers 2.63.0 → 2.64.1

package/scripts/build-receipts.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# story: e41s01
+# build-receipts.sh — aggregate all quality evidence into specs/receipts.json.
+set -euo pipefail
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "build-receipts: not inside a git repo" >&2; exit 1; }
+OUTFILE="$ROOT/specs/receipts.json"
+TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+emit_json() {
+  python3 -c "
+import json, sys, os, subprocess, glob as gb
+sections = {}
+
+# compliance
+comp = '$ROOT/specs/verifications/features/'
+if os.path.isdir(comp):
+    try:
+        r = subprocess.run(['bash','scripts/audit-compliance.sh','specs/verifications/features/','--dry-run'],
+            cwd='$ROOT', capture_output=True, text=True, timeout=30)
+        score = None
+        for line in r.stdout.splitlines():
+            if 'SCORE:' in line and '%' in line:
+                p = line.split('SCORE:')[1].strip()
+                s = p.split('%')[0].strip()
+                try: score = int(s)
+                except ValueError: pass
+                break
+        if score is not None:
+            sections['compliance'] = {'value':score,'generated_at':'$TIMESTAMP','source':'measured','command':'bash scripts/audit-compliance.sh specs/verifications/features/'}
+        else:
+            sections['compliance'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'bash scripts/audit-compliance.sh specs/verifications/features/'}
+    except Exception as e:
+        print(f'build-receipts: compliance error: {e}', file=sys.stderr)
+        sections['compliance'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'bash scripts/audit-compliance.sh specs/verifications/features/'}
+else:
+    sections['compliance'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'bash scripts/audit-compliance.sh specs/verifications/features/'}
+
+# golden
+gd = '$ROOT/specs/benchmarks/reports/'
+if os.path.isdir(gd):
+    reports = sorted(gb.glob(os.path.join(gd, 'GOLDEN-*.yaml')))
+    if reports:
+        try:
+            with open(reports[-1]) as f:
+                import yaml; data = yaml.safe_load(f)
+            sm = data.get('summary',{})
+            sections['golden_suite'] = {'value':{'pass_rate':sm.get('pass_rate'),'passed':sm.get('passed'),'total':sm.get('total'),'overall':sm.get('overall','unknown'),'timestamp':data.get('timestamp',''),'commit':data.get('git_commit','')},'generated_at':'$TIMESTAMP','source':'measured','command':'specs/benchmarks/reports/GOLDEN-*.yaml (latest)'}
+        except Exception as e:
+            print(f'build-receipts: golden error: {e}', file=sys.stderr)
+            sections['golden_suite'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/benchmarks/reports/GOLDEN-*.yaml'}
+    else:
+        sections['golden_suite'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/benchmarks/reports/GOLDEN-*.yaml'}
+else:
+    sections['golden_suite'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/benchmarks/reports/GOLDEN-*.yaml'}
+
+# metrics
+md = '$ROOT/specs/metrics/'
+if os.path.isdir(md):
+    mfs = sorted(gb.glob(os.path.join(md, '*.okf.md')))
+    sc = 0; st = {'measured':0,'estimated':0,'backfilled':0}; te = 0.0; tb = 0
+    for mf in mfs:
+        try:
+            with open(mf) as f: content = f.read()
+            parts = content.split('---')
+            if len(parts) < 3: continue
+            import yaml; fm = yaml.safe_load(parts[1])
+            if fm is None or fm.get('okf_kind') != 'story-metrics': continue
+            sc += 1; src = fm.get('source','absent')
+            if src in st: st[src] += 1
+            e = (fm.get('effort') or {}).get('effort_hours')
+            if e is not None:
+                try: te += float(e)
+                except: pass
+            b = fm.get('bcps')
+            if b is not None:
+                try: tb += int(b)
+                except: pass
+        except: pass
+    if sc > 0:
+        sections['metrics'] = {'value':{'story_count':sc,'total_effort_hours':round(te,1),'total_bcps':tb,'source_breakdown':st},'generated_at':'$TIMESTAMP','source':'measured','command':'specs/metrics/*.okf.md'}
+    else:
+        sections['metrics'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/metrics/*.okf.md'}
+else:
+    sections['metrics'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/metrics/*.okf.md'}
+
+# traceability
+tf = '$ROOT/specs/traceability-matrix.json'
+if os.path.isfile(tf):
+    try:
+        with open(tf) as f: matrix = json.load(f)
+        stories = matrix.get('stories',[])
+        ts = len(stories); ls = sum(1 for s in stories if s.get('link_count',0)>0); lc = sum(s.get('link_count',0) for s in stories)
+        sections['traceability'] = {'value':{'total_stories':ts,'linked_stories':ls,'total_links':lc,'coverage_pct':round(ls/ts*100,1) if ts>0 else 0,'generated_at':matrix.get('generated_at','')},'generated_at':'$TIMESTAMP','source':'measured','command':'specs/traceability-matrix.json (trace-matrix.py)'}
+    except Exception as e:
+        print(f'build-receipts: trace error: {e}', file=sys.stderr)
+        sections['traceability'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/traceability-matrix.json'}
+else:
+    sections['traceability'] = {'source':'absent','generated_at':'$TIMESTAMP','command':'specs/traceability-matrix.json'}
+
+with open('$OUTFILE','w') as f: json.dump(sections,f,indent=2)
+print(f'build-receipts: wrote {len(sections)} sections to specs/receipts.json')
+for key, sec in sections.items(): print(f'  {key}: source={sec.get(\"source\",\"?\")}')
+"
+}
+echo "build-receipts: aggregating quality evidence..."
+emit_json
+echo "build-receipts: done — $(date -u +%H:%M:%SZ)"
+exit 0

package/scripts/build-skill-graph.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# story: e39s01
+# Consumes bigpowers-mcp build_skill_graph MCP tool output (graph.jsonl)
+# and emits specs/skill-graph.json + specs/skills-wiki/ OKF concepts.
+#
+# Supersedes standalone SKILL.md parsing approach (2026-07-04).
+# Graph must be built first: run MCP tool `build_skill_graph` or
+# `node -e "..."` to generate bigpowers-mcp/graph.jsonl.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+GRAPH_IN="$REPO_ROOT/bigpowers-mcp/graph.jsonl"
+GRAPH_OUT="$REPO_ROOT/specs/skill-graph.json"
+WIKI_DIR="$REPO_ROOT/specs/skills-wiki/skills"
+
+# --help
+if [[ "${1:-}" == "--help" ]]; then
+  cat <<EOF
+Usage: build-skill-graph.sh
+
+Reads bigpowers-mcp/graph.jsonl (generated by e32 build_skill_graph MCP tool)
+and produces:
+  specs/skill-graph.json  — nodes + typed edges (depends_on, gates, references,
+                             enforces, handoff_to)
+  specs/skills-wiki/      — one OKF concept markdown file per skill
+
+Options:
+  --help    Show this message
+  --json    Write only specs/skill-graph.json (skip OKF wiki)
+  --wiki    Write only specs/skills-wiki/ (skip JSON graph)
+
+Requires: bigpowers-mcp/graph.jsonl (run build_skill_graph MCP tool first)
+EOF
+  exit 0
+fi
+
+MODE="${1:-both}"
+case "$MODE" in
+  --json) DO_JSON=1; DO_WIKI=0 ;;
+  --wiki) DO_JSON=0; DO_WIKI=1 ;;
+  both)   DO_JSON=1; DO_WIKI=1 ;;
+  *)      echo "Unknown option: $MODE" >&2; exit 1 ;;
+esac
+
+# Pre-flight: graph.jsonl must exist
+if [[ ! -f "$GRAPH_IN" ]]; then
+  cat >&2 <<EOF
+ERROR: $GRAPH_IN not found.
+
+The skill graph has not been built yet. Run the bigpowers-mcp
+build_skill_graph tool to generate it:
+
+  # Option A: via MCP inspector
+  npx @modelcontextprotocol/inspector node bigpowers-mcp/build/index.js
+  # Then call build_skill_graph
+
+  # Option B: via Node.js directly
+  node -e "
+    const {discoverSkills,readSkillFile}=require('./bigpowers-mcp/build/lib/skill-parser.js');
+    const {buildGraphFromSkills}=require('./bigpowers-mcp/build/lib/graph/builder.js');
+    const {saveGraph}=require('./bigpowers-mcp/build/lib/graph/store.js');
+    const skills=discoverSkills(process.cwd(),()=>'');
+    const parsed=skills.map(s=>readSkillFile(process.cwd(),s.name));
+    saveGraph('bigpowers-mcp/graph.jsonl', buildGraphFromSkills(parsed));
+  "
+EOF
+  exit 1
+fi
+
+# Parse graph.jsonl into nodes + edges
+echo "Reading $GRAPH_IN ..." >&2
+
+NODES_JSON="$REPO_ROOT/specs/.tmp-nodes.json"
+EDGES_JSON="$REPO_ROOT/specs/.tmp-edges.json"
+
+python3 - "$GRAPH_IN" "$NODES_JSON" "$EDGES_JSON" <<'PYEOF'
+import json, sys
+from pathlib import Path
+
+graph_in = Path(sys.argv[1])
+nodes_out = Path(sys.argv[2])
+edges_out = Path(sys.argv[3])
+
+nodes = []
+edges = []
+entity_count = 0
+relation_count = 0
+parse_errors = 0
+
+with open(graph_in) as f:
+    for lineno, line in enumerate(f, 1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError as e:
+            print(f"WARNING: {graph_in}:{lineno}: invalid JSON — {e}", file=sys.stderr)
+            parse_errors += 1
+            continue
+
+        if obj.get("type") == "entity":
+            nodes.append({
+                "name": obj["name"],
+                "entityType": obj.get("entityType", "Skill"),
+                "observations": obj.get("observations", []),
+            })
+            entity_count += 1
+        elif obj.get("type") == "relation":
+            edges.append({
+                "from": obj["from"],
+                "to": obj["to"],
+                "relationType": obj.get("relationType", "unknown"),
+            })
+            relation_count += 1
+        else:
+            print(f"WARNING: {graph_in}:{lineno}: unknown type {obj.get('type')}", file=sys.stderr)
+
+with open(nodes_out, "w") as f:
+    json.dump(nodes, f, indent=2)
+with open(edges_out, "w") as f:
+    json.dump(edges, f, indent=2)
+
+print(f"  Entities: {entity_count}, Relations: {relation_count}", file=sys.stderr)
+if parse_errors:
+    print(f"  Parse errors: {parse_errors}", file=sys.stderr)
+PYEOF
+
+# Emit specs/skill-graph.json
+if [[ "$DO_JSON" -eq 1 ]]; then
+  echo "Writing $GRAPH_OUT ..." >&2
+  python3 - "$NODES_JSON" "$EDGES_JSON" "$GRAPH_OUT" <<'PYEOF'
+import json, sys
+
+with open(sys.argv[1]) as f:
+    nodes = json.load(f)
+with open(sys.argv[2]) as f:
+    edges = json.load(f)
+
+graph = {"nodes": nodes, "edges": edges}
+with open(sys.argv[3], "w") as f:
+    json.dump(graph, f, indent=2)
+
+print(f"  nodes: {len(nodes)}, edges: {len(edges)}", file=sys.stderr)
+PYEOF
+fi
+
+# Emit specs/skills-wiki/ OKF concepts
+if [[ "$DO_WIKI" -eq 1 ]]; then
+  echo "Writing $WIKI_DIR/ ..." >&2
+  rm -rf "$WIKI_DIR"
+  mkdir -p "$WIKI_DIR"
+
+  python3 - "$NODES_JSON" "$WIKI_DIR" <<'PYEOF'
+import json, sys, re
+from pathlib import Path
+
+nodes_file = Path(sys.argv[1])
+wiki_dir = Path(sys.argv[2])
+
+with open(nodes_file) as f:
+    nodes = json.load(f)
+
+count = 0
+for node in nodes:
+    name = node["name"]
+    observations = node.get("observations", [])
+
+    model = ""
+    effort = ""
+    description = ""
+    for obs in observations:
+        if obs.startswith("model: "):
+            model = obs[7:]
+        elif obs.startswith("effort: "):
+            effort = obs[8:]
+        elif obs.startswith("description: "):
+            description = obs[13:]
+
+    # Derive phase from name convention (simplified)
+    phase = "utility"
+    critical_path = [
+        "survey-context", "elaborate-spec", "model-domain", "define-language",
+        "design-interface", "plan-work", "plan-release", "slice-tasks",
+        "kickoff-branch", "develop-tdd", "verify-work", "audit-code",
+        "commit-message", "release-branch", "security-review",
+        "assess-impact", "investigate-bug", "validate-fix",
+    ]
+    if name in critical_path:
+        phase = "critical-path"
+
+    safe_desc = description.replace('"', '\\"')
+    md = f"""---
+type: Skill
+name: {name}
+phase: {phase}
+model: {model}
+effort: {effort}
+description: "{safe_desc}"
+---
+
+# {name}
+
+**Phase:** {phase}
+**Model:** {model}
+**Effort:** {effort}
+
+{description}
+
+> Auto-generated by build-skill-graph.sh (e39s01) from bigpowers-mcp/graph.jsonl.
+> Source of truth: skills/{name}/SKILL.md
+"""
+    out_path = wiki_dir / f"{name}.md"
+    out_path.write_text(md)
+    count += 1
+
+print(f"  concepts written: {count}", file=sys.stderr)
+PYEOF
+fi
+
+# Cleanup
+rm -f "$NODES_JSON" "$EDGES_JSON"
+
+echo "Done." >&2

package/scripts/build-skill-index.sh

@@ -1,28 +1,18 @@
 #!/usr/bin/env bash
-# build-skill-index.sh — lexical index for search-skills (zero embedding deps)
+# story: e28s04
+# build-skill-index.sh — lexical index for search-skills
 set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 OUT="$REPO_ROOT/specs/SKILL-SEARCH-INDEX_LATEST.md"
 mkdir -p "$(dirname "$OUT")"
-
-{
-  echo "# Skill Search Index (auto-generated)"
-  echo ""
-  echo "Regenerate: \`bash scripts/build-skill-index.sh\`"
-  echo ""
-  echo "| name | model | description |"
-  echo "|------|-------|-------------|"
-  for skill_dir in $(find "$REPO_ROOT" -maxdepth 1 -mindepth 1 -type d | sort); do
+{ echo "# Skill Search Index (auto-generated)"; echo ""; echo "Regenerate: \`bash scripts/build-skill-index.sh\`"; echo ""; echo "| name | model | description |"; echo "|------|-------|-------------|"
+  while IFS= read -r skill_dir; do
     skill_md="$skill_dir/SKILL.md"
-    [[ -f "$skill_md" ]] || continue
-    name=$(awk '/^---/{f++} f==1 && /^name:/{print; exit}' "$skill_md" | sed 's/^name:[[:space:]]*//')
-    model=$(awk '/^---/{f++} f==1 && /^model:/{print; exit}' "$skill_md" | sed 's/^model:[[:space:]]*//')
-    desc=$(awk '/^---/{f++} f==1 && /^description:/{sub(/^description:[[:space:]]*/,""); print; exit}' "$skill_md" \
-      | tr -d '\n' | sed 's/|/\\|/g' | LC_ALL=C head -c 200)
+    parse_frontmatter "$skill_md" || continue
+    name="$_PF_NAME"; model="${_PF_MODEL:-sonnet}"
+    desc=$(echo "$_PF_DESCRIPTION" | sed 's/|/\\|/g' | LC_ALL=C head -c 200)
     [[ -z "$name" ]] && continue
-    echo "| $name | ${model:-sonnet} | $desc |"
-  done
+    echo "| $name | $model | $desc |"
+  done < <(iterate_skills)
 } > "$OUT"
-
 echo "build-skill-index: wrote $OUT"

package/scripts/generate-skill-index.sh

@@ -5,12 +5,10 @@
 # DO NOT edit SKILL-INDEX.md manually — it is auto-generated.
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+
 LOCKFILE="$REPO_ROOT/skills-lock.json"
 INDEX_FILE="$REPO_ROOT/SKILL-INDEX.md"
-# SKILLS_ROOT: use skills/ when it exists, fall back to repo root
-SKILLS_ROOT="$REPO_ROOT"
-[[ -d "$REPO_ROOT/skills" ]] && SKILLS_ROOT="$REPO_ROOT/skills"
 
 if [[ ! -f "$LOCKFILE" ]]; then
   echo "generate-skill-index: ERROR — skills-lock.json not found. Run regenerate-lockfile.sh first." >&2

package/scripts/record-cycle-time.sh

@@ -37,7 +37,7 @@
 # Usage:
 #   scripts/record-cycle-time.sh report [--range <git-range>] [--story-key <key>]
 #   scripts/record-cycle-time.sh append --story <id> --bcps <n> \
-#         [--range <git-range>] [--merged-at <epoch>] [--file <path>] [--story-key <key>]
+#         [--bcp-plus <n>] [--range <git-range>] [--merged-at <epoch>] [--file <path>] [--story-key <key>]
 #
 # `report`  prints the per-story partition + an additivity self-check.
 # `append`  recomputes the partition and appends one row for <id> to the ledger.
@@ -59,9 +59,7 @@ Usage: scripts/record-cycle-time.sh <command> [flags]
 Commands:
   report      Compute per-story effort partition + additivity self-check.
               Flags: --range <git-range>  --story-key <trailer-key>
-  append      Recompute partition and append one row for a story.
-              Flags: --story <id> --bcps <n> [--range <git-range>]
-                     [--merged-at <epoch>] [--file <path>] [--story-key <trailer-key>]
+  append      Recompute partition and append one row for a story.\n              Flags: --story <id> --bcps <n> [--bcp-plus <n>] [--range <git-range>]\n                     [--merged-at <epoch>] [--file <path>] [--story-key <trailer-key>]
   self-test   Run report, then exit 0 on additivity PASS; exit 1 on FAIL.
               Flags: --range <git-range>  --story-key <trailer-key>
   help        Show this message.
@@ -133,6 +131,7 @@ cmd_append() {
     case "$1" in
       --story) story="$2"; shift 2 ;;
       --bcps) bcps="$2"; shift 2 ;;
+      --bcp-plus) bcp_plus="$2"; shift 2 ;;
       --range) range="$2"; shift 2 ;;
       --merged-at) merged_at="$2"; shift 2 ;;
       --file) file="$2"; shift 2 ;;
@@ -216,6 +215,9 @@ cmd_append() {
     printf -- 'id: %s\n' "$story"
     printf -- 'epic: %s\n' "${story%%s*}"          # e40s03 → e40
     printf -- 'bcps: %s\n' "$bcps"
+    if [ -n "$bcp_plus" ]; then
+      printf -- 'bcp_plus: %s\n' "$bcp_plus"
+    fi
     printf -- 'commit_range: "%s..%s"\n' "${range_lo:-$range_hi}" "$range_hi"
     printf -- 'source: measured\n'
     printf -- 'generated_at: %s\n' "$generated_at"

package/scripts/regenerate-lockfile.sh

@@ -1,49 +1,21 @@
 #!/usr/bin/env bash
+# story: e28s04
 # regenerate-lockfile.sh — Scan all SKILL.md files and regenerate skills-lock.json
-# Output: Canonical catalog with name, description, sha256, path for every skill.
-# Run this after adding, removing, or updating any skill.
 set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 LOCKFILE="$REPO_ROOT/skills-lock.json"
-# SKILLS_ROOT: use skills/ when it exists, fall back to repo root
-SKILLS_ROOT="$REPO_ROOT"
-[[ -d "$REPO_ROOT/skills" ]] && SKILLS_ROOT="$REPO_ROOT/skills"
-
-# Build JSON using jq from individual skill records
-# We pipe each skill as a JSON object, then jq -s merges them into an object keyed by name
 records=()
-for skill_dir in "$SKILLS_ROOT"/*/; do
+while IFS= read -r skill_dir; do
   skill_md="$skill_dir/SKILL.md"
-  [[ -f "$skill_md" ]] || continue
-
   name=$(basename "$skill_dir")
-  # Extract description from YAML frontmatter (between first --- and second ---)
-  description=$(awk '/^---/{f++; next} f==1 && /^description:/{p=1; sub(/^description:[[:space:]]*/,""); print; next} f==1 && p && /^[a-z]+:/{exit} f==1 && p{print}' "$skill_md" \
-    | tr -d '\n' | sed -E 's/[[:space:]]+/ /g')
-
-  # Compute SHA-256 of full SKILL.md content (first 16 hex chars for compact uniqueness)
-  # Falls back to shasum for macOS where sha256sum is not installed by default
-  if command -v sha256sum &>/dev/null; then
-    sha256=$(sha256sum "$skill_md" | cut -c1-16)
-  else
-    sha256=$(shasum -a 256 "$skill_md" | cut -c1-16)
-  fi
-
-  # Relative path from repo root
+  parse_frontmatter "$skill_md" || continue
+  description="$_PF_DESCRIPTION"
+  if command -v sha256sum &>/dev/null; then sha256=$(sha256sum "$skill_md" | cut -c1-16)
+  else sha256=$(shasum -a 256 "$skill_md" | cut -c1-16); fi
   relpath="${skill_dir#$REPO_ROOT/}SKILL.md"
-
-  # Emit JSON record for this skill
-  records+=("$(jq -n --arg name "$name" \
-                       --arg desc "$description" \
-                       --arg sha "$sha256" \
-                       --arg path "$relpath" \
+  records+=("$(jq -n --arg name "$name" --arg desc "$description" --arg sha "$sha256" --arg path "$relpath" \
     '{($name): {description: $desc, sha256: $sha, path: $path}}')")
-done
-
-# Merge all records into a single "skills" object with version
-jq -n --argjson skills "$(printf '%s\n' "${records[@]}" | jq -s 'add')" \
-  '{version: 1, skills: $skills}' > "$LOCKFILE"
-
+done < <(iterate_skills)
+jq -n --argjson skills "$(printf '%s\n' "${records[@]}" | jq -s 'add')" '{version: 1, skills: $skills}' > "$LOCKFILE"
 count=$(jq '.skills | length' "$LOCKFILE")
 echo "regenerate-lockfile: $count skills written to skills-lock.json"