@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/standards/skill-output-discipline.md

@@ -1,90 +0,0 @@
----
-tier: lite
-standard: skill-output-discipline
-title: Skill output discipline — dispatch /kiss on operator-facing prose before returning
-authoring_luminaries:
-  primary:
-    - john-ousterhout       # deep module — one contract, many call sites
-    - saltzer-schroeder     # complete mediation — every output surface passes /kiss
-  supporting:
-    - alan-cooper           # persona-driven — Sam skims, Louis copies, Morgan inspects
-    - don-norman            # signifier — the "## Output discipline" heading names the contract
-    - michael-nygard        # stability — cosine gate pins post-cure behavior
-version: 1
-supersedes: none
-verification_status: accepted
-description: Every skill that returns operator-facing prose runs /kiss words --rewrite on the full output before returning.
----
-
-# Skill output discipline
-
-Every skill that returns operator-facing prose runs `/kiss words --rewrite` on the full output before returning. This standard names the contract. Each skill body carries a 3-line pointer to this file, not the full contract.
-
-## The contract
-
-Before returning any operator-facing text from a skill (opener, tables, cards, findings, status, closing prose):
-
-1. Dispatch `/kiss words --rewrite` on the full rendered draft. Not just the opener. Not an inline block-term scan. Actual skill dispatch. The two-flag form runs vocabulary substitution AND six heuristic checks — passive voice, hyphen words, long sentences, non-SVO openers, noun stacks, adverb density.
-2. Apply the rewrite. When `/kiss` returns no changes, accept the pass.
-3. Cite the dispatched skill inline per `.claude/rules/operator-facing-prose.md` Rule 3.
-4. Return the response.
-
-`/kiss` reads `standards/bassclef-internal-jargon.md` per bassclef#907 as the single source of truth for BLOCK + ADVISE + ADVISE-PHRASE terms. The `--rewrite` heuristics live at `lib/rewrite-check.sh` and are grounded in UK ONS Style Guide + Nielsen Norman Group Plain Language + US Federal Plain Language Guidelines + Hemingway Editor. Heuristics surface candidates for review; they do not block.
-
-**Writing-craft anchor.** The full craft rules live at `standards/ogilvy-writing-rules.md` — Ogilvy's 10 rules plus Roman + Raphaelson's principles. `/kiss words` covers vocabulary substitution. `/ogilvy-writing-audit` covers the craft-audit. Skills producing operator-facing prose benefit from both — kiss for words, ogilvy-audit for shape.
-
-## What counts as operator-facing prose
-
-- Skill output the operator reads on screen (opener, tables, cards, recommendations)
-- Findings tables and audit results
-- Status updates between phases
-- Closing prose (recommendations, confirm-to-proceed, next-step lines)
-
-Skill output that is machine-parsed only (JSON, CSV, structured markers) does not count. Skills that emit only machine output declare `no_operator_output: true` in frontmatter.
-
-## The body snippet each skill carries
-
-Every skill that emits operator-facing prose appends this 3-line section to its body:
-
-```markdown
-## Output discipline
-
-Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.
-```
-
-The snippet grades around 5.0 on Flesch-Kincaid. That passes the grade gate at `.claude/hooks/skill-body-grade-gate.sh` (target 80% at grade 8-9).
-
-The classifier in `lib/output-discipline.sh` `has_kiss_dispatch` matches either the full canonical form or the pointer sentence, in single-flag OR two-flag shape. Skills using the two-flag pointer (`/kiss words --rewrite`) count as PRESENT. Skills still using the single-flag pointer (`/kiss words`) also count as PRESENT during the grace window per ADR-031.
-
-## Why the pointer, not the full contract
-
-Sam skims the skill body. He reads the section heading `## Output discipline` and knows a contract exists. He can move on.
-
-Louis writes his own skills for the community. He copies the 3-line snippet verbatim. He does not have to internalize the full contract.
-
-Morgan reads for over-claim. He clicks through to this standards file. He sees one source of truth, not 90 duplicated contracts scattered across skill bodies.
-
-The pattern follows Ousterhout's deep module — small interface (3 lines in each skill), large implementation (this standard) hidden behind it.
-
-## Opt-out
-
-Skills whose only output is machine-parsed (JSON, structured markers, exit codes) declare `no_operator_output: true` in frontmatter. The `has_opt_out` classifier reads this and returns `OPT_OUT`.
-
-## Sources read
-
-- `docs/canvases/2026-07-25-substrate-output-discipline.md` — parent canvas naming the pattern
-- `lib/output-discipline.sh` L36-49 — the classifier this contract feeds
-- `.claude/rules/operator-facing-prose.md` Rule 3 — inline citation discipline
-- `.claude/luminaries/john-ousterhout.md` — deep module framing
-- `docs/personas/sam.md`, `docs/personas/2026-07-12-bet11c-louis.md`, `docs/personas/morgan.md` — persona lens for the design
-
-## Refs
-
-- bassclef-upstream#859 (parent epic — substrate-wide output discipline)
-- bassclef-upstream#858 (pilot — /longrun + /sprint dispatch pattern)
-- Canvas `docs/canvases/2026-07-25-substrate-output-discipline.md`
-- Standard `standards/bassclef-internal-jargon.md` (SSOT for /kiss vocabulary)
-
-## Retirement condition
-
-This standard retires only if `/kiss` itself retires or if all skill output moves to a machine-parsed shape. Until then, the 3-line snippet is the interface every skill body carries.

