@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/architecture/decisions/ADR-044-unified-skill-body-template.md

@@ -0,0 +1,162 @@
+---
+adr: 044
+tier: lite
+title: Unified SKILL body template — converges Amazon PR-FAQ, Cooper, Krug, Beck, Anthropic, OpenAI
+status: proposed
+date: 2026-07-19
+supersedes:
+  - ADR-040 Decision 4
+authoring_luminaries:
+  primary:
+    - amazon-pr-faq
+    - alan-cooper
+    - steve-krug
+    - kent-beck
+  supporting:
+    - anthropic (external — platform.claude.com best practices + skill-creator SKILL.md)
+    - openai (external — OpenAI Academy skills guidance)
+tickets:
+  - sunj-labs/bassclef-upstream#798
+description: Bassclef ships two competing SKILL body specs.
+---
+
+# ADR-044 — Unified SKILL body template
+
+## Context
+
+Bassclef ships two competing SKILL body specs. ADR-040 Decision 4 prescribes an Amazon PR-FAQ shape (H1 + mock announcement + when-to-use + FAQ + details below the fold). `.claude/skills/skill/SKILL.md` Step 3 prescribes a different scaffold (When to use / When NOT to use / Usage / Procedure / Composes with / Distinct from / Rules / Sources read / Why this skill exists). Neither cites the other. Neither embeds every discipline the converged best practices name.
+
+Bet 19i audit at `architecture/audits/2026-07-19-scope-a-pre-simplification-intent.md` surfaced two follow-on problems:
+
+- INSTEAD-block regression across 12 of 17 planning-adjacent skills after Scope A + Scope B rewrites. Grandfathered through 2026-08-18 per bassclef#1249 allowlist.
+- Scope A + Scope B applied ADR-040 D4 and stripped disciplines the `/skill` scaffold still enforces (INSTEAD blocks, Composes with, Distinct from, When NOT to use).
+
+An internal consultation compared 4 luminaries against 3 external best-practice sources. Six disciplines carry three or more upvotes from independent sources. Two more disciplines (progressive disclosure, examples pattern) are Anthropic's biggest recommendations neither current template names.
+
+Operator picked path c per direct feedback on 2026-07-19 — one unified template supersedes both prior specs.
+
+## Decision
+
+Every rewritten SKILL body follows the unified template below. This ADR supersedes ADR-040 Decision 4 for SKILL body shape. The `/skill` skill's Step 3 scaffold updates to output this template. The `substrate-clarity-gate.sh` hook extends to check for missing sections (advisory V1; BLOCK V2 after grace window).
+
+### Frontmatter
+
+Required fields per bassclef#377 + Anthropic naming spec:
+
+- `name` — lowercase-letters + numbers + hyphens; up to 64 chars. Gerund form preferred (`processing-pdfs`, `writing-documentation`) per Anthropic; noun phrase or action-oriented forms accepted.
+- `description` — up to 280 chars per bassclef#377. Third person per Anthropic mandate. Includes both what the skill does AND when to use it. Pushy trigger per Anthropic skill-creator ("Use whenever the user mentions X").
+- `tier` — one of `upstream | lite | standard | ultra` per ADR-043 tier axis.
+- `maturity` — one of `alpha | beta | stable | hardened` per ADR-043 maturity axis. Optional; defaults to `stable` when absent.
+- `user_invocable`, `disable_model_invocation` — Anthropic Claude Code convention.
+- `modes` / `tiers` / `sizes` — YAML list when applicable. Mirrored inline in description per bassclef#535.
+- `composes_with` — YAML list of skill names this skill dispatches. Enforced by substrate-clarity-gate to resolve to real skills.
+- `depends_on` — YAML list of preconditions (skills, rules, or config blocks). Advisory in V1.
+
+### Body sections (in order)
+
+1. **`# /skill-name`** — H1 with plain-English slash-command form. Krug trunk-test signal: reader identifies the skill at first line.
+
+2. **`## What you get`** — outcome-framed opener. Past tense as if the skill already shipped its result. Amazon PR-FAQ discipline: describe what the operator sees when the skill finishes, not the mechanics. One to two paragraphs; grade 8-9 English.
+
+3. **`## When to use it`** — persona-explicit discriminator per Cooper. Open with the primary persona ("Sam invokes this when...") when persona applies. Otherwise open with the triggering condition. Includes the discriminator against sibling skills. One paragraph.
+
+4. **`## When NOT to use`** — Krug trunk-test / anti-scope. Names skills the reader should reach for instead. One paragraph or bullet list.
+
+5. **`## FAQ`** — 4 to 6 anticipated adopter questions with 2-3 sentence answers each. Questions written in third person from the reader's viewpoint ("What does X do?"; not "How do I use X?"). Krug + Cooper discipline; Amazon PR-FAQ shape.
+
+6. **`## Details below the fold`** — the runnable protocol. Numbered steps with feedback loops named per Anthropic + Beck. Optional if the skill body is dispatch-only.
+
+7. **`## Examples`** — input / output pairs for output-quality-critical skills. Anthropic + OpenAI + Beck agree. Required when the skill produces prose, code, or structured output the operator will read or ship. Optional when the skill is action-only (e.g., pure state read).
+
+8. **`## Anti-patterns and INSTEAD`** — required table per Cooper + Krug + bassclef#371. Left column names the anti-pattern; right column names the INSTEAD substitute. At least 3 rows. Enforced by substrate-clarity-gate.
+
+9. **`## Composes with`** — bullet list of skills this skill dispatches OR extends. Relational metadata; substrate-clarity-gate verifies references resolve.
+
+10. **`## Distinct from`** — bullet list of adjacent skills the reader might confuse with this one; each entry names how this one differs. Cooper disambiguation.
+
+11. **`## Rules`** — self-check bullets the agent runs before / during / after. Anthropic feedback-loop discipline made explicit.
+
+12. **`## Output discipline`** — dispatch `/kiss words --grade10` on the full rendered output before posting. Applies to opener + tables + cards + step details + recommendation + closing prose. Not just the opener. Not an inline BLOCK-term scan. Actual skill dispatch per bassclef-upstream#858 pilot on /longrun + /sprint. Required for skills that emit operator-facing prose. Skipped only when the skill emits no operator-facing prose (pure state read, JSON output only) — declare `no_operator_output: true` in frontmatter to opt out. Added by bassclef-upstream#859 Iteration A WU-A1.
+
+13. **`## Test cases`** — evaluation prompts per Anthropic + Beck. Required when the skill body is over 100 lines OR ships to bassclef-lite. Each test carries an ID, a prompt, and expected behavior. Small skills MAY defer to a stub row.
+
+14. **`## Sources read`** — evidence trail per bassclef#559 (assert-only-after-verify). Every claim in the body cites the source read inline. Placeholder for the author to fill.
+
+15. **`## Why this skill exists`** — rationale for the reader. Names the class of failure the skill prevents or the pattern it captures.
+
+### Progressive disclosure
+
+Anthropic's biggest recommendation. When the SKILL.md body approaches 500 lines, split domain-specific detail into referenced files at `.claude/skills/<slug>/references/<domain>.md`. Reference files must be one level deep from SKILL.md — Claude will partially read files that reference other files.
+
+Reference files longer than 100 lines carry a table of contents at the top per Anthropic.
+
+Executable scripts live at `.claude/skills/<slug>/scripts/`. Scripts execute via bash; their contents do not consume context tokens until read.
+
+### Prose disciplines (mandatory across every section)
+
+Two clarity checks fire at compose time via `/skill` Step 4 and again at Write time via the settings.json hook chain:
+
+- **FKGL grade 8-9 for 80% of prose; ceiling 10 per sentence** per bassclef#790 + `.claude/rules/operator-facing-prose.md`. Enforced by `.claude/hooks/skill-body-grade-gate.sh`. Structured spec content that legitimately grades high uses `<!-- FKGL-EXEMPT: reason --> ... <!-- /FKGL-EXEMPT -->` blocks.
+- **Compound nouns outside the allowlist BLOCK** per `standards/bassclef-internal-jargon.md`. Enforced by `.claude/hooks/compound-noun-scrub.sh`. Allowlist covers standard tech vocab (pre-commit, YAML, API). Bassclef-internal compounds (load-bearing, blast-radius, tier-preset) are the substitution table's block list.
+
+The `/skill` scaffold at Step 4 runs the full three-layer chain before Write — substrate-clarity-gate + skill-body-grade-gate + compound-noun-scrub. A `/skill` dispatch that produces a draft failing any layer returns to Step 2 (description work) or Step 3 (body work) automatically. The composer catches issues at compose time, not at Write time.
+
+### Grace window
+
+Per `.claude/rules/we-dont-break-adopters.md` — existing SKILL bodies read through 2026-10-31 under prior shapes (ADR-040 D4 or the older `/skill` scaffold). New skills authored from this ADR's ship date land under the unified template. Existing skills refactored under bassclef-lite Path X''' start from their pre-2026-07-16 body per operator direction, apply the unified template, and regenerate baseline vectors per #795.
+
+## Consequences
+
+### Positive
+
+- One template governs SKILL body shape across bassclef. Two-template drift retires.
+- INSTEAD-block discipline enforced by required Anti-patterns section. Closes bassclef#1249 allowlist grace at expiry.
+- Progressive disclosure enables SKILL bodies to grow without exceeding 500 lines. Anthropic-native pattern.
+- Examples pattern makes output-quality-critical skills verifiable at read time.
+- Test cases section makes every SKILL body evaluation-ready per Anthropic.
+- Persona-explicit discriminator per Cooper; adopters see who the skill serves at first glance.
+- ADR-043 tier + maturity fields codified in the frontmatter spec.
+
+### Negative
+
+- Longer body sections list than ADR-040 D4 (14 sections vs 5). Trade-off: comprehensive vs terse.
+- Every SKILL body under 100 lines still owes at least the required sections. Small skills gain overhead.
+- Refactor cost across ~30 lite skills starting from pre-2026-07-16 bodies is substantial. Grace window absorbs.
+
+### Neutral
+
+- The `/skill` scaffold updates to output the unified template. Existing scaffold users get the new shape from the next `/skill` dispatch.
+- `substrate-clarity-gate.sh` V1 advisory; V2 BLOCK after grace window closes.
+
+## Alternatives considered
+
+**Path a — patch ADR-040 D4 to add INSTEAD-block requirement only.** Smallest cure; closes the INSTEAD-block regression. Rejected because it leaves the two-template drift.
+
+**Path b — patch both ADR-040 D4 and the `/skill` scaffold to add missing convergence disciplines.** Middle ground; keeps two specs synchronized. Rejected because keeping two specs synchronized is the root failure mode. One breaks; the other rots.
+
+**Path c — one ADR-044 replaces both.** Selected. Root-cause fix.
+
+## Related decisions
+
+- ADR-040 Decision 4 (superseded by this ADR for SKILL body shape)
+- ADR-040 Decision 1 (planning-skill vocabulary — bet → goal, chronicle → session log) — unrelated to shape; stays as-is
+- ADR-041 (adopter-count-based grace window discipline)
+- ADR-043 (two-axis tier + maturity)
+
+## Sources read
+
+- Consultation memo at operator-private consultation path (local-only)
+- `.claude/luminaries/amazon-pr-faq.md`
+- `.claude/luminaries/alan-cooper.md`
+- `.claude/luminaries/steve-krug.md`
+- `.claude/luminaries/kent-beck.md`
+- External — platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices via WebFetch
+- External — github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md via WebFetch
+- External — academy.openai.com/public/clubs/work-users-ynjqu/resources/skills via WebFetch
+- `architecture/decisions/ADR-040-planning-skill-vocabulary-and-lite-profile.md` § Decision 4
+- `.claude/skills/skill/SKILL.md` Step 3 scaffold
+- `.claude/rules/context-engineering.md` (bassclef#371)
+- `.claude/rules/skill-description-clarity.md` (bassclef#377)
+- `.claude/hooks/substrate-clarity-gate.sh` (bassclef#382)
+- `architecture/audits/2026-07-19-scope-a-pre-simplification-intent.md`
+- Operator direct feedback on 2026-07-19 (path c pick + pre-2026-07-16 constraint)

package/dist/lite/lib/clean-artifacts-sweep.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# lib/clean-artifacts-sweep.sh — shared deep module for workflow-exhaust
+# sweep. Both /session-end (lite) and /clean-artifacts (standard) source this.
+#
+# Public interface (per docs/decompositions/2026-08-25-clean-artifacts-sweep.md):
+#   clean_artifacts_sweep [--delete] [--age=N]
+#
+# Env:
+#   SWEEP_ROOT      — root directory to sweep (default: $PWD)
+#   CURRENT_BRANCH  — current branch for marker exclusion (default: git detect)
+#
+# Exit codes:
+#   0 — sweep completed (dry-run or delete)
+#   1 — refusal (too many / too large / bad state)
+#   2 — delete error (partial state; caller reports)
+#
+# Anchor luminaries: @luminary john-ousterhout (deep module),
+# @luminary tony-hoare (safety list is precondition boundary),
+# @luminary alan-cooper (Sam-language in stdout),
+# @luminary michael-feathers (characterization of SKILL body L1-L230).
+
+clean_artifacts_sweep() {
+  local delete=0 age_override="" arg
+  for arg in "$@"; do
+    case "$arg" in
+      --delete) delete=1 ;;
+      --age=*) age_override="${arg#--age=}" ;;
+      *) echo "clean_artifacts_sweep: unknown arg '$arg'" >&2; return 1 ;;
+    esac
+  done
+
+  local root="${SWEEP_ROOT:-$PWD}"
+  local cur_branch="${CURRENT_BRANCH:-$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '')}"
+  local cur_slug="${cur_branch#feature/}"; cur_slug="${cur_slug#fix/}"; cur_slug="${cur_slug//\//-}"
+
+  local age_marker=7 age_screenshot=7 age_trace=30
+  if [ -n "$age_override" ]; then
+    age_marker="$age_override"; age_screenshot="$age_override"; age_trace="$age_override"
+  fi
+
+  # Enumerate per category
+  local -a candidates=()
+  local f
+  if [ -d "$root/state/markers/verify" ]; then
+    while IFS= read -r -d '' f; do candidates+=("$f"); done \
+      < <(find "$root/state/markers/verify" -type f -name '*.marker' -mtime +"$age_marker" -print0 2>/dev/null)
+  fi
+  if [ -d "$root/.playwright-mcp" ]; then
+    while IFS= read -r -d '' f; do candidates+=("$f"); done \
+      < <(find "$root/.playwright-mcp" -type f \( -name '*.png' -o -name '*.yaml' \) -mtime +"$age_screenshot" -print0 2>/dev/null)
+  fi
+  if [ -d "$root/docs/sdlc-traces" ]; then
+    while IFS= read -r -d '' f; do candidates+=("$f"); done \
+      < <(find "$root/docs/sdlc-traces" -type f -name '*.log' -mtime +"$age_trace" -print0 2>/dev/null)
+  fi
+
+  # Safety-list filter
+  local -a survivors=()
+  for f in ${candidates[@]+"${candidates[@]}"}; do
+    local base rel
+    rel="${f#"$root"/}"
+    base="$(basename "$f")"
+    case "$rel" in
+      .claude/CHECKPOINT.md|.claude/SESSION_LOCK|.claude/LAST_SAVE) continue ;;
+    esac
+    if [ -n "$cur_slug" ] && [ "$base" = "feature-${cur_slug}.marker" ]; then continue; fi
+    if git -C "$root" ls-files --error-unmatch "$rel" >/dev/null 2>&1; then continue; fi
+    survivors+=("$f")
+  done
+
+  local n=${#survivors[@]}
+
+  # Refusal thresholds (Hoare precondition)
+  if [ "$n" -gt 100 ]; then
+    echo "Refusing sweep — candidate count $n exceeds safe threshold (100). Inspect clean-targets table before override." >&2
+    return 1
+  fi
+  local total_bytes=0 sz
+  for f in ${survivors[@]+"${survivors[@]}"}; do
+    sz=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+    total_bytes=$((total_bytes + ${sz:-0}))
+  done
+  if [ "$total_bytes" -gt 52428800 ]; then
+    echo "Refusing sweep — total size ${total_bytes} bytes exceeds safe threshold (50 MB)." >&2
+    return 1
+  fi
+
+  if [ "$n" -eq 0 ]; then
+    echo "Sweeping stale files... nothing to clean."
+    return 0
+  fi
+
+  local kb=$((total_bytes / 1024))
+  if [ "$delete" -eq 0 ]; then
+    echo "Sweeping stale files... Would remove $n files (${kb} KB)"
+    return 0
+  fi
+
+  local removed=0
+  for f in "${survivors[@]}"; do
+    if rm -f "$f" 2>/dev/null; then
+      removed=$((removed + 1))
+    else
+      echo "Removed $removed of $n before error at $f" >&2
+      return 2
+    fi
+  done
+  echo "Removed $removed files (${kb} KB)"
+  return 0
+}

