bigpowers 2.84.0 → 2.85.0

package/scripts/validate-agentic-ste.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# story: e79s02
+# validate-agentic-ste.sh — mechanical Agentic STE checks for instructional prose.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+MAX_WORDS=20
+BANNED_RE='\b(should|might|could|may|consider|try|generally|typically)\b'
+
+STRICT=false
+AUDIT=false
+SELF_TEST=false
+TARGETS=()
+
+ste_usage() {
+  echo "Usage: bash scripts/validate-agentic-ste.sh [--self-test|--strict|--audit] [file|dir ...]"
+  echo "  (no args)     Run built-in fixture self-test"
+  echo "  --strict      Exit 1 on violations (craft-skill gate)"
+  echo "  --audit       WARN-only catalog scan (stocktake)"
+  exit 2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --strict) STRICT=true; shift ;;
+    --audit) AUDIT=true; shift ;;
+    --self-test) SELF_TEST=true; shift ;;
+    -h|--help) ste_usage ;;
+    --) shift; TARGETS+=("$@"); break ;;
+    -*) echo "Unknown flag: $1" >&2; ste_usage ;;
+    *) TARGETS+=("$1"); shift ;;
+  esac
+done
+
+VIOLATIONS=0
+WARNINGS=0
+
+ste_report_fail() {
+  echo "FAIL: $1" >&2
+  VIOLATIONS=$((VIOLATIONS + 1))
+}
+
+ste_report_warn() {
+  echo "WARN: $1" >&2
+  WARNINGS=$((WARNINGS + 1))
+}
+
+ste_strip_frontmatter() {
+  awk '
+    BEGIN { n=0; emit=0 }
+    /^---$/ { n++; if (n==1) next; if (n==2) { emit=1; next } }
+    emit { print }
+  ' "$1"
+}
+
+ste_extract_prose() {
+  local file="$1"
+  local body
+  if [[ "$(basename "$file")" == "SKILL.md" ]]; then
+    body="$(ste_strip_frontmatter "$file")"
+  else
+    body="$(cat "$file")"
+  fi
+  printf '%s\n' "$body" | awk '
+    BEGIN { in_code=0 }
+    /^```/ { in_code = !in_code; next }
+    in_code { next }
+    /^[[:space:]]*#/ { next }
+    /^[[:space:]]*\|/ { next }
+    /^[[:space:]]*<!--/ { next }
+    /^[[:space:]]*$/ { next }
+    /^# story:/ { next }
+    /^<!-- story:/ { next }
+    { print }
+  '
+}
+
+ste_count_words() {
+  # shellcheck disable=SC2207
+  local words=($1)
+  echo "${#words[@]}"
+}
+
+ste_audit_line() {
+  local file="$1"
+  local line_no="$2"
+  local line="$3"
+  local label="${file}:${line_no}"
+
+  if echo "$line" | grep -qiE "$BANNED_RE"; then
+    local word
+    word="$(echo "$line" | grep -oiE "$BANNED_RE" | head -1)"
+    if $STRICT; then
+      ste_report_fail "$label — banned hedge modal '$word'"
+    else
+      ste_report_warn "$label — banned hedge modal '$word'"
+    fi
+  fi
+
+  local sentence
+  while IFS= read -r sentence; do
+    [[ -z "$sentence" ]] && continue
+    local trimmed
+    trimmed="$(echo "$sentence" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    [[ -z "$trimmed" ]] && continue
+    local wc
+    wc="$(ste_count_words "$trimmed")"
+    if (( wc > MAX_WORDS )); then
+      if $STRICT; then
+        ste_report_fail "$label — sentence has ${wc} words (max ${MAX_WORDS}): ${trimmed:0:60}..."
+      else
+        ste_report_warn "$label — sentence has ${wc} words (max ${MAX_WORDS}): ${trimmed:0:60}..."
+      fi
+    fi
+  done < <(echo "$line" | sed 's/[.!?]/&\n/g')
+}
+
+ste_audit_file() {
+  local file="$1"
+  [[ -f "$file" ]] || { ste_report_fail "not found: $file"; return; }
+
+  local prose line_no=0
+  prose="$(ste_extract_prose "$file")"
+  while IFS= read -r line; do
+    line_no=$((line_no + 1))
+    ste_audit_line "$file" "$line_no" "$line"
+  done <<< "$prose"
+}
+
+ste_collect_files() {
+  local path="$1"
+  if [[ -f "$path" ]]; then
+    echo "$path"
+  elif [[ -d "$path" ]]; then
+    find "$path" -type f \( -name 'SKILL.md' -o -name 'CLAUDE.md' -o -name 'CONVENTIONS.md' -o -name 'AGENTS.md' \) | sort
+  fi
+}
+
+ste_run_self_test() {
+  local tmp
+  tmp="$(mktemp -d)"
+  trap 'rm -rf "$tmp"' RETURN
+
+  cat > "$tmp/good-skill.md" <<'EOF'
+---
+name: fixture-good
+description: Test fixture for Agentic STE validator. Use when running self-test.
+---
+# Fixture Good
+> **HARD GATE** — Run Preflight before forward work.
+Run tests after every change.
+Write specs to specs/ at project root.
+EOF
+
+  cat > "$tmp/bad-hedge.md" <<'EOF'
+---
+name: fixture-bad
+description: Bad fixture.
+---
+You should consider running tests generally.
+EOF
+
+  cat > "$tmp/bad-long.md" <<'EOF'
+---
+name: fixture-long
+description: Long sentence fixture.
+---
+Run the full local green stack including compliance verification gates sync skills trace stories and catalog drift check before any forward implementation work on this repository.
+EOF
+
+  local saved_strict=$STRICT saved_audit=$AUDIT
+  STRICT=true
+  AUDIT=false
+  VIOLATIONS=0
+
+  ste_audit_file "$tmp/good-skill.md"
+  if (( VIOLATIONS > 0 )); then
+    echo "SELF-TEST FAIL: good fixture should pass" >&2
+    return 1
+  fi
+
+  VIOLATIONS=0
+  ste_audit_file "$tmp/bad-hedge.md"
+  if (( VIOLATIONS == 0 )); then
+    echo "SELF-TEST FAIL: hedge fixture should fail" >&2
+    return 1
+  fi
+
+  VIOLATIONS=0
+  ste_audit_file "$tmp/bad-long.md"
+  if (( VIOLATIONS == 0 )); then
+    echo "SELF-TEST FAIL: long-sentence fixture should fail" >&2
+    return 1
+  fi
+
+  STRICT=$saved_strict
+  AUDIT=$saved_audit
+  VIOLATIONS=0
+  echo "validate-agentic-ste: self-test PASS"
+  return 0
+}
+
+if $SELF_TEST || [[ ${#TARGETS[@]} -eq 0 ]]; then
+  ste_run_self_test
+  exit $?
+fi
+
+if $AUDIT; then
+  STRICT=false
+fi
+
+for target in "${TARGETS[@]}"; do
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && ste_audit_file "$f"
+  done < <(ste_collect_files "$target")
+done
+
+if (( VIOLATIONS > 0 )); then
+  echo "validate-agentic-ste: $VIOLATIONS violation(s)" >&2
+  exit 1
+fi
+
+if $AUDIT; then
+  echo "validate-agentic-ste: audit complete ($WARNINGS warning(s))"
+else
+  echo "validate-agentic-ste: PASS"
+fi

package/skills/audit-code/SKILL.md

@@ -99,6 +99,10 @@ bash scripts/lib/parallel-review-worktrees.sh audit-code
 - [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable
 - [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)
 
+### Refactoring Smells (Fowler)
+
+Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.
+
 ### Code Style (CONVENTIONS.md)
 
 - [ ] Functions: 4–20 lines; split if longer
@@ -110,13 +114,6 @@ bash scripts/lib/parallel-review-worktrees.sh audit-code
 - [ ] Conditionals: expressed as positives (G29)
 - [ ] Comments explain WHY, not WHAT
 
-### Agent Readability (Akita's Lens)
-
-- [ ] Functions are small enough to fit in a standard context window (4–20 lines)
-- [ ] Names are unique and specific enough to be `grep`-able (grep returns < 5 hits)
-- [ ] Types are explicit (no `any`, no inferred return types for public APIs)
-- [ ] Code avoids deep nesting (max 2 levels) and uses early returns
-
 ### Red Flags
 
 Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.

package/skills/craft-skill/SKILL.md

@@ -1,5 +1,6 @@
 # story: e45s02
 <!-- story: e45s12 -->
+<!-- story: e79s02 -->
 ---
 name: craft-skill
 model: sonnet
@@ -9,7 +10,7 @@ description: Create new bigpowers skills with proper structure, progressive disc
 
 # Craft Skill
 
-> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md.
+> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh`. Generated `.cursor/rules/` and `.gemini/` artifacts MUST match the source SKILL.md.
 
 ## CSO Description Discipline (e45s02)
 
@@ -24,11 +25,25 @@ The YAML `description` is the **Catalog Selection Object** — the only field ag
 
 Move process detail into the SKILL.md body or REFERENCE.md — never into `description`.
 
+## Agentic STE body discipline (e79s02)
+
+Skill-body instructional prose MUST follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md).
+
+| Rule | Limit |
+|------|-------|
+| Sentence length | ≤20 words per instruction sentence |
+| Voice | Imperative, active |
+| Directive terms | MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT |
+| Banned modals | should, might, could, may, consider, try, generally, typically |
+| Scope | SKILL.md body only — not YAML `description`, not `terse-mode` output |
+
+> **HARD GATE** — Do NOT merge a new or edited skill until `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` exits 0. Fix violations before `sync-skills.sh`.
+
 ## Process
 
 1. **Gather requirements** — ask user about:
    - What task/domain does the skill cover?