package/substrate/standards/state-spine-contract.md

@@ -1,255 +0,0 @@
----
-tier: lite
-description: "The interface contract for lib/state.sh — the typed accessor library over bassclef's state spine."
----
-
-# State Spine Accessor Contract
-
-The interface contract for `lib/state.sh` — the typed accessor library
-over bassclef's state spine. Repository pattern (Fowler PoEAA): hides
-storage backend (JSON-on-git for v0; cxdb for opt-in adopters per
-bassclef#300) from consumers via a stable accessor surface.
-
-This standard is the contract. The implementation is `lib/state.sh`.
-Adapter discipline (per canvas Stage 3 §"Adapter discipline") preserves
-the swap surface — when cxdb adoption ships, the implementation changes
-but this contract does not.
-
-## Sources read
-
-- `docs/iteration-bets/2026-04-27-state-spine-v0.md` §"WU-2 Typed accessor library" — procedure + acceptance
-- `strategy/canvases/2026-04-26-state-spine.md` v4 — accessor discipline (replay-determinism); pattern-set (Repository/Facade); cxdb-adapter exit criteria
-- `architecture/decisions/ADR-015-state-schema-format.md` — JSON Schema only for v0 (no Zod runtime)
-- `standards/state-spine.md` — entity catalog (17 v0 + Persona); storage shapes (3 — A/B/C); replay-determinism rule; write-once-immutability rule
-- All 18 v0 entity schemas in `standards/state-spine/schemas/` — define what each accessor returns
-- `.claude/luminaries/martin-fowler.md` — Repository pattern + Strangler Fig
-- `.claude/rules/diagnosis.md` — error-shape conventions (return non-zero + stderr message; never silent failure)
-
-## What I'm NOT reading (with reason)
-
-- cxdb / Dolt vendor docs — out of v0 scope (Track B)
-- `extract-session-telemetry.sh` line-by-line — WU-5's pre-read; this contract defines the surface telemetry will consume, not telemetry itself
-
-## Naming convention
-
-```
-state_<entity>_<verb>[_<modifier>]
-```
-
-- **entity** — kebab-case entity name from state-spine.md (e.g., `whereami`, `iteration_bet`, `deferred_action`, `chronicle`, `marker`)
-- **verb** — operation (bassclef set below)
-- **modifier** — optional qualifier for special-purpose accessors
-
-Examples:
-- `state_whereami_get` — get the singleton
-- `state_iteration_bet_list` — list all bets
-- `state_marker_count` — count markers (with optional filter args)
-- `state_chronicle_gate_evidence` — special-purpose: extract gates_fired from a chronicle
-- `state_deferred_action_pending` — special-purpose: list pending actions matching capabilities
-
-## Verb vocabulary
-
-Stable set. Extend via this contract (with a paired schema-side rationale).
-
-| Verb | Semantics | Allowed for |
-|---|---|---|
-| `get` | Single entity by id; returns JSON to stdout, 1 to stderr if not found | All entities |
-| `list` | Collection (optional filter args); returns JSON array to stdout (empty array `[]` if none) | All entities |
-| `count` | Counter (optional filter args); returns integer to stdout | All entities |
-| `add` | Append a new entity; takes JSON on stdin, writes file, returns id to stdout | Write-many entities (Marker, Chronicle, Decomposition, InputArtifact, Session, Gate, InboxWorkItem, TemplateInstance, DeferredAction) |
-| `set` | Update field on singleton; takes field + value, validates against schema, writes | Singletons only (Whereami, SubstrateConfig, PreviewState, BassclefPlatform) |
-| `update_status` | Change status field; validates new value against entity's status enum | Mutable-status entities (IterationBet, Step, InboxWorkItem, DeferredAction) |
-| `render` | Generate operator-readable markdown from JSON authoritative source | Singletons (Whereami, SubstrateConfig, PreviewState) |
-
-Forbidden verbs: any mutation on Markers, Chronicles, Discoveries,
-Sessions (write-once-immutable per Helland — see canvas §"Accessor
-discipline"). Updates produce NEW records; readers consider the latest
-non-superseded record per business-key.
-
-## Return semantics
-
-| Outcome | Stdout | Stderr | Exit code |
-|---|---|---|---|
-| Success (single entity) | JSON object | (empty) | 0 |
-| Success (list) | JSON array (possibly empty) | (empty) | 0 |
-| Success (count) | integer | (empty) | 0 |
-| Success (add) | new id | (empty) | 0 |
-| Not found | (empty) | (empty) | 1 |
-| Invalid input | (empty) | error message | 2 |
-| Schema validation failed | (empty) | jq/ajv error | 3 |
-| File system error | (empty) | error message | 4 |
-| Unsupported entity / verb | (empty) | error message | 5 |
-
-Consumers check exit code; non-zero is failure. Never silent — error
-messages always go to stderr per `.claude/rules/diagnosis.md`
-("Step 0 — Reproduce" requires the failure to surface).
-
-## Replay-determinism rule (canvas v4 SWF mining)
-
-Counters and computed state derived from history on every call. **Never
-cache derived values as side state.**
-
-Concretely:
-- `state_marker_count [category] [since-N-sessions]` reads the Marker
-  collection + computes; no `latest_count` field stored anywhere
-- `state_chronicle_gate_evidence <id>` derives from session's marker
-  history at chronicle write time, not maintained out-of-band
-- `state_whereami_recompute` regenerates the Whereami singleton from
-  collection state; the JSON sidecar at `docs/whereami.json` is a
-  cache, not authority
-
-This is the bassclef analog of SWF's "decider must be idempotent on
-replay." Same input history → same output, deterministically. Failing
-at this is what produced bassclef#296 (compliance counter floor-lift).
-
-## Write-once-immutability rule (Helland)
-
-Markers, Chronicles, Discoveries, Sessions are write-once. Once
-committed:
-- Filename never changes (UUID for Markers; ID-based for others)
-- Body content never changes
-- Updates produce NEW records that supersede the prior (via
-  `supersedes` field per the Marker schema)
-
-Accessors that mutate (`add`) write atomic — file lands or fails. No
-partial writes. Use temp-file + rename pattern.
-
-Accessors that don't mutate (`get`, `list`, `count`, `update_status`)
-operate on whatever's on disk; consumers responsible for any
-serializability they need (out of v0 scope; cxdb upgrade addresses for
-concurrent fanout).
-
-## Storage-shape extraction (per state-spine.md §"Storage format")
-
-The accessor handles all three on-disk shapes via entity-type-aware
-extraction:
-
-### Shape A entities (singleton JSON authoritative + markdown rendered)
-
-```bash
-state_whereami_get() { cat docs/whereami.json; }
-state_whereami_set <field> <value>  # jq update + atomic rename
-state_whereami_render               # JSON → markdown (with auto-generated banner)
-```
-
-### Shape B entities (markdown + YAML frontmatter + body)
-
-```bash
-state_iteration_bet_get <slug> {
-  # Extract YAML frontmatter, convert to JSON
-  awk '/^---$/{c++; next} c==1' docs/iteration-bets/$slug.md | yq2json
-}
-```
-
-`yq2json` is implemented as `python3 -c "import sys,yaml,json; print(json.dumps(yaml.safe_load(sys.stdin), default=str))"` (yaml + json stdlib, available everywhere).
-
-### Shape C entities (pure JSON)
-
-```bash
-state_marker_get <uuid> {
-  # Find by UUID across category dirs
-  find state/markers -name "${uuid}.json" -type f -print -quit | xargs cat
-}
-```
-
-### Shape D entities (pure YAML at sibling-repo root) — added bassclef#462
-
-```bash
-state_platform_get [dot.path.key] {
-  # Resolves file via BASSCLEF_PLATFORM_CONFIG_PATH env or default
-  # ~/src/sunj-labs/platform-config/bassclef-platform.yml; converts
-  # YAML to JSON; if a key is given, jq-walks the path.
-  python3 -c "import yaml,json; print(json.dumps(yaml.safe_load(open('$path'))))" \
-    | jq -r --arg key "$key" 'getpath($key | split("."))'
-}
-state_platform_path  # returns the resolved file path (no read)
-```
-
-## Special-purpose accessors (v0 hot-path consumers)
-
-Beyond generic verbs, the following exist for known v0 consumers:
-
-| Accessor | Returns | Consumer |
-|---|---|---|
-| `state_marker_count [category] [since-days]` | int | `extract-session-telemetry.sh` (WU-5); `40-gate-compliance.sh` (WU-6). v0 since-days = mtime-based; v1 will redefine as session-boundary-mapped per canvas v4 SWF mining. Accepts both `.json` (spine) and `.marker` (legacy verify-markers) extensions. |
-| `state_chronicle_list [--recent N]` | newline-separated chronicle IDs (lex order) | `extract-session-telemetry.sh` (WU-5); `/sprint`, `/chronicle` (WU-7). Tries `chronicle/` then `docs/chronicle/`. |
-| `state_chronicle_gate_evidence <id>` | JSON of `gates_fired` frontmatter array | `extract-session-telemetry.sh` (WU-5) — frontmatter-only. Legacy chronicles with body-table Gate Evidence return `[]`; consumers may parse markdown body directly per `accessor-library-discipline.md` §"What this rule allows". |
-| `state_session_recent <N>` | JSON array of recent N sessions | `/sprint`, `/chronicle` (WU-7) |
-| `state_step_for_branch <branch-name>` | JSON of Step | status checks; `/longrun checkpoint` |
-| `state_deferred_action_pending [requires-capability...]` | JSON array of resolvable entries (capability-filtered) | `60-deferred-actions.sh` (WU-6) |
-| `state_deferred_action_list [pending\|completed\|all]` | JSON array of all entries in scope (no capability filter) | `/state` skill (WU-8); ad-hoc inspection |
-| `state_iteration_bet_active` | JSON of currently-active bet (or empty if none) | `/sprint` (WU-7) |
-| `state_iteration_bet_list` | JSON array of all bets (lexicographic order) | `/state` skill (WU-8) |
-| `state_reference_get <type> <id>` | JSON of referenced entity (resolves typed cross-refs) | validator (WU-3); render (WU-7) |
-| `state_reference_check <type> <id>` | exit 0 if exists, 1 if dangling | validator (WU-3) |
-| `state_validate <path>` | empty stdout on success; BLOCK message on stderr if schema violation | `/state` skill (WU-8); ad-hoc operator validation |
-| `state_roadmap_get <slug>` | JSON of roadmap frontmatter | `/sprint`, `/longrun` first-turn orientation (bassclef#337 WU-4) |
-| `state_roadmap_next_pending <slug>` | JSON of next claimable WU (depends_on satisfied + status=pending) | claim_wu's default arg path |
-| `state_platform_get [dot.path]` | JSON object (whole file) or scalar (when dot-path given) | `/provision-deploy-host` (bassclef#457), `/secrets-bootstrap` (bassclef#461), `/scaffold-stack` (bassclef#460), `/bind-subdomain` (existing — V2 reads zone via this rather than per-repo substrate.config); reads sibling-repo `bassclef-platform.yml` |
-| `state_platform_path` | filesystem path string | tooling that displays where state_platform_get reads from without reading |
-| `state_roadmap_claim_wu <slug> [wu-slug] [session-id]` | JSON of claimed WU; advances `last_event` with `task-claimed` (bassclef#349 tail-1) | distributed agent coordination — atomic claim via flock |
-| `state_roadmap_release_wu <slug> <wu-slug> [event] [refs-json]` | JSON of new `last_event`; advances `last_event` with completion | distributed agent coordination — completion |
-| `state_roadmap_abandon_wu <slug> <wu-slug> [reason] [--terminal]` | JSON of new `last_event`; advances `last_event` with `task-abandoned` (bassclef#349 tail-2) | scope-change exit path; default returns to pending, `--terminal` marks abandoned |
-| `state_roadmap_add_task <slug> <wu-slug> <issue> <wu-id> <title> [depends_on-json]` | JSON of new task; advances `last_event` with `task-added` (bassclef#349 tail-3) | proper accessor entry point for populating roadmap task list — replaces hand-edits per `accessor-library-discipline.md` |
-
-## Adapter discipline — preserved swap surface
-
-Per canvas Stage 3 §"Adapter discipline" (7 exit criteria):
-
-1. **Accessor library is the ONLY consumer of storage backend APIs.**
-   No skill/hook/rule/script invokes `cat docs/whereami.json` directly
-   when an accessor exists. Enforced via `accessor-library-discipline.md`
-   rule (paired with this contract; ships in same PR as `lib/state.sh`).
-2. **Accessor surface exposes only operations expressible in BOTH
-   backends** (JSON-on-git AND cxdb). No JSON-on-git-specific features
-   (e.g., `find`-based glob queries, jq paths in public surface) leak
-   into the contract. cxdb-adopter would re-implement these accessors
-   against Turn DAG + Blob CAS; surface stays unchanged.
-3. **JSON spine remains writable from cxdb.** When cxdb adoption ships,
-   `state_marker_add` etc. continue to write JSON files (cxdb is a
-   read-side projection); JSON files in git are still authoritative.
-4. **Contract is schema-first, not implementation-first.** Entity
-   definitions live in `standards/state-spine/schemas/`. cxdb's Type
-   Registry would be loaded FROM bassclef's schema, not derived.
-5. **A working cxdb fork is maintained** when adopted. (Out of v0 scope.)
-6. **Migration tooling (cxdb → Dolt) is designable from the entity
-   model.** (Out of v0 scope; ADR bassclef#300 placeholder.)
-7. **Dolt-as-fallback design is sketched in the cxdb ADR.** (Out of
-   v0 scope.)
-
-For v0: criteria 1-4 apply now. They constrain `lib/state.sh` design
-even though only criterion 1 is enforceable in v0 (the rule).
-
-## Test coverage requirement
-
-≥95% test coverage on `lib/state.sh` per step-2 acceptance. Test scaffold
-at `scripts/tests/state.test.sh` per existing bassclef bash-test
-pattern (`scripts/tests/bind-subdomain.test.sh`).
-
-Each accessor has at minimum:
-- Happy path (successful return)
-- Not-found path (exit 1, empty stdout)
-- Invalid-input path (exit 2, stderr message)
-- Schema-validation path where applicable (exit 3)
-
-## Versioning
-
-Accessor surface versioned via this standard. Breaking changes
-(removing accessors, changing return shapes, changing exit codes) are
-v1 changes — ship as `state_v1.sh` alongside `state.sh` during
-deprecation window per Fowler expand-and-contract.
-
-Adding new accessors is non-breaking; can land in v0 patches.
-
-## Relationship to other standards
-
-- `standards/state-spine.md` — entity catalog + storage shapes; this
-  contract operates on
-- `standards/branch-stacking.md` — Stack entity uses retarget protocol;
-  WU-2 PR will need this on merge
-- `.claude/rules/state-schema-validation.md` (paired with WU-3) — write-time
-  validation; this contract's `add`/`set`/`update_status` accessors invoke
-  the validator before writing
-- `.claude/rules/accessor-library-discipline.md` (paired with this
-  standard) — enforces "no skill/hook/rule reads state directly; all
-  access goes through `lib/state.sh`"