bigpowers 2.66.0 → 2.67.1

package/scripts/okf-post-sync.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# story: e39s04
+# okf-post-sync.sh — Post-processing pipeline for OKF skills-wiki generation.
+# Called by sync-skills.sh --okf after concept files are rendered.
+# Steps: cross-references from skill-graph.json → index.md → validate-okf.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+GRAPH_JSON="$REPO_ROOT/specs/skill-graph.json"
+OKF_WIKI_SKILLS="$REPO_ROOT/specs/skills-wiki/skills"
+OKF_WIKI_DIR="$REPO_ROOT/specs/skills-wiki"
+OKF_INDEX="$OKF_WIKI_DIR/index.md"
+
+# ── Step 1: Run build-skill-graph.sh for cross-references ──────────
+echo ""
+echo "--- OKF post-sync ---"
+echo "Step 1: Cross-references from skill graph..."
+
+if [[ -x "$REPO_ROOT/scripts/build-skill-graph.sh" ]]; then
+  bash "$REPO_ROOT/scripts/build-skill-graph.sh" --json || {
+    echo "  WARNING: build-skill-graph.sh --json failed; cross-references will be fallback" >&2
+  }
+else
+  echo "  WARNING: build-skill-graph.sh not found" >&2
+fi
+
+# ── Step 2: Add cross-references from skill-graph.json ─────────────
+echo "Step 2: Adding cross-references to OKF concepts..."
+
+if [[ -f "$GRAPH_JSON" ]] && command -v python3 &>/dev/null; then
+  python3 "$REPO_ROOT/scripts/okf-add-references.py" "$GRAPH_JSON" "$OKF_WIKI_SKILLS"
+else
+  echo "  Adding fallback references..."
+  for f in "$OKF_WIKI_SKILLS"/*.md; do
+    [[ -f "$f" ]] || continue
+    python3 -c "
+import re
+c = open('$f').read()
+c = re.sub(r'references:\s*\[\]', 'references:\n  - concept: skills-wiki\n    type: belongs_to', c)
+open('$f','w').write(c)
+" 2>/dev/null || true
+  done
+fi
+
+# ── Step 3: Generate index.md with progressive disclosure ──────────
+echo "Step 3: Generating index.md..."
+
+python3 - "$OKF_WIKI_SKILLS" "$OKF_INDEX" <<'PYEOF'
+import re, sys
+from pathlib import Path
+from collections import defaultdict
+
+wiki_skills = Path(sys.argv[1])
+index_path = Path(sys.argv[2])
+
+concepts = []
+for f in sorted(wiki_skills.glob("*.md")):
+    content = f.read_text()
+    fm_match = re.search(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not fm_match:
+        continue
+    fm_text = fm_match.group(1)
+    name = title = phase = model = effort = description = ""
+    for line in fm_text.split('\n'):
+        line = line.strip()
+        if line.startswith('name:'): name = line.split(':', 1)[1].strip()
+        elif line.startswith('title:'): title = line.split(':', 1)[1].strip().strip('"')
+        elif line.startswith('phase:'): phase = line.split(':', 1)[1].strip()
+        elif line.startswith('model:'): model = line.split(':', 1)[1].strip()
+        elif line.startswith('effort:'): effort = line.split(':', 1)[1].strip()
+        elif line.startswith('description:'): description = line.split(':', 1)[1].strip().strip('"')
+    if not name:
+        continue
+    concepts.append({
+        "name": name,
+        "title": title or name.replace('-', ' ').title(),
+        "phase": phase or "utility",
+        "model": model,
+        "effort": effort,
+        "description": (description[:120] + "...") if len(description) > 120 else description,
+    })
+
+phases = defaultdict(list)
+for c in concepts:
+    phases[c["phase"]].append(c)
+
+total = len(concepts)
+cp = phases.get("critical-path", [])
+util = phases.get("utility", [])
+
+with open(index_path, "w") as out:
+    out.write(f"""---
+okf_kind: concept
+type: Index
+id: skills-wiki
+title: "BigPowers Skills Wiki"
+category: skills
+description: "Progressive-disclosure index of {total} bigpowers skills ({len(cp)} critical-path, {len(util)} utility) — auto-generated by sync-skills.sh --okf (e39s04)."
+references:
+  - concept: bigpowers
+    type: belongs_to
+---
+
+# BigPowers Skills Wiki
+
+**{total} skills** ({len(cp)} critical-path, {len(util)} utility)
+
+> Auto-generated by sync-skills.sh --okf (e39s04). Source of truth: skills/*/SKILL.md files.
+
+## Critical-Path Skills ({len(cp)})
+
+These skills form the bigpowers core development loop.
+
+| Skill | Model | Effort | Description |
+|-------|-------|--------|-------------|
+""")
+    for c in cp:
+        out.write(f"| [{c['title']}](skills/{c['name']}.md) | {c['model']} | {c['effort']} | {c['description']} |\n")
+
+    out.write(f"""
+## Utility Skills ({len(util)})
+
+Supporting skills for specialised workflows.
+
+| Skill | Model | Effort | Description |
+|-------|-------|--------|-------------|
+""")
+    for c in util:
+        out.write(f"| [{c['title']}](skills/{c['name']}.md) | {c['model']} | {c['effort']} | {c['description']} |\n")
+
+    out.write(f"""
+## Quick Reference
+
+- **Total skills:** {total}
+- **Critical-path:** {len(cp)}
+- **Utility:** {len(util)}
+- **Format:** OKF concept bundles (okf_kind: concept)
+- **Validation:** `bash scripts/validate-okf.sh --dir specs/skills-wiki/skills`
+""")
+
+print(f"  index.md written: {total} skills ({len(cp)} critical-path, {len(util)} utility)")
+PYEOF
+
+# ── Step 4: Validate OKF conformance ───────────────────────────────
+echo "Step 4: Validating OKF conformance..."
+
+VALIDATE_SCRIPT="$REPO_ROOT/scripts/validate-okf.sh"
+if [[ -x "$VALIDATE_SCRIPT" ]]; then
+  if bash "$VALIDATE_SCRIPT" --dir "$OKF_WIKI_SKILLS" 2>&1; then
+    echo "  OKF validation: PASSED"
+  else
+    OKF_EXIT=$?
+    echo "  OKF validation: exit code $OKF_EXIT (non-zero — see output above)" >&2
+  fi
+else
+  echo "  WARNING: validate-okf.sh not found; skipping validation" >&2
+fi
+
+OKF_COUNT=$(find "$OKF_WIKI_SKILLS" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+echo ""
+echo "okf-post-sync: $OKF_COUNT OKF concepts generated"
+echo "  → specs/skills-wiki/skills/ ($OKF_COUNT .md files)"
+echo "  → specs/skills-wiki/index.md (progressive-disclosure index)"

package/scripts/validate-okf.sh

@@ -292,6 +292,24 @@ validate_bundle() {
     EXIT_CODE=1
     return
   }
+
+  # ── OKF v0.1 Generic Frontmatter Conformance (e39s10) ──
+  # Check required 'type' field
+  local fm_type
+  fm_type="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('type',''))" 2>/dev/null)"
+  if [ -z "$fm_type" ]; then
+    printf "${RED}FAIL${NC} %s: OKF v0.1 — missing required 'type' field\n" "$name"
+    EXIT_CODE=1
+    return
+  fi
+
+  # Reserved filenames: index.md must have type: Index
+  if [ "$name" = "index.md" ] && [ "$fm_type" != "Index" ]; then
+    printf "${RED}FAIL${NC} %s: OKF v0.1 — index.md must have type: Index (got '%s')\n" "$name" "$fm_type"
+    EXIT_CODE=1
+    return
+  fi
+
   local kind
   kind="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('okf_kind',''))" 2>/dev/null)"
   case "$kind" in

package/skills/build-epic/SKILL.md

@@ -43,6 +43,14 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 8. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
 9. **Traceability refresh:** Before step 8 (release-branch), run `bash scripts/trace-stories.sh` to regenerate `specs/traceability-matrix.json`, `specs/TRACEABILITY_LATEST.md`, and the `specs/codebase-wiki/` OKF bundle. Surface dark/orphan/stale findings for the just-built epic in your verify summary. If `scripts/trace-stories.sh` is missing or fails, note "trace skipped" and continue — trace failure must be visible, not silent (blocking is gate-trace's job, e38s06).
 
+9b. **OKF wiki refresh (e39s08):** Before step 8, run maintain-wiki INGEST to refresh the OKF wiki bundle:
+   ```bash
+   bash scripts/decompose-conventions.sh
+   bash scripts/generate-agent-guide.sh
+   ```
+   If any script is missing or fails, note "OKF wiki refresh skipped" and continue.
+   This is non-blocking — stale concepts are caught by LINT in verify-work Phase 3.
+
 ### Step 6 — audit-code gate (non-optional)
 
 After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:

package/skills/gate-trace/SKILL.md

@@ -37,7 +37,8 @@ TEA-inspired: if trace links rely on heuristics rather than explicit tags, confi
 3. Read `specs/traceability-matrix.json` and `specs/blind-spots.json`.
 4. Apply decision rules R1–R5 in order (first match wins).
 5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`.
-6. Output verdict + rationale to stdout.
+6. **Drift check (e39s03):** If `specs/drift-report.json` exists and has suspect links, mark verdict as CONCERNS with note: "Drift detected — some implementing files are newer than their specs. Run scripts/check-spec-drift.sh for details."
+7. Output verdict + rationale to stdout.
 7. Update `specs/execution-status.yaml` with gate-trace result.
 
 ## Verdict Semantics

package/skills/kickoff-branch/SKILL.md

@@ -95,6 +95,25 @@ git checkout -b <task-slug>
 
 ### 4. Verify clean baseline
 
+> **HARD GATE (e39s02):** Acquire story lock in `specs/agent-locks.yaml` before running tests.
+
+```bash
+LOCK="specs/agent-locks.yaml"; STORY="<story-id>"
+if [ -f "$LOCK" ]; then
+  python3 -c "
+import yaml,sys,datetime
+d=yaml.safe_load(open('$LOCK'))or{'locks':[]}
+for l in d['locks']:
+  if l['story_id']=='$STORY':print(f'LOCKED by {l[\"locked_by\"]} at {l[\"locked_at\"]}');sys.exit(1)
+d['locks'].append({'story_id':'$STORY','locked_by':'agent: build-epic','locked_at':datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),'files_touched':[]})
+yaml.dump(d,open('$LOCK','w'),default_flow_style=False)
+print(f'LOCK ACQUIRED: $STORY')
+"
+fi
+```
+
+If locked: abort. If unlocked: entry added, proceed.
+
 Run the full test suite and confirm it passes before writing any code:
 
 ```bash

package/skills/maintain-wiki/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: maintain-wiki
+model: haiku
+effort: light
+description: "Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3."
+# story: e39s07
+---
+
+# Maintain Wiki
+
+Three operations for keeping the OKF wiki bundle consistent with its source docs.
+
+## INGEST
+
+Read source doc (CLAUDE.md, CONVENTIONS.md, or SKILL.md) and write/update OKF concept pages:
+
+```bash
+# Regenerate skills-wiki from SKILL.md files
+bash scripts/sync-skills.sh --okf
+
+# Regenerate conventions-wiki from CONVENTIONS.md
+bash scripts/decompose-conventions.sh
+
+# Regenerate agent-guide from CLAUDE.md
+bash scripts/generate-agent-guide.sh
+```
+
+## LINT
+
+Check for common OKF issues:
+
+1. **Stale concepts** — source file mtime vs concept page mtime. If source is newer, concept is stale.
+2. **Orphan concepts** — concept page exists but source doc section no longer exists.
+3. **Missing cross-references** — skill concept pages with no `enforced_by` or `references` links.
+4. **Contradictions** — two concept pages that make opposite claims about the same topic.
+5. **Broken links** — internal OKF links that point to non-existent concept pages.
+
+```bash
+# Quick stale check: compare source vs concept mtimes
+for page in specs/skills-wiki/skills/*.md; do
+  skill=$(basename "$page" .md)
+  source="skills/$skill/SKILL.md"
+  if [ -f "$source" ] && [ "$page" -ot "$source" ]; then
+    echo "STALE: $skill (SKILL.md newer than concept page)"
+  fi
+done
+```
+
+## QUERY
+
+Search across OKF concept pages to answer questions:
+
+```bash
+# Find all concepts about a topic
+grep -rl "topic" specs/skills-wiki/ specs/conventions-wiki/ specs/agent-guide/
+
+# Trace a convention → enforcing skills
+grep -A1 "enforced_by" specs/conventions-wiki/*.md
+
+# Find skill by description keyword
+grep -ril "keyword" specs/skills-wiki/skills/*.md
+```
+
+## Verify
+
+→ verify: `test -d specs/skills-wiki && test -d specs/conventions-wiki && test -d specs/agent-guide && echo "OKF wiki present" || echo "FAIL"`

package/skills/plan-tests/SKILL.md

@@ -34,7 +34,7 @@ Bridges the gap between slicing and planning by systematically designing the tes
 
 ## Verify
 
-→ verify: `test -f specs/tech-architecture/$(echo $EPIC | sed "s|.*/||")-TEST_PLAN_LATEST.md && echo OK`
+→ verify: `ls specs/tech-architecture/*-TEST_PLAN_LATEST.md 2>/dev/null | head -1 && echo OK || echo "SKIP: no test plan yet — EPIC not set or not generated"`
 
 ## Handoff
 

package/skills/release-branch/SKILL.md

@@ -13,7 +13,6 @@ description: Make the merge/PR/keep/discard decision for a feature branch, verif
 Finalize a completed feature branch: verify coverage gates, integrate onto `main`, and clean up the worktree.
 
 ## Additional modes
-
 - `--hotfix`: Cherry-pick to main + tag. Skip PR in solo.
 - `--squash-state`: Squash `chore(state):` commits before merge.
 
@@ -76,9 +75,7 @@ bash scripts/land-branch.sh <task-slug> "feat(scope): description"
 
 ### 6. Create PR (team-pr only)
 
-See [REFERENCE.md](REFERENCE.md) for the full PR body template and gh commands.
-
-### 7. Merge (team-pr only)
+Create the pull request, then merge via `gh`:
 
 ```bash
 gh pr merge --squash --delete-branch
@@ -94,22 +91,32 @@ gh pr merge --squash --delete-branch
 mv specs/epics/eNN-slug specs/epics/archive/
 ```
 
-### 7b. CI verification (solo-local and team-pr)
+### 7b. CI verification & agent lock release (e39s02)
 
 > **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
 
-After push (solo-local step 5 or team-pr step 7), run the CI polling script:
+After push, run CI polling:
 
 ```bash
 bash scripts/wait-for-ci.sh --timeout 600 --interval 30
 ```
 
-The script auto-discovers workflow runs for the pushed commit and polls until completion.
-See [REFERENCE.md](REFERENCE.md) for exit code semantics and git-only fallback.
+Then release the story lock:
+
+```bash
+LOCK="specs/agent-locks.yaml"; STORY="<story-id>"
+[ -f "$LOCK" ] && python3 -c "
+import yaml
+d=yaml.safe_load(open('$LOCK'))
+if d:d['locks']=[l for l in d['locks'] if l.get('story_id')!='$STORY']
+yaml.dump(d,open('$LOCK','w'),default_flow_style=False)
+print(f'LOCK RELEASED: $STORY')
+"||echo "No lock for $STORY — idempotent"
+```
 
 - [ ] CI workflow passes after push (wait-for-ci.sh exit 0)
 - [ ] `release.ci_verified: true` documented in state.yaml
-- On failure: `handoff.next_skill = fix-bug` with the CI failure URL
+- On failure: `handoff.next_skill = fix-bug` with CI failure URL
 
 ### 8. Clean up worktree
 
@@ -130,16 +137,13 @@ bash scripts/record-cycle-time.sh append \
   --file specs/metrics/cycle-times.yaml
 ```
 
-This replaces the previous hand-arithmetic approach (story_end minus story_start).
-See [REFERENCE.md](REFERENCE.md) for the git-hours model and field definitions.
-
 ### 9. Return to main
 
 ```bash
 git checkout main && git status && pwd
 ```
 
-Report: "Branch released. Integrate mode: <solo-local|team-pr>. cwd: $(pwd) on $(git branch --show-current)."
+Report: "Branch released."
 
 ## Verify
 

package/skills/verify-work/SKILL.md

@@ -109,6 +109,13 @@ phases:
     closed: true
 ```
 
+### 5b. OKF wiki LINT (e39s08)
+
+```bash
+for p in specs/skills-wiki/skills/*.md; do s="skills/$(basename "$p" .md)/SKILL.md"; [ -f "$s" ]&&[ "$p" -ot "$s" ]&&echo "STALE: $p"; done
+for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&continue; grep -q "$(basename "$p" .md)" CONVENTIONS.md||echo "ORPHAN: $p"; done
+```
+
 > **HARD GATE** — Verification evidence MUST be persisted before marking the story done. No evidence = not verified.
 
 ## --cli mode
@@ -132,15 +139,12 @@ BINARY=$(grep '^BIN\s*=' Makefile 2>/dev/null | awk '{print $3}')
 3. Happy-path: run documented example command from README.md → assert non-empty output
 4. Edge case: `$BINARY --invalid-flag` → assert exit code ≠ 0 and error message printed
 
-No "stop server" or "clear caches" steps are executed in `--cli` mode. Steps 3–6 of the default process (mechanical gates, UAT, gaps loop) still run unchanged.
+No "stop server" / "clear caches" in `--cli` mode. Steps 3–6 still run unchanged.
 
 ## Verify
 
 → verify: `find specs/verifications -maxdepth 1 -name '*-verify.yaml' 2>/dev/null | head -1 | grep -q . && echo "Evidence persisted" || echo "No evidence yet"`
 
-See [REFERENCE.md](REFERENCE.md) for cold-start and gaps template.
-
 ## Handoff
-
-Gate: READY -> next: audit-code
+READY -> next: audit-code
 Writes: state.yaml handoff.next_skill = audit-code

package/skills-lock.json

@@ -23,7 +23,7 @@
     },
     "build-epic": {
       "description": "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.",
-      "sha256": "96fd5e0cc63a9962",
+      "sha256": "230ac9d30cae1a63",
       "path": "skills/build-epicSKILL.md"
     },
     "change-request": {
@@ -128,7 +128,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.\"# story: e38s06",
-      "sha256": "7326525dc3d5d51f",
+      "sha256": "81deb2549867386b",
       "path": "skills/gate-traceSKILL.md"
     },
     "grill-me": {
@@ -163,9 +163,14 @@
     },
     "kickoff-branch": {
       "description": "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions \"start a branch\" or \"new worktree\".",
-      "sha256": "2857dac9f23bd7be",
+      "sha256": "928d87bae8cc4ddf",
       "path": "skills/kickoff-branchSKILL.md"
     },
+    "maintain-wiki": {
+      "description": "\"Agent-maintained OKF wiki — INGEST source docs, LINT for issues, QUERY across concept pages. Run as part of build-epic Step 8 and verify-work Phase 3.\"# story: e39s07",
+      "sha256": "c54c6170db6fe3f9",
+      "path": "skills/maintain-wikiSKILL.md"
+    },
     "map-codebase": {
       "description": "\"Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does.\"",
       "sha256": "cfd8a71a3cdb63af",
@@ -203,7 +208,7 @@
     },
     "plan-tests": {
       "description": "\"Design a risk-scaled test architecture for an epic before implementation begins. Produces prioritized scenarios, test level distribution, and fixture plans based on TEA and bigpowers principles.\"",
-      "sha256": "3f43a105b860105a",
+      "sha256": "ed22b3feb985eabb",
       "path": "skills/plan-testsSKILL.md"
     },
     "plan-work": {
@@ -223,7 +228,7 @@
     },
     "release-branch": {
       "description": "Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says \"release\", \"merge\", or \"open a PR\".",
-      "sha256": "354267f0f4b593b5",
+      "sha256": "73a9aebff3fb4dc0",
       "path": "skills/release-branchSKILL.md"
     },
     "request-review": {
@@ -348,7 +353,7 @@
     },
     "verify-work": {
       "description": "Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.",
-      "sha256": "030622528b2bf5ed",
+      "sha256": "300e5a7c7695e33f",
       "path": "skills/verify-workSKILL.md"
     },
     "visual-dashboard": {

package/tests/fixtures/v1.x-project/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md — v1.x Project
+## Commands
+- npm test
+- npm start

package/tests/fixtures/v1.x-project/CONVENTIONS.md

@@ -0,0 +1,4 @@
+# CONVENTIONS.md — v1.x
+## Naming
+- kebab-case for files
+- camelCase for functions

package/tests/fixtures/v2.0.0-project/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md — v2.0.0
+## Commands
+- npm test
+- npm start

package/tests/fixtures/v2.0.0-project/CONVENTIONS.md

@@ -0,0 +1,3 @@
+# CONVENTIONS.md — v2.0.0
+## Naming
+- kebab-case

package/tests/fixtures/v2.20-project/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md — v2.20
+## Commands
+- npm test
+- npm run lint

package/tests/fixtures/v2.20-project/CONVENTIONS.md

@@ -0,0 +1,4 @@
+# CONVENTIONS.md — v2.20
+## Naming
+- kebab-case
+- YAML cockpit