-   - What specific use cases should it handle?
+   - Which use cases must the skill handle?
    - Does it need executable scripts or just instructions?
    - Any reference materials to include?
    - What specs/ output does it produce (if any)?
@@ -44,7 +59,8 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
    - Additional reference files if content exceeds 100 lines
    - Utility scripts if deterministic operations needed
 
-   **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source.
+   **Auto-skill from library README:** When user provides a library README or API docs URL, extract triggers and HARD GATEs.
+   Draft verify commands and specs/ output into SKILL.md. Do NOT invent APIs not in the source.
 
 4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md).
 
@@ -53,10 +69,11 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
 5. **Review with user** — present draft and ask:
    - Does this cover your use cases?
    - Anything missing or unclear?
-   - Should any section be more/less detailed?
+   - Does any section need more or less detail?
 
 6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done:
    - Run `bash scripts/validate-skill-description.sh skills/<name>/SKILL.md` — must exit 0
+   - Run `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` — must exit 0 (e79s02)
    - Run `bash scripts/sync-skills.sh` — must complete without error
    - Run `bash scripts/run-skill-verify.sh <name>` if the skill defines a verify command
    - Show terminal output for each — narration without evidence is rejected
@@ -81,6 +98,7 @@ After drafting, verify:
 - [ ] Consistent terminology with CONVENTIONS.md
 - [ ] specs/ output documented if applicable
 - [ ] `validate-skill-description.sh` exits 0
