@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/.claude/rules/manual-prod-approval.md

@@ -1,100 +0,0 @@
----
-tier: lite
-globs: [".github/workflows/**/*.yml", ".github/workflows/**/*.yaml"]
-description: Prod deploys require GitHub Environments with required_reviewers — no exceptions
----
-
-# Manual Prod Approval Rule
-
-Every app repo's production deploy MUST gate on GitHub Environments
-with `required_reviewers` configured. Auto-deploy-to-prod on any
-branch push is a rule violation.
-
-## Why
-
-`guardrails.md` already says: "Deploy to production without human
-approval — even in orchestrator-gated mode. This is the hardest
-guardrail. No exceptions."
-
-This rule specifies the **mechanism** for enforcement: GitHub's
-native Environments feature with reviewer requirements, not agent
-discipline. Agents can and will skip softer forms. Infrastructure-
-enforced gates cannot be skipped.
-
-## What satisfies the rule
-
-A deploy workflow with a job referencing a GitHub Environment that
-has `required_reviewers` configured:
-
-```yaml
-jobs:
-  deploy-prod:
-    environment:
-      name: prod   # ← this environment must exist in repo settings
-                   #   with required_reviewers set
-    steps:
-      - ... actual deploy steps
-```
-
-Repo settings at github.com/[owner]/[repo]/settings/environments
-must show:
-- Environment named `prod`
-- Deployment protection rules enabled
-- Required reviewers populated (at least one operator)
-
-## What violates the rule
-
-- `main` branch push auto-deploys to prod without Environment gating
-- Any workflow job deploying to prod without `environment:` field
-- Environment exists but has no required reviewers (empty list = auto-approved)
-- Reviewers are GitHub bots / service accounts (must be human identity)
-
-## Detection
-
-This rule fires when:
-- A new app repo is scaffolded by `/autonomous start` with
-  `deploy_targets.prod` set to a URL
-- `.github/workflows/deploy.yml` is added or modified
-- Pre-commit-gate hook detects workflow changes touching prod deploy steps
-
-## Enforcement
-
-- Pre-commit-gate hook surfaces a warning if deploy workflow
-  touches prod without Environment reference
-- `/substrate-check` skill validates Environment + reviewer configuration
-  when `deploy_targets.prod` is set
-- `/deploy-prod` skill refuses to run if Environment validation
-  fails
-
-## What agents do when rule is violated
-
-Fire BLOCKED: (per `blocked-items.md`):
-- `BLOCKED: prod deploy without approval gate — configure GitHub
-  Environment 'prod' with required_reviewers before proceeding`
-- Resolve (configure via `gh api` or UI) or explicit defer with
-  rationale. Silence is not deferral.
-
-## Setup commands (one-time per repo)
-
-```bash
-# Get your user ID
-USER_ID=$(gh api user --jq '.id')
-
-# Create prod environment with yourself as reviewer
-gh api repos/$OWNER/$REPO/environments/prod --method PUT -f "wait_timer=0" \
-  -f "deployment_branch_policy[protected_branches]=false" \
-  -f "deployment_branch_policy[custom_branch_policies]=true"
-
-# Add required reviewer
-gh api repos/$OWNER/$REPO/environments/prod \
-  --method PUT \
-  -F "reviewers[][type]=User" \
-  -F "reviewers[][id]=$USER_ID"
-```
-
-## Related
-
-- `.claude/rules/guardrails.md` — prod deploy human-approved
-- `standards/deployment-topology.md` — bassclef deploy pattern
-- `standards/substrate-config-schema.md` — `prod_approval_reviewers`
-  field convention

package/substrate/.claude/rules/marker-enrichment-discipline.md

