@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/skills/state/SKILL.md

@@ -0,0 +1,204 @@
+---
+tier: lite
+name: state
+description: "Inspect bassclef's saved state \u2014 get, list, count, or validate entries via lib/state.sh. Read-only. Writes happen through dedicated skills like /session-end and /chronicle."
+problem: "Bassclef's saved state lives in state markers and JSON files. Read-only access is scattered."
+value: "Inspects bassclef's saved state \u2014 get or list or count or validate entries via lib/state.sh."
+inputs: [Verb — get or list or count or validate, Entity type and optional slug]
+outputs: [State entry values, List of entries per type, Count, Validation report]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /state — Ad-hoc state inspection
+
+Operator-facing surface over `lib/state.sh` accessors. Answers: "what
+does the spine show right now for entity X?" without spawning a heavier
+skill. Read-only.
+
+The skill is a thin dispatcher to `scripts/state.sh` (the CLI wrapper)
+and `lib/state.sh` (the typed accessor library). Mutations live
+elsewhere: `/session-end` writes whereami; `/chronicle` writes
+chronicles; deferred-actions resolve via `git mv` per their own
+protocol. This skill never writes.
+
+## When to invoke
+
+- Mid-session orientation: "what goal is active?" → `/state get iteration_bet active`
+- Spot-check: "did the deferred-actions list rot?" → `/state list deferred_action`
+- Audit: "how many gate markers fired?" → `/state count marker`
+- Manual validation: "does this artifact validate against its schema?" → `/state validate <path>`
+- New-skill scaffolding: "what's the shape of a Chronicle entity?" → `/state get chronicle <id>`
+
+## What this skill is NOT
+
+| Skill | Altitude | Output |
+|-------|----------|--------|
+| `/state` | **Spine inspection** | Typed entity data (read-only) |
+| `/whereami` | Project state snapshot | Phase + iteration + freshness |
+| `/sprint` | Ticket/scope level | Open issues, proposed next sprint |
+| `/substrate-check` | Wiring validation | Symlinks, hooks, CLIs, CLAUDE.md health |
+
+`/whereami` reads ONE entity (the singleton); `/state get whereami`
+delivers the same data through the spine. Use `/whereami` for the
+rendered narrative view, `/state` for the typed JSON.
+
+## Procedure
+
+The skill dispatches to `scripts/state.sh <subcommand> [args]` which
+sources `lib/state.sh` and calls the appropriate `state_*` accessor.
+Output is piped through `jq .` for pretty-printing JSON results;
+scalars (counts) print raw.
+
+### `/state get <entity> [<id>]`
+
+Returns a single entity. For singletons (whereami, substrate-config),
+no id is required. For collections (iteration_bet, marker, chronicle,
+deferred_action, session, stack, roadmap, decomposition, persona, adr),
+`<id>` is the slug/uuid/identifier.
+
+```bash
+bash scripts/state.sh get whereami
+bash scripts/state.sh get iteration_bet 2026-04-27-state-spine-v0
+bash scripts/state.sh get iteration_bet active   # special: active goal
+bash scripts/state.sh get marker <uuid>
+bash scripts/state.sh get chronicle 2026-04-27b-spine-v0-WU-1
+```
+
+Exit code 0 = found; exit 1 = not found (empty stdout); exit 2 = bad
+args (stderr message).
+
+### `/state list <entity> [<filter>]`
+
+Returns a JSON array of entities. Empty array `[]` if none found.
+
+```bash
+bash scripts/state.sh list iteration_bet
+bash scripts/state.sh list deferred_action            # default: pending
+bash scripts/state.sh list deferred_action completed  # completed only
+bash scripts/state.sh list deferred_action all        # both
+```
+
+### `/state count <entity> [<filter>]`
+
+Returns an integer count.
+
+```bash
+bash scripts/state.sh count marker                   # all markers
+bash scripts/state.sh count marker temperance        # category filter
+bash scripts/state.sh count iteration_bet            # all bets
+bash scripts/state.sh count deferred_action pending  # pending only
+```
+
+### `/state validate <path>`
+
+Validates a state-spine file against its entity schema by invoking
+`.claude/hooks/state-validate.sh` with a synthesized PreToolUse event.
+
+```bash
+bash scripts/state.sh validate docs/whereami.json
+bash scripts/state.sh validate docs/iteration-bets/2026-04-27-state-spine-v0.md
+bash scripts/state.sh validate chronicle/2026-04-27b-spine-v0-WU-1.md
+```
+
+Exit code 0 = validates clean (or legacy pass-through); 3 = schema
+violation (structured BLOCK on stderr); 4 = file or hook missing.
+
+### `/state help`
+
+Lists supported entity / verb pairs and points at the contract:
+
+```bash
+bash scripts/state.sh help
+```
+
+## Supported entity / verb matrix (v0)
+
+| Entity | get | list | count | validate (via path) |
+|---|---|---|---|---|
+| whereami (singleton) | ✓ | n/a | n/a | ✓ (`docs/whereami.json`) |
+| iteration_bet | ✓ (incl. `active`) | ✓ | derived from list | ✓ |
+| stack | via reference resolver | — | — | ✓ |
+| chronicle | via reference resolver | — | — | ✓ |
+| marker | ✓ | — | ✓ (with category filter) | ✓ |
+| deferred_action | via list filter | ✓ (pending/completed/all) | derived from list | ✓ |
+| session | via reference resolver | — | — | ✓ |
+| decomposition | via reference resolver | — | — | ✓ |
+| persona | via reference resolver | — | — | ✓ |
+| roadmap | via reference resolver | — | — | ✓ |
+| adr | via reference resolver | — | — | n/a (markdown without frontmatter) |
+| discovery | via reference resolver | — | — | ✓ |
+
+`reference` is the universal resolver: `bash scripts/state.sh get reference <type> <id>`
+returns whatever entity type is named. This covers entity types where
+a dedicated `_get` accessor is not yet implemented.
+
+## What `/state` does NOT support (deferred)
+
+- **Mutation verbs** (`add`, `set`, `update_status`, `render`) — those
+  go through dedicated skills or accessor calls in scripts; exposing
+  them via `/state` would create a second mutation surface contradicting
+  this skill's read-only contract
+- **Per-entity `list` for entities without dedicated accessors**
+  (chronicle, session, stack, etc.) — defer to spine v1 once usage
+  signal motivates per-entity list accessors; for now `find` + the
+  reference resolver covers the rare case
+- **Filter expressions beyond category/scope** — full query language
+  is out of v0 scope; if N consumers need it, file a /promote
+
+## Rules
+
+- **Read-only.** This skill never writes. If an operator asks the agent
+  to mutate state via `/state`, redirect to the appropriate dedicated
+  skill (`/session-end` for whereami, `/chronicle` for chronicles, etc.).
+- **No inventing accessors.** If the requested verb-entity pair isn't
+  in the matrix above, say so and point to the reference resolver or
+  to filing a /promote for the gap. Do not silently grep around the
+  spine.
+- **Schema is the contract.** When `/state validate` BLOCKs, the BLOCK
+  message names the schema field that failed; report it verbatim. Do
+  not paraphrase or downgrade the failure.
+- **Replay-determinism preserved.** All `state_*_count` accessors derive
+  from history on every call (no cached state). The skill MUST NOT add
+  caching layers between operator input and accessor output.
+
+## Skipping / Aborting
+
+- If the entity directory doesn't exist (e.g., fresh repo with no
+  iteration-bets/), the accessor returns empty array `[]` or count 0.
+  Report cleanly; do not invent state.
+- If the accessor is not yet implemented for the requested verb-entity
+  pair, return a clear error pointing at the matrix above.
+- If `state-validate.sh` hook is missing or not executable, `/state
+  validate` returns exit 4; report that the spine v0 wiring is
+  incomplete and point at the bassclef-sync hook.
+
+## Relationship to other skills + standards
+
+- `lib/state.sh` — the typed accessor library this skill dispatches to
+- `scripts/state.sh` — the CLI wrapper this skill invokes (argv → accessor)
+- `standards/state-spine.md` — entity catalog + storage shapes
+- `standards/state-spine-contract.md` — accessor surface (what verbs +
+  modifiers exist)
+- `.claude/rules/accessor-library-discipline.md` — paired discipline rule;
+  this skill IS one of the consumers that goes through the accessor
+- `.claude/hooks/state-validate.sh` — wired PreToolUse hook; `/state
+  validate <path>` invokes it directly
+- `/whereami` — uses Whereami singleton; `/state` exposes the same data
+  as typed JSON
+- `/sprint` — composes whereami + iteration_bet; `/state` exposes the
+  same primitives at a lower altitude
+
+## Enforcement
+
+Methodology-level. The skill is registered via bassclef-sync symlink
+(automatic per substrate distribution). No hook enforcement added by
+this skill — read-only inspection requires no gate.
+
+The reserved-skill-names check passes: `state` is NOT on the harness
+built-in list per `standards/reserved-skill-names.md` (verified during
+spine v0 goal shape).
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/substrate-check/SKILL.md