+- [ ] `validate-agentic-ste.sh --strict` exits 0 (e79s02)
 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini
 - [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty)
 

package/skills/grill-me/SKILL.md

@@ -19,6 +19,14 @@ Interview relentlessly about every aspect of this plan until reaching shared und
 
 If a question can be answered by exploring the codebase, explore it instead.
 
+### Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by exploring the codebase, reading docs, or checking APIs. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the code, go find it. Only ask questions where the user's judgment is needed.
+
 ## Docs mode
 
 Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process.
@@ -30,3 +38,7 @@ Short form:
 4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
 5. Update the plan for each confirmed discrepancy.
 
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+

package/skills/grill-with-docs/SKILL.md

@@ -24,6 +24,18 @@ effort: standard
 - If docs contradict the plan, plan loses until updated.
 - Prefer official docs over blog posts.
 
+## Facts vs. Decisions Boundary
+
+Distinguish between **facts** and **decisions**:
+- **Facts** — things discoverable by reading docs, checking APIs, or exploring the codebase. Do not ask the user to confirm facts; find them yourself.
+- **Decisions** — choices that require user input (trade-offs, preferences, priorities). Always present options and ask the user to choose.
+
+Never "grill yourself" — if the answer is in the docs, go fetch it. Only ask questions where the user's judgment is needed.
+
+## Confirmation Gate
+
+> **HARD GATE** — Do NOT enact the plan or generate specifications until the user explicitly confirms shared understanding. Wait for explicit approval (e.g., "looks good", "confirmed", "proceed") before transitioning to any implementation, spec-writing, or task-slicing step.
+
 ## Verify
 
 → verify: `grep -c 'https\?://' skills/grill-with-docs/SKILL.md | awk '{if($1>=2) print "OK"; else print "NEEDS DOCS"}'`

package/skills/request-review/SKILL.md

@@ -90,6 +90,7 @@ Review for:
 4. Design — are there simpler or more robust approaches?
 5. Edge cases — what inputs or states could cause failures?
 6. Security — any injection, auth, or data exposure risks?
+7. Refactoring smells — explicitly name any detected Fowler smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man
 
 For each finding, categorize as: must-fix / should-fix / consider.
 Run the verify command and report the result.

package/skills/seed-conventions/SKILL.md

@@ -10,6 +10,7 @@ description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project throu
 # story: e10s02
 # story: e51s02
 # story: e45s21
+# story: e79s03
 
 
 # Seed Conventions
@@ -33,13 +34,25 @@ Ask the user these questions (one at a time, wait for each answer):
 2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
 2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
 3. **Commands** — "What commands do you use for: run, test, build, lint?"