@@ -1,99 +0,0 @@
----
-tier: lite
-description: Gate marker files (under state/markers/temperance/, state/markers/luminary/, state/markers/arc-walk/, state/markers/orientation-gate/, state/markers/roadmap-reconcile-gate/) MUST…
----
-
-# Marker Enrichment Discipline
-
-Gate marker files (under `state/markers/temperance/`, `state/markers/luminary/`, `state/markers/arc-walk/`, `state/markers/orientation-gate/`, `state/markers/roadmap-reconcile-gate/`) MUST carry body content within the same WU or PR that creates them. Touching a marker without body content satisfies the gate's existence check but leaves no audit trail — months later, a reader cannot recover the scope-decision, luminary lens, or thread context that the marker is supposed to record.
-
-This rule is the methodology layer. The mechanical layer is `pre-build-gate.sh` extended with a non-empty-body check on the 5 gate-marker classes (advisory in V1 per the allowlist baseline; BLOCK in V2 after the allowlist is empty).
-
-## Why this rule exists
-
-Bet 27c WU-11 surfaced "marker-enrichment-gap" as candidate substrate-defect 5. The gate hooks (`pre-build-gate.sh`) check marker file EXISTENCE only. An agent satisfies the gate by running `touch state/markers/temperance/<branch>.marker`. The marker exists; the gate clears; substantive work proceeds. Months later, a reader looking at the marker has zero evidence of what scope decision was made.
-
-Bet 27c shipped 13 PRs across the foundation work. Most markers in `state/markers/` are empty files from earlier sessions where the agent satisfied the gate without recording reasoning. The audit trail is missing.
-
-INSTEAD of writing empty markers to clear gates: the WU/PR that creates a marker writes its body content in the same change. Format conventions:
-
-- **Temperance marker** — date + branch + scope-decision (right-thing answer, right-way answer, drift trigger)
-- **Luminary marker** — date + branch + primary lens(es) + supporting lens(es) + one-line rationale per lens
-- **Arc-walk marker** — date + branch + parent_bet chain (recursive walk) + drivers consumed
-- **Orientation-gate marker** — date + branch + thread-level read completion notes
-- **Roadmap-reconcile-gate marker** — date + branch + reconcile result (no drift / drift detected / no roadmap declared)
-
-The bet 28a WU-0 prep + WU-1..5 markers ship as the exemplar pattern.
-
-## When this rule fires
-
-Any session creating a marker file in the 5 gate-marker directories:
-
-- `state/markers/temperance/`
-- `state/markers/luminary/`
-- `state/markers/arc-walk/`
-- `state/markers/orientation-gate/`
-- `state/markers/roadmap-reconcile-gate/`
-
-Does NOT fire on:
-
-- `state/markers/session-timing/` — transient timing data, machine-written
-- `state/markers/diagnose/` — fix-branch evidence (uses different format)
-- `state/markers/adr/` — ADR decision markers (different rule)
-- `state/markers/turn-prose-surface/` — kiss-surface flags (different rule)
-- Markers in the allowlist `state/markers/marker-enrichment-allowlist.txt` (grandfathered baseline; cleared over time)
-
-## What the rule requires
-
-When the step that creates a marker commits:
-
-1. Marker file exists at the expected path
-2. Marker file is non-empty (>0 bytes)
-3. Marker body contains the format conventions above (date + branch + decision-content; advisory check in V1, mechanical in V2)
-
-INSTEAD of `touch state/markers/temperance/<branch>.marker`: use heredoc to write the body inline:
-
-```bash
-cat > state/markers/temperance/<branch>.marker << 'EOF'
-# Temperance marker — <bet> <WU>
-- date: <ISO date>
-- branch: <branch>
-- scope-decision: <right-thing + right-way + drift-trigger>
-EOF
-```
-
-## Mechanical layer (V1 advisory)
-
-`pre-build-gate.sh` extended with `check_marker_non_empty()` function. Fires on existence check; if marker exists but is 0 bytes AND not in the allowlist, emits ADVISORY warning to stderr. Does NOT block in V1.
-
-V2 (deferred to follow-on goal): flip to BLOCK once the allowlist baseline is fully cleared (operator backfills over time).
-
-## Allowlist
-
-`.claude/hooks/marker-enrichment-allowlist.txt` lists existing empty markers as of bet 28a WU-5 land date. Entries grandfathered indefinitely. Operator backfills body content over time; when the allowlist is empty, V2 BLOCK flip becomes eligible.
-
-## Override
-
-`SKIP_MARKER_ENRICHMENT=1 <command>` — for one-shot migration scripts that bootstrap markers from external state. Logged via trace-helper.
-
-INSTEAD of overriding for routine work: write the body. The cost is seconds; the audit trail compounds across every future session reading the marker.
-
-## Composes with
-
-- `.claude/rules/sdlc-gates.md` — temperance + diagnose gate firing semantics
-- `.claude/rules/blocked-items.md` — BLOCK protocol (V2 will use this)
-- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on the hook + tests
-- `.claude/rules/mechanism-fidelity.md` — sister mechanical-enforcement discipline
-- `.claude/hooks/pre-build-gate.sh` — the mechanical implementation
-- `@luminary michael-feathers` — characterization tests as cure; existing empty markers are legacy; cure by enriching as touched
-
-## Refs
-
-- bet `docs/iteration-bets/2026-06-28a-mechanism-fidelity-cures-proposal.md` (WU-5)
-- bet 27c WU-11 (substrate-defect candidate 5 identification)
-- Closes bassclef-upstream#438
-- Closes part of bassclef-upstream#440
-
-## Retirement condition
-
-This rule retires only if the gate-marker primitive itself retires. Body-content conventions may evolve; the discipline of marker-as-audit-trail persists.