@@ -0,0 +1,218 @@
+---
+tier: lite
+name: substrate-check
+description: "Check the bassclef wiring in this repo. Validates files, skills, hooks, CLIs, git remote, CLAUDE.md, and session dirs. Use before a fresh session. Use after a new setup. Renamed from /self-test on 2026-04-15."
+problem: "Bassclef wiring drifts across environments. Broken files and missing hooks get discovered mid-session."
+value: "Checks the bassclef wiring in this repo. Validates files and hooks and CLIs and git remote."
+inputs: [Optional --verbose flag]
+outputs: [8 check results with PASS/WARN/FAIL, Warnings list, Overall status]
+user_invocable: true
+disable_model_invocation: false
+requires:
+  cli: [git, gh, node, npx]
+  network: true
+---
+
+# Substrate Self-Test
+
+A 30-second check that validates the full substrate chain. Run it before
+a fresh session. Run it after a new setup. Run it when something feels
+broken.
+
+## When to invoke
+
+- Before `/autonomous start` in a new environment
+- After `boot-bassclef.sh` or manual substrate setup
+- When a skill, hook, or substrate file fails unexpectedly
+- As part of `/autonomous dry-run` (automatically)
+
+## Procedure
+
+Run each check in order. Report PASS / WARN / FAIL for each.
+
+### 1. Substrate files
+
+Check that all `.claude/skills/` and `.claude/rules/` entries are present:
+
+Since the 2026-07-29 npm pivot, bassclef ships as file copies. Files land
+in `node_modules/@sunjlabs/bassclef-lite/`. `bassclef-sync` copies from
+that location into the consumer's `.claude/` tree. Dev-mode local checkouts
+may still use symlinks. Both shapes work.
+
+```bash
+# For each substrate file in .claude/skills/ and .claude/rules/
+# Check: does the file exist and is it readable?
+for f in .claude/skills/*/SKILL.md .claude/rules/*.md; do
+  if [ ! -r "$f" ]; then
+    echo "FAIL: missing or unreadable file: $f"
+  fi
+done
+```
+
+- PASS: all substrate files present and readable
+- WARN: untracked files (expected from bassclef-sync, not a problem)
+- FAIL: missing or unreadable files (sync did not complete, or file removed)
+
+### 2. Skills
+
+Validate all SKILL.md files:
+
+```
+For each .claude/skills/*/SKILL.md:
+  - Does it have valid YAML frontmatter? (name, description required)
+  - Is user_invocable set? (informational, not a failure)
+```
+
+- PASS: all skills parse correctly
+- WARN: skill missing optional fields
+- FAIL: skill with missing/broken frontmatter
+
+### 3. Hooks
+
+Check that hooks referenced in settings.json exist and are executable:
+
+```
+Read .claude/settings.json (project) and ~/.claude/settings.json (user)
+For each hook command:
+  - Does the script file exist?
+  - Does it have execute permission?
+  - Is the hook type valid? (PreToolUse, PostToolUse, Stop, etc.)
+```
+
+- PASS: all hooks exist and are executable
+- WARN: hook script exists but not executable (chmod +x needed)
+- FAIL: hook references a script that doesn't exist
+
+### 4. CLIs
+
+Check for required command-line tools:
+
+```
+Required: git, gh, node, npx
+Optional: claude (for headless agent spawning)
+```
+
+For each:
+- PASS: command exists and responds to --version
+- WARN: optional command missing
+- FAIL: required command missing
+
+### 5. Git remote
+
+```
+git remote -v           # can we see origin?
+gh auth status          # is GitHub auth working?
+```
+
+- PASS: remote configured and auth working
+- WARN: auth expired or not configured (push will fail)
+- FAIL: no remote configured
+
+### 6. CLAUDE.md
+
+```
+Does CLAUDE.md exist at project root?
+Does it reference the correct directories?
+Does the skills count match actual .claude/skills/ entries?
+```
+
+- PASS: CLAUDE.md exists and is consistent
+- WARN: skills count mismatch (CLAUDE.md says N, actual is M)
+- FAIL: CLAUDE.md missing
+
+### 7. Session artifact directories
+
+Check that required directories exist (or can be created):
+
+```
+Required:
+  - chronicle/ or docs/chronicle/    (session records)
+  - docs/operator-private/journals/            (journal entry drafts)
+  - docs/sdlc-traces/                (hook trace logs)
+
+Conditional (standard/full level):
+  - docs/iteration-bets/             (iteration goals)
+  - docs/risk-register.md            (risk register — file, not dir)
+```
+
+- PASS: all required directories exist
+- WARN: directory missing but can be created
+- FAIL: parent directory doesn't exist (unusual)
+
+### 7b. Whereami artifact
+
+```
+docs/whereami.md MUST exist and conform to standards/whereami-schema.md.
+Check:
+  - File present
+  - YAML frontmatter `last_updated.at` field exists with ISO-8601 timestamp (legacy `## Last updated` section retired per goal 2026-09-06d Cure 3)
+  - Age of last_updated (days since)
+  - All 8 schema sections present (phase, active iteration, active
+    agents, subsystem phases, gate progress, risk register, last
+    updated, configuration)
+```
+
+- PASS: file present, schema-conformant, age <3 days
+- WARN: schema non-conformance (missing section) OR age 3-7 days
+- FAIL: file missing OR age ≥7 days OR last_updated unparseable
+
+See `.claude/rules/whereami-load-bearing.md` for the freshness policy.
+Fresh consumer repos should scaffold from
+`templates/whereami-template.md`.
+
+### 8. Hook idempotency spot-check
+
+Check for common non-idempotent patterns in hook scripts:
+
+```
+For each hook script:
+  - Does it write a file then immediately check for that file?
+    (SESSION_LOCK write-then-detect pattern)
+  - Does it append without checking if content already exists?
+  - Does it use >> without dedup?
+```
+
+- PASS: no obvious idempotency issues
+- WARN: potential non-idempotent pattern detected (list them)
+- FAIL: (not used — idempotency issues are warnings, not blockers)
+
+## Output format
+
+```
+## Substrate Self-Test Report
+
+**Date**: YYYY-MM-DD
+**Repo**: [repo name]
+**Branch**: [current branch]
+
+| Check | Status | Detail |
+|-------|--------|--------|
+| 1. Substrate files | PASS | 25 skills, 12 rules — all present |
+| 2. Skills | PASS | 25 skills parsed, all valid frontmatter |
+| 3. Hooks | PASS | 5 hooks registered, all executable |
+| 4. CLIs | PASS | git 2.x, gh 2.x, node 22.x, npx 10.x |
+| 5. Git remote | PASS | origin configured, gh auth valid |
+| 6. CLAUDE.md | WARN | Skills table says 23, actual is 25 |
+| 7. Artifact dirs | PASS | All directories present |
+| 8. Hook idempotency | WARN | session-start: writes SESSION_LOCK then detects it |
+
+**Overall: PASS** (2 warnings)
+
+### Warnings
+- CLAUDE.md skills count mismatch: update the skills table
+- session-start hook: SESSION_LOCK write-then-detect pattern may cause
+  false "another session active" warnings on restart
+```
+
+## Rules
+
+- Read-only. Do not create, modify, or delete any files.
+- Report findings clearly. Do not fix issues — just identify them.
+- If the operator wants to fix warnings, they can run the appropriate
+  tool (e.g., update CLAUDE.md, chmod +x a hook script).
+- This skill can be integrated into `/autonomous dry-run` as an
+  additional validation layer.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.