-3b. **Preflight (optional)** — "What single command runs your full local green stack (test + lint + build)? If you don't have one, we'll chain your Test + Lint + Build answers into a **Preflight** row in the Commands table."
+3b. **Preflight (optional)** — "What command runs test, lint, and build together? If none, chain Test + Lint + Build into one **Preflight** row."
 4. **Architecture** — "Key modules and relationships in 1–2 sentences."
 5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
 6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
 7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
 8. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in).
 
+## Agentic STE for generated prose (e79s03)
+
+When writing instructional lines in `CLAUDE.md`, `AGENTS.md`, or `CONVENTIONS.md`, follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md):
+
+- Use directive vocabulary: MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT
+- Do NOT use hedge modals listed in AGENTIC-STE.md Rule 3
+- Cap each instruction sentence at 20 words
+- Write imperative, active-voice lines — one instruction per line
+- Do NOT apply Agentic STE to `terse-mode` (output compression is out of scope)
+
+After generation, run `bash scripts/validate-agentic-ste.sh --strict CLAUDE.md CONVENTIONS.md` when those files exist in the target project.
+
 ## Generate files
 
 After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
@@ -66,9 +79,11 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 
 **Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
 
-`specs/state.yaml` carries a top-level `workflow_mode` key (`team-pr` | `solo-git`, default `solo-git`). This is the **canonical integrate-mode signal** for all skills — set it once here and skills such as `release-branch` read it from this file instead of sniffing profile files.
+`specs/state.yaml` carries top-level `workflow_mode` (`team-pr` | `solo-git`, default `solo-git`).
+This is the **canonical integrate-mode signal** for all skills.
+Set it once here. Skills such as `release-branch` read this file instead of sniffing profiles.
 
-When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`).
+When generating `CLAUDE.md`, chain Test + Lint + Build into one **Preflight** row if the user named no Preflight command.
 
 ### Self-installing fenced markers (e45s21)
 
@@ -80,7 +95,9 @@ Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment
 <!-- END bigpowers:section-id -->
 ```
 
-**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file.
+**Merge rule:** On update, replace only content between matching `BEGIN`/`END` pairs.
+If a marker pair is missing, append a new fenced block at file end.
+Never rewrite the whole file.
 
 **Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
 

package/skills/stocktake-skills/SKILL.md

@@ -9,6 +9,7 @@ effort: standard
 
 # story: e09s01
 <!-- story: e45s12 -->
+<!-- story: e79s04 -->
 
 
 # Stocktake Skills
@@ -28,6 +29,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 ## Process
 
 0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
+0b. **Agentic STE audit (e79s04)** — run `bash scripts/validate-agentic-ste.sh --audit skills/`. Flag hedge words and sentences over 20 words per [AGENTIC-STE.md](../../docs/AGENTIC-STE.md). Record WARN lines in the stocktake report as **STE debt** — do NOT rewrite the full catalog in one pass. Route critical repeat offenders to `evolve-skill`.
 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
 2. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).

package/skills/visual-dashboard/scripts/frame-template.html

@@ -232,45 +232,7 @@
     <div id="claude-content" class="spread">
       <div class="wrap">
         <div class="grid">
-          <div class="band section">
-            <h2 class="opt-align">Dashboard Template</h2>
-            <p class="subtitle">Mockup and structure using the new 12-column Müller-Brockmann grid.</p>
-          </div>
-
-          <div class="band section split">
-            <div>
-              <h3 class="opt-align">Split Left (6 cols)</h3>
-              <p>Aligned precisely to the grid. All baselines lock to 8px.</p>
-            </div>
-            <div>
-              <h3 class="opt-align">Split Right (6 cols)</h3>
-              <p>The gap between is precisely one gutter (24px).</p>
-            </div>
-          </div>
-
-          <div class="band section cards">
-            <div class="card">
-              <div class="card-image">Img 1</div>
-              <div class="card-body">
-                <h3>Card 1 (4 cols)</h3>
-                <p>Three cards fit perfectly in 12 columns.</p>
-              </div>
-            </div>
-            <div class="card">
-              <div class="card-image">Img 2</div>
-              <div class="card-body">
-                <h3>Card 2 (4 cols)</h3>
-                <p>Aligned on the baseline.</p>
-              </div>
-            </div>
-            <div class="card selected">
-              <div class="card-image">Img 3</div>
-              <div class="card-body">
-                <h3>Card 3 (4 cols)</h3>
-                <p>This card is selected.</p>
-              </div>
-            </div>
-          </div>
+          <!-- CONTENT -->
       <!-- GRID GUIDES -->
       <div class="guides" aria-hidden="true">
         <div class="cols"></div><div class="rows"></div>