package/substrate/.claude/rules/mobile-ephemeral-session.md

@@ -1,109 +0,0 @@
----
-tier: lite
-globs: ["**/*"]
-description: Mobile/ephemeral session rules — state round-trips through git, no filesystem-only markers, explicit session-end
----
-
-# Mobile / Ephemeral Session Rule
-
-Fires whenever the session is running in an ephemeral environment
-(claude.ai/code mobile sandbox, CI runner, temporary container). See
-`standards/mobile-ephemeral-session.md` for the full standard.
-
-## Detection
-
-**Primary signal (required for certainty):**
-
-```bash
-[ "$CLAUDE_EPHEMERAL" = "1" ]
-```
-
-Operator sets this as the first command in mobile / CI / ephemeral
-sessions. Explicit opt-in removes guessing. Put it in a bookmarklet,
-shell init, or session template.
-
-**Fallback heuristics** (if primary not set, OR of these):
-
-| Check | Signal strength |
-|-------|----------------|
-| `pwd` doesn't start with `/Users/` (macOS operator path) | High |
-| `hostname` doesn't match known operator machines | High |
-| `$HOME` isn't operator's real home | High |
-| `/Applications/Tailscale.app/Contents/MacOS/Tailscale` missing | Medium |
-| `git reflog \| wc -l` is very small (fresh clone) | Medium |
-
-If ≥2 fallback signals fire, treat as ephemeral with a surfaced
-warning: "Detected ephemeral mode via heuristics — explicit
-`CLAUDE_EPHEMERAL=1` recommended."
-
-**First-session bootstrap**: on the very first mobile session, run
-with heuristics OR explicit flag — observe which signals fire —
-refine this list based on actual claude.ai/code sandbox environment.
-Update this rule after empirical data.
-
-## Rules when ephemeral
-
-1. **All artifacts push immediately.** Auto-save hook does
-   `git commit` AND `git push` — not deferred. If push fails, retry
-   once with backoff, then surface failure visibly.
-
-2. **Markers go git-tracked, not /tmp.** Any skill or hook that writes
-   `/tmp/*` markers MUST also write a git-tracked equivalent. The
-   bassclef durable surface is `state/markers/<gate>/...`
-   (temperance, diagnose, edit-count, session-timing); `/verify` keeps
-   its own pre-existing surface at `state/markers/verify/<branch>.marker`
-   for backward-compat with `pre-commit-gate.sh`. In ephemeral mode,
-   the git-tracked form is authoritative. Consumers of gate evidence
-   (pre-build-gate hook, compliance counter, `/chronicle` gate-evidence
-   auto-populate) read whichever form exists; dual-write ensures mobile
-   firings survive sandbox teardown.
-
-3. **Session lock has TTL.** Lock at `.claude/SESSION_LOCK` includes
-   ISO 8601 timestamp. Locks older than 30 minutes are cleared with
-   an announcement ("Clearing stale lock from [timestamp]"). No
-   indefinite holds.
-
-4. **Explicit session-end MUST fire.** Stop hook is unreliable in
-   ephemeral. Agent must invoke `/session-end` at natural stopping
-   points — task complete, context pressure, operator cue.
-
-5. **No credential-bearing tools.** Ephemeral sessions do not hold
-   SSH keys, AWS access keys, Tailscale tokens, or long-lived PATs.
-   Only fine-grained PATs or GitHub App installation tokens with
-   short TTL. Deploy work happens in CI after PR merge, never from
-   ephemeral.
-
-6. **Chronicle read at session start.** If project memory isn't
-   available (no MCP memory server), read the last 2-3 chronicles
-   at session start as context substitute. This is how ephemeral
-   sessions recover "what we were working on."
-
-7. **Conservative gating default.** Orchestrator-gated mode requires
-   explicit `--ephemeral-ok` flag in ephemeral. Default is operator-
-   gated even if orchestrator was requested — ephemeral adds risk
-   that deserves confirmation at decision points.
-
-## Failures to surface
-
-When any of the following happen, session output must prominently
-report it:
-
-- Push failure on auto-save (state loss risk)
-- Stale lock cleared (possible other session running)
-- Chronicle read failed at start (no context recovery)
-- Credential-bearing tool invoked (should not happen; rule violation)
-
-## Rationale
-
-Desktop sessions assume the filesystem survives between steps. Mobile
-sessions don't. A rule that lets agents keep working with the same
-skills and hooks — but with ephemeral-safe behavior — is how
-continuity holds.
-
-## Relationship
-
-- `standards/mobile-ephemeral-session.md` — full standard with
-  all MUST/SHOULD items
-- `.claude/rules/blocked-items.md` — BLOCKED: protocol still applies
-- `.claude/rules/guardrails.md` — "deploy prod requires human approval"
-  is reinforced by this rule (ephemeral can't deploy anyway)

package/substrate/.claude/rules/new-dependency-check.md

@@ -1,51 +0,0 @@
----
-tier: lite
-globs: ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "requirements.txt", "pyproject.toml", "poetry.lock", "Gemfile", "Gemfile.lock", "Cargo.toml", "Cargo.lock", "go.mod", "go.sum"]
-description: New dependency check — verify before adding any package; loads per-pkg-manager sibling
----
-
-# New Dependency Check
-
-Before adding any new dependency to the project, verify five universal concerns. Then load the per-package-manager sibling under `standards/dependency-discipline/<pkg_manager>.md` for stack-specific specifics.
-
-## Universal concerns (every package manager)
-
-1. **Stack compatibility** — does it work with the project's framework, language version, build system, and runtime constraints?
-2. **Bundle / install impact** — what does it add to your build artifact, install footprint, or runtime memory?
-3. **Runtime compatibility** — does the package make assumptions about the runtime environment (SSR vs CSR, threaded vs async, target architecture)?
-4. **Maintenance risk** — last publish date, open issues, bus factor. Prefer packages from known maintainers or organizations.
-5. **Alternatives** — can the need be met without a dependency? Built-in standard library? CSS-only? Native HTML? Small inline helper?
-
-## Per-package-manager siblings
-
-Bassclef's loader logic reads `tech_stack.pkg_manager:` from `.claude/bassclef-configs.jsonc` and loads the matching sibling for stack-specific specifics:
-
-| Adopter's `pkg_manager` | Sibling loaded |
-|---|---|
-| `npm` / `pnpm` / `yarn` | `standards/dependency-discipline/npm.md` |
-| `pip` / `poetry` | `standards/dependency-discipline/pip.md` |
-| `cargo` | `standards/dependency-discipline/cargo.md` |
-| `gem` | `standards/dependency-discipline/gem.md` |
-| `go-mod` | `standards/dependency-discipline/go-mod.md` |
-| `none` or unset | Universal concerns only |
-
-When the matching sibling does not exist (e.g., a stack bassclef has not yet adopted), the rule fires the universal concerns only and surfaces a `/promote` candidate for the missing sibling.
-
-## Process
-
-1. State the package name and what it is for.
-2. Run the five universal checks above.
-3. Run the per-PM checks from the matching sibling.
-4. If red flags surface in any check, propose an alternative.
-5. If clear, install and add to the project's Approved Dependencies list (or equivalent — see sibling for the exact list name and location).
-
-## Tech stack vocabulary
-
-The loader reads `tech_stack.pkg_manager` shipped in bassclef#1127 (WU-2 of bet 2026-06-18a). Adopters set the value at `/onboard-repo` Phase 2.x. When `tech_stack:` block is absent, the universal concerns still apply; sibling-specific guidance is skipped until the operator declares the stack.
-
-## Refs
-
-- Path A pattern from bassclef#1133 (ARCH-T0 stack-leakage audit).
-- WU-10 of bet `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` ships this catalog split.
-- Sister Path A: bassclef#1133 WU-5 (schema-management → migration-discipline catalog).
-- Reads from bassclef#1127 (tech_stack vocabulary).