package/dist/lite/lib/code-comment-discipline.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# tier: lite
+# code-comment-discipline.sh — classifier lib for header comment blocks
+# in bash source files.
+#
+# Answers per file: does the header comment block carry bassclef-internal
+# jargon per standards/bassclef-internal-jargon.md BLOCK-tier terms? Returns
+# a count + list of hits.
+#
+# Sister to lib/output-discipline.sh (goal 25a) — one classifies SKILL/rule
+# body prose for /kiss dispatch presence; this one classifies bash header
+# comments for jargon presence. Same Ousterhout deep-module shape.
+#
+# Per bassclef-upstream#859 Iteration C goal 25b WU-5. Bash 3.2+ compatible.
+#
+# Usage — sourced by /audit-code-comment-discipline skill:
+#   source lib/code-comment-discipline.sh
+#   extract_header_comments <file>              # prints header comment lines
+#   count_jargon_hits <file>                    # prints hit count to stdout
+#   list_jargon_hits <file>                     # prints one line per hit "term|line#"
+#   walk_code_files <type>                      # prints one path per line
+#   load_block_terms                            # loads BLOCK terms into a global var
+
+set -o pipefail
+
+# === Global: BLOCK terms loaded from standards/bassclef-internal-jargon.md ===
+# Populated on demand via load_block_terms. Bash 3.2 has no associative arrays;
+# a newline-separated string works fine here.
+CCD_BLOCK_TERMS=""
+
+# === Load BLOCK terms from the wordlist ===
+# Reads the wordlist table + extracts the term column for BLOCK-tier rows.
+# Skips ADVISE + ALLOW + BLOCK-title tiers. Cached after first load.
+load_block_terms() {
+  [ -n "$CCD_BLOCK_TERMS" ] && return 0
+
+  local wordlist="${CCD_WORDLIST:-standards/bassclef-internal-jargon.md}"
+  [ ! -f "$wordlist" ] && return 1
+
+  # Table row shape: | term | plain | TIER |
+  # Grep BLOCK rows only (exclude BLOCK-title); extract first column between pipes.
+  CCD_BLOCK_TERMS=$(grep -E '^\|.*\|.*\|[[:space:]]*BLOCK[[:space:]]*\|' "$wordlist" 2>/dev/null \
+    | awk -F '|' '{gsub(/^[[:space:]]+|[[:space:]]+$/, "", $2); print $2}' \
+    | grep -v '^$')
+  return 0
+}
+
+# === extract_header_comments — print header comment lines ===
+# Header block = leading `#` comment lines from top of file, skipping the
+# shebang, until the first blank line OR the first non-comment/non-blank line.
+# Returns 0 always.
+extract_header_comments() {
+  local file="$1"
+  [ ! -f "$file" ] && return 0
+
+  awk '
+    NR == 1 && /^#!/ { next }             # skip shebang
+    /^#/ { print; next }                  # keep comment lines
+    /^[[:space:]]*$/ { exit }             # blank line ends header block
+    { exit }                              # any other line ends header
+  ' "$file"
+}
+
+# === count_jargon_hits — count BLOCK-term hits in header comment ===
+# Prints an integer to stdout. Exit 0 always.
+count_jargon_hits() {
+  local file="$1"
+  [ ! -f "$file" ] && { echo 0; return 0; }
+
+  load_block_terms
+  [ -z "$CCD_BLOCK_TERMS" ] && { echo 0; return 0; }
+
+  local header
+  header=$(extract_header_comments "$file")
+  [ -z "$header" ] && { echo 0; return 0; }
+
+  local count=0
+  local term
+  # Iterate over BLOCK terms; count case-insensitive substring matches.
+  while IFS= read -r term; do
+    [ -z "$term" ] && continue
+    # Skip very long descriptive rows (they carry commentary in the wordlist).
+    [ "${#term}" -gt 40 ] && continue
+    if echo "$header" | grep -qiF -- "$term"; then
+      count=$((count + 1))
+    fi
+  done <<< "$CCD_BLOCK_TERMS"
+
+  echo "$count"
+  return 0
+}
+
+# === list_jargon_hits — one line per hit ===
+# Format: "term|first-line-in-header-where-it-appears"
+# Prints nothing when clean. Exit 0 always.
+list_jargon_hits() {
+  local file="$1"
+  [ ! -f "$file" ] && return 0
+
+  load_block_terms
+  [ -z "$CCD_BLOCK_TERMS" ] && return 0
+
+  local header
+  header=$(extract_header_comments "$file")
+  [ -z "$header" ] && return 0
+
+  local term line
+  while IFS= read -r term; do
+    [ -z "$term" ] && continue
+    [ "${#term}" -gt 40 ] && continue
+    line=$(echo "$header" | grep -inF -- "$term" | head -1)
+    [ -n "$line" ] && echo "${term}|${line}"
+  done <<< "$CCD_BLOCK_TERMS"
+
+  return 0
+}
+
+# === walk_code_files — enumerate bash source files ===
+# Types: hooks | scripts | libs | all. Prints one path per line.
+walk_code_files() {
+  local type="$1"
+  local root="${2:-.}"
+
+  case "$type" in
+    hooks|hook)
+      find "$root/.claude/hooks" -maxdepth 1 -name "*.sh" -type f 2>/dev/null | sort
+      ;;
+    scripts|script)
+      find "$root/scripts" -maxdepth 1 -name "*.sh" -type f 2>/dev/null | sort
+      ;;
+    libs|lib)
+      find "$root/lib" -maxdepth 1 -name "*.sh" -type f 2>/dev/null | sort
+      ;;
+    all)
+      walk_code_files hooks "$root"
+      walk_code_files scripts "$root"
+      walk_code_files libs "$root"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+  return 0
+}