package/substrate/.claude/rules/oo-ad-entry-point.md

@@ -1,117 +0,0 @@
----
-tier: lite
-globs: ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.py", ".claude/hooks/*.sh", "lib/*.sh", "scripts/*.sh"]
-description: OOA/D entry point — /decompose must fire for all Construction work, not just canvas-driven flow. Extended per bet 24a to cover hook + lib + script code paths per Cockburn ceremony tiering matrix.
----
-
-# OOA/D Entry Point Rule
-
-Construction work that modifies `src/` source files OR substrate code
-(`.claude/hooks/*.sh`, `lib/*.sh`, `scripts/*.sh`) MUST have `/decompose`
-evidence in the session before the first substantive commit. This applies
-regardless of the starting artifact — canvas, spec, epic, defect ticket,
-or bug report.
-
-Ceremony scales with code class per Alistair Cockburn's use-case tiering
-(skip / casual / brief / fully-dressed). Table amended per canvas
-`docs/canvases/2026-08-25-ooad-chain-as-substrate-offering.md` Axis 1 —
-adds a skip row at the top and lifts new substrate hook/lib to fully-dressed
-with ADR consult per Ousterhout + Beck + Brooks convergence:
-
-| Code class | Ceremony minimum | Artifact path |
-|---|---|---|
-| Typo, comment fix, doc edit | Skip. No chain fires. | — |
-| One-line change inside existing function | Casual use case sentence in commit body | Commit body |
-| Existing code extension (add arg, add case) | Brief use case + /decompose entry-point check | `docs/use-cases/UC-*.md` (brief) |
-| Adopter app code (`src/*.ts`, new module or route) | Fully-dressed use case + /decompose + /spec | `docs/use-cases/UC-*.md` |
-| Substrate hook (new `.claude/hooks/*.sh`) | Fully-dressed use case + /decompose + ADR consult | `docs/use-cases/UC-hook-*.md` |
-| Substrate lib (new `lib/*.sh` module) | Fully-dressed use case + /decompose + ADR consult | `docs/use-cases/UC-lib-*.md` |
-| Adopter-facing script (new `scripts/*.sh`) | Brief use case + Tier 0 tests | `docs/use-cases/UC-script-*.md` |
-
-Cockburn's rule — ceremony scales with the audience for the artifact.
-Fully-dressed reads by future maintainers, testers, product folks. Brief
-reads by devs on the same team. Casual reads by the author six weeks later.
-
-Bet 24a extended the trigger to substrate code paths so hooks + libs +
-scripts get the same design-first discipline that adopter app code gets.
-Per Feathers legacy-code retrofit — characterization tests come first for
-existing code; brief use case follows the tests.
-
-## Why this rule exists
-
-The `/decompose` skill catches the Langfuse-inside-HaikuImputer class
-of mistakes: cross-cutting concerns (observability, testability,
-extensibility, security, cacheability) bolted into implementations
-instead of resolved as Decorators wrapping interfaces.
-
-Recurring pattern: when Construction starts from a canvas, the UX
-translation chain (canvas → spec → ia-model → interaction-design →
-sequence diagrams → /decompose) runs naturally. When it starts from
-an epic or bug, agents jump to implementation and skip /decompose
-entirely — reproducing the exact failure mode the skill was built
-to prevent.
-
-Evidence:
-- POA 2026-04-09: Langfuse tracing bolted into HaikuImputer instead
-  of wrapping AssociationImputer facade
-- POA 2026-04-12: Credit-tracking logic added inline to scraper-api.ts
-  instead of ScraperMetricsDecorator wrapping interface (epic #472)
-
-Both were epic-driven (no canvas). /decompose was skipped.
-
-## What triggers the rule
-
-Creating changes to `src/` files on a Construction branch
-(`feature/*`, `fix/*`) without prior /decompose evidence.
-
-## What satisfies the rule
-
-One of:
-
-1. **Decomposition artifact** at `docs/decompositions/[slug].md` or
-   inline in the spec, produced by running `/decompose`.
-2. **Explicit trivial-work deferral**: "Skipped /decompose — trivial
-   change, no responsibility reassignment" stated in session.
-3. **Bug-hotfix deferral**: "Skipped /decompose — hotfix, diagnosis
-   identified specific failure site, no cross-cutting concerns
-   involved" stated in session.
-
-Silence is not deferral (per blocked-items rule).
-
-## Entry-point variants (per /decompose)
-
-- State 1 (canvas path): sequence diagrams drive decomposition
-- State 2 (epic/defect): reverse-engineer from spec + current code
-- State 3 (bug/hotfix): decompose the failure site, identify missing
-  interface/decorator
-
-All three produce the same artifact format; agents must not skip the
-skill just because the input shape differs from State 1.
-
-## Enforcement
-
-This rule ships at `tier: lite` — every adopter tier loads the discipline as methodology guidance.
-The mechanical BLOCK layer ships at `tier: standard`:
-
-**Methodology layer (all tiers — lite, standard, ultra).**
-Rule loads in session context. Agents self-check at Construction branch creation per the ceremony matrix above.
-
-**Mechanical layer (standard, ultra only).**
-Hook at `.claude/hooks/oo-ad-entry-point-check.sh` (bassclef-upstream#1169) fires on PreToolUse Edit/Write against paths in the frontmatter globs. It BLOCKs new-file writes when the required artifacts are missing.
-
-The hook checks two conditions:
-- Decomposition — marker at `state/markers/decompose/<branch>.marker` OR any file under `docs/decompositions/`
-- Use case — matching `docs/use-cases/UC-*.md` per code class (UC-hook-*, UC-lib-*, UC-script-*, or unprefixed UC-*)
-
-Existing file Edit passes through (Cockburn casual tier — commit body carries the discipline).
-Override: `SKIP_OO_AD_ENTRY_POINT=1` logged via trace-helper.
-
-**Lite adopter behavior.** Rule guides ceremony choice; no BLOCK fires on lite. Canvas Axis 1 (docs/canvases/2026-08-25-ooad-chain-as-substrate-offering.md) applied Ousterhout + Beck + Brooks lens — mechanical enforcement fits standard+ scope. INSTEAD of BLOCK on lite: rule guidance shapes agent behavior at construction branch creation. Methodology guidance benefits all adopters; mechanical BLOCK is standard+ scope.
-
-## Relationship to other rules
-
-- `sdlc-gates.md` Pre-Build section — temperance + diagnosis gates
-  fire before this one
-- `blocked-items.md` — entry-point skip is a BLOCKED condition; resolve
-  or explicitly defer
-- `testing.md` — new interfaces identified via /decompose need tests