@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/standards/branch-stacking.md

@@ -1,408 +0,0 @@
----
-tier: lite
-description: Stacked atomic branches are the default for any iteration with N≥2 issues.
----
-
-# Branch Stacking Standard
-
-## Default for multi-issue iterations
-
-**Stacked atomic branches are the default** for any iteration with N≥2
-issues. One branch per issue, one PR per branch, each independently
-reviewable and revertable. The `bundle` flag at `/autonomous start`
-overrides this; see `.claude/rules/pr-strategy.md` for when bundling is
-acceptable.
-
-This is codified — the boot sequence does not ask "stacked or bundled?"
-per session.
-
-## When to use
-
-Autonomous or multi-step sessions where work spans multiple logical units
-that should be independently reviewable and revertable. This extends the
-trunk-based model in `.claude/rules/branching.md` for multi-branch work.
-
-Use this standard when:
-- An agent (or agents) will produce more than one PR in a session
-- Work has a natural decomposition into independent or sequenced units
-- You want the ability to accept some branches and reject others
-
----
-
-## Core principle
-
-**Each branch = one intent.** A branch does one thing: "Add the data model"
-or "Build the list view" — not "Add data model and list view and API routes."
-
-If you can't describe a branch's intent in one sentence, split it.
-
----
-
-## Stack manifest
-
-Before building, the agent writes a manifest declaring the planned stack.
-This is the iteration's work breakdown and the Orchestrator's routing map.
-
-**Location**: `docs/branch-stacks/YYYY-MM-DD-slug.md` in the working repo.
-
-### Format
-
-```markdown
-# Branch Stack: [name]
-
-**Issue**: #NNN
-**Iteration goal**: [path to iteration goal]
-**Execution mode**: sequential | parallel | mixed
-**Date**: YYYY-MM-DD
-
-## Branches
-
-| # | Branch | Intent | Depends on | Parallel-safe |
-|---|--------|--------|-----------|---------------|
-| 1 | feature/NNN-stack-1-data-model | CRM schema + migration | none | yes |
-| 2 | feature/NNN-stack-2-api-routes | CRUD API for entities | stack-1 | no |
-| 3 | feature/NNN-stack-3-list-view  | List page UI | stack-1 | yes |
-| 4 | feature/NNN-stack-4-detail-view | Detail page UI | stack-3 | no |
-
-## Parallel groups
-
-- Group A (no dependencies): stack-1
-- Group B (after stack-1 merged): stack-2, stack-3 (parallel)
-- Group C (after stack-3 merged): stack-4
-
-## Acceptance criteria per branch
-
-### stack-1: data-model
-- [ ] Prisma schema with migration file
-- [ ] prisma generate succeeds
-- [ ] Seed script if needed
-
-### stack-2: api-routes
-- [ ] CRUD endpoints with tests
-- [ ] Auth middleware applied
-
-[... etc]
-```
-
----
-
-## Execution modes
-
-### Sequential (supervised sessions)
-
-One agent, one branch at a time. Human checkpoint between branches.
-
-```
-Agent builds stack-1
-  → PR opened → human reviews → approved → merge to main
-Agent builds stack-2
-  → PR opened → human reviews → approved → merge to main
-[...]
-```
-
-**Branch base**: Each branch is based on `main` (after the previous branch
-is merged). This means each branch includes the accumulated work of prior
-branches but is independently reviewable as a PR.
-
-**Human checkpoint**: After each branch, the agent opens a PR and stops.
-Human reviews. Approved → merge → agent proceeds. Rejected → agent adjusts
-or the branch is discarded.
-
-### Parallel (Cherny's worktree model)
-
-Multiple agents in git worktrees (`claude -w`), each on its own branch,
-building simultaneously. No dirty tree conflicts — each worktree is an
-isolated copy of the repo.
-
-```
-Orchestrator reads stack manifest
-  → Independent branches fan out to parallel worktree agents
-  → Dependent branches queue behind prerequisites
-
-Agent A (worktree 1): stack-2-api-routes
-Agent B (worktree 2): stack-3-list-view
-  [building simultaneously, no conflicts]
-
-Each agent opens its own PR when done
-Human reviews PRs after session (or Reviewer agent evaluates)
-```
-
-**Branch base for parallel work**: Independent branches base off `main`.
-When a branch depends on another (stack-4 depends on stack-3), it bases
-off the dependency branch. The manifest makes this explicit.
-
-**Worktree lifecycle**:
-- Created by Orchestrator (or human) when fanning out parallel work
-- Each worktree gets one branch, one agent
-- On completion: agent opens PR, worktree is available for cleanup
-- Merged worktrees: deleted automatically after merge
-- Abandoned worktrees (no commits after 2 hours): flagged for cleanup
-- Worktree cleanup command: `git worktree prune`
-
-**Conflict detection**: If two parallel agents modify the same file,
-the Orchestrator flags this to the human. Do not attempt auto-resolution —
-file-level conflicts in parallel branches indicate a decomposition problem
-(the branches weren't truly independent). Fix the manifest, not the merge.
-
-### Mixed (common in practice)
-
-Some branches are independent (parallelize), some are dependent (sequence).
-The manifest's dependency graph determines which is which.
-
-```
-Group A: stack-1 (alone, must complete first)
-Group B: stack-2 + stack-3 (parallel, both depend on stack-1)
-Group C: stack-4 (sequential, depends on stack-3)
-```
-
-The Orchestrator executes Group A, waits for merge, fans out Group B in
-parallel worktrees, waits for Group B merges, then executes Group C.
-
----
-
-## Graceful unwind
-
-If branch N is rejected:
-- **Branches that depend on N** (per manifest): also discarded
-- **Branches independent of N**: survive untouched
-- **Agent never needs to untangle** — independence is designed in, not retrofitted
-
-The dependency graph in the manifest makes this mechanical:
-1. Look up what depends on N (transitively)
-2. Discard N and all its dependents
-3. Everything else is unaffected
-
-This is why independence is the default and dependencies are the exception.
-
----
-
-## Squash merge — two protocols
-
-When merging stacked PRs whose bases are other feature branches
-(Graphite-style stack — common when the agent declares "depends on"
-in the manifest), GitHub auto-closes dependent PRs the moment the
-base branch is deleted. ("Cannot change the base branch of a closed
-pull request.") Recovery requires re-creating each PR. Costs ~3-8
-turns per stack. Observed 2026-04-18c (#178/#179/#180 cascade).
-
-Two protocols handle this. Pick by **when** you can act:
-
-| Protocol | When to use | Trade-off |
-|----------|-------------|-----------|
-| **Retarget-before-merge** (preferred) | You have access to the dependent PRs before merging stack-N | Cleanest — no auto-close, no recovery cost |
-| **Rebase-after-merge** (fallback) | Auto-close already happened, OR you forgot to retarget | Recoverable but expensive — per-PR rebase + re-create |
-
-If the iteration uses **base = main** for every branch (independence
-designed in via manifest, no Graphite-style chaining), neither cascade
-fires — but stacked PRs with declared dependencies almost always use
-chained bases.
-
-### Retarget-before-merge (preferred)
-
-**Before** squash-merging PR N in a stack:
-
-1. **Identify dependent PRs** — those whose `baseRefName` equals
-   PR N's `headRefName`. Use the helper script:
-
-   ```bash
-   scripts/check-stack-dependents.sh <PR-N-number>
-   ```
-
-   This lists open PRs that will auto-close if PR N merges and its
-   branch is deleted.
-
-2. **Retarget each dependent to main** (or the stack root):
-
-   ```bash
-   gh pr edit <dependent-PR-number> --base main
-   ```
-
-   The dependent PR survives the merge. Its diff may now show extra
-   commits (the work from PR N) until the dependent is rebased — but
-   it stays open.
-
-3. **Merge PR N**:
-
-   ```bash
-   gh pr merge <PR-N-number> --squash --delete-branch
-   ```
-
-   Auto-close cascade does not fire because no other PR has PR N's
-   branch as base anymore.
-
-4. **(Optional) Rebase dependent on top of merged main** if you want
-   the diff to show only the dependent's own work:
-
-   ```bash
-   git checkout <dependent-branch>
-   git pull origin main --rebase
-   git push --force-with-lease
-   ```
-
-5. **Repeat** for the next PR in stack order.
-
-#### Why this works
-
-The auto-close trigger is "base branch deleted on a closed/merged PR
-where another PR depends on it." Retarget breaks the dependency
-*before* the delete fires. The dependents continue tracking main; their
-content is unchanged.
-
-### Rebase-after-merge (fallback)
-
-Use only if the cascade has already fired (dependent PRs show
-"Closed — base branch was deleted") OR you forgot the retarget step.
-
-After squash-merging PR N in a stack (without prior retarget):
-
-1. **Pull updated main**: `git checkout main && git pull`
-2. **Rebase the next branch**: `git checkout feature/next && git rebase main`
-3. **Force push with lease**: `git push --force-with-lease`
-   (safe force push — fails if someone else pushed to the branch)
-4. **If GitHub auto-closed the downstream PR**: re-create it pointing
-   at main, since the closed PR cannot be reopened with a new base:
-   ```bash
-   gh pr create --base main --head feature/next \
-     --title "[same as closed PR]" \
-     --body "[same as closed PR, plus link to closed PR for context]"
-   ```
-   Or merge locally:
-   ```bash
-   git checkout main
-   git merge --squash feature/next
-   git commit -m "feat: description"
-   ```
-5. **Repeat** for remaining branches in stack order
-
-#### Why this happens
-
-Squash merge creates a single new commit on main that replaces all
-commits from the branch. The next branch's base commits no longer exist
-on main — they were squashed into one. GitHub sees a conflict because
-the branch history diverged from main. Combined with branch deletion,
-the auto-close cascade fires for any dependent PR.
-
-### Auto-save checkpoint conflicts
-
-If the auto-save launchd timer committed checkpoint files (e.g.,
-`.test-baseline`) on feature branches during construction, these
-checkpoints will conflict during rebase. Use `git rebase --skip` to
-drop the checkpoint commits — they're not part of the real work.
-
-The auto-save timer should be paused during autonomous sessions
-(SESSION_LOCK check, see #62).
-
-### Alternative: regular merge commits
-
-Using regular merge commits (no squash) preserves branch relationships
-and avoids the rebase cascade. Trade-off: messier main history with
-merge commits. Squash is still preferred for a clean main, but the
-rebase step is the cost.
-
----
-
-## Naming convention
-
-```
-feature/ISSUE-NNN-stack-N-short-description
-```
-
-Examples:
-- `feature/47-stack-1-crm-data-model`
-- `feature/47-stack-2-crm-api-routes`
-- `feature/47-stack-3-crm-list-view`
-
-The `stack-N` segment makes merge ordering obvious in `git branch` output
-and GitHub's PR list.
-
----
-
-## Per-branch verification
-
-Each branch passes `/verify` independently before the PR is opened.
-CI must pass on each branch in isolation. A branch that only works when
-combined with another branch is not atomic — fix the decomposition.
-
-Exception: Dependent branches (stack-4 depends on stack-3) are verified
-against their base branch, not against main alone.
-
----
-
-## Automatic stack creation (via /autonomous)
-
-When `/autonomous start` enters Construction, the Orchestrator runs a
-five-step automation sequence (defined in strategy/autonomous-boot-sequence.md Step 9).
-This section documents what the automation produces so agents know what
-to expect when picking up a stack mid-session.
-
-### What gets created automatically
-
-**1. GitHub issues** — one per task, created via `gh issue create`.
-Each issue includes: what, acceptance criteria, and a ref to the
-iteration goal. Issue numbers are assigned before any branch is created.
-
-**2. Stack manifest** — written to `docs/branch-stacks/YYYY-MM-DD-slug.md`
-before any branch is created. The manifest is committed first so all
-agents can find it.
-
-**3. Branches** — created from main in dependency order, named
-`feature/ISSUE-NNN-stack-N-short-description`.
-
-### Automation invariants
-
-- The manifest is always committed before branches are created.
-  If you see a branch without a manifest, the automation was interrupted.
-- Issue numbers in the manifest are real GitHub issue numbers.
-  A placeholder NNN means the automation did not complete — finish it.
-- Every branch bases from main, not from the previous branch.
-  Stacked rebases follow the squash-merge protocol in this document.
-- The manifest is updated after each PR opens (status: pr-open) and
-  after each merge (status: merged). Pending = not yet started.
-
-### Resuming an interrupted stack
-
-If the automation was interrupted (crash, time budget exhausted, pause),
-the next session reads:
-
-1. `docs/branch-stacks/YYYY-MM-DD-slug.md` — what's done, what's pending
-2. `docs/whereami.md` — branch_stack field points at the manifest
-3. GitHub issues — open issues with no linked PR are pending branches
-
-Resume from the first branch with status "pending" in the manifest.
-Do not re-create issues or rewrite the manifest unless it is corrupted.
-
-### Manual stack creation (non-autonomous sessions)
-
-The standard still applies for manually created stacks — write the
-manifest first, create issues, then branches. The automation does this
-programmatically. Format and invariants are identical.
-
----
-
-## Integration with process framework
-
-| Concept | Maps to |
-|---------|---------|
-| Branch stack | Iteration |
-| Stack manifest | Iteration work breakdown |
-| Individual branch | Task within iteration |
-| Iteration goal | Governs the whole stack |
-| Parallel groups | Orchestrator routing |
-
-Individual branches do not need their own iteration goals. The stack-level
-bet covers time budget, risk, and value for the entire body of work.
-
----
-
-## Relation to existing branching rules
-
-This standard extends `.claude/rules/branching.md`. All existing rules
-still apply:
-- `main` is always deployable
-- Every branch ties to a GitHub Issue (stack branches share the parent issue)
-- Squash merge to main
-- No branches older than 5 days
-- Force push on feature branches is fine, never on main
-
-The addition: branches can now be explicitly sequenced and parallelized
-via a stack manifest, with graceful unwind as a first-class property.

package/substrate/standards/code-safety-principles.md

@@ -1,176 +0,0 @@
----
-tier: lite
-description: "This standard codifies language-agnostic principles for writing safer code across bassclef's supported stacks (TypeScript, Python, Ruby, Java, Go, bash)."
----
-
-# Code Safety Principles — Language-Agnostic
-
-This standard codifies language-agnostic principles for writing safer code across bassclef's supported stacks (TypeScript, Python, Ruby, Java, Go, bash). It is the substrate-internal companion to the Saltzer & Schroeder luminary — the luminary names WHY each principle matters at the protection-mechanism design level; this standard names WHAT the principle looks like in source code.
-
-## Why this standard exists
-
-Bassclef's `.claude/rules/security.md` is scoped to web-application source files (`.ts`, `.tsx`, `.json`, `.env`, `Dockerfile`). It catches the OWASP-top-10 surface for the web layer. It does not cover:
-
-- Bash hooks (bassclef's own implementation language for `.claude/hooks/*.sh`)
-- Backend daemons (Python, Go, Java, Ruby — any language an adopter ships)
-- Code review of cross-cutting concerns (default-behavior choices, scope choices, override-path design)
-
-The principles in this standard apply to ALL six languages because they are about the *shape* of code, not language-specific syntax. The downstream stack-specific guides (Phase X-3 `bash-hook-safety.md`; Phase Y reference configs per stack) instantiate these principles in the language idiom of the day.
-
-## Anchor luminary
-
-`@luminary saltzer-schroeder` is the authority. Their 1975 paper articulated the 8 principles for protection-mechanism design that this standard implements at the source-code level.
-
-INSTEAD of inventing bassclef-specific principles: this standard maps Saltzer & Schroeder's 8 principles into 6 source-code disciplines that any language can express. The 1975 framing predates every modern attack class and still holds.
-
-## The six source-code disciplines
-
-### 1. Validate at boundaries
-
-Every value entering the system from an external source must be validated at the boundary. After validation, internal code treats the value as trusted.
-
-INSTEAD of validating at every call site: validate once at the entry boundary; pass typed values to internal code that trusts them.
-
-**Boundaries to validate at:**
-
-- HTTP request handlers (parse + validate body, query, headers, path params before any business logic)
-- CLI argument parsers (validate flag values before dispatch)
-- File parsers (validate schema/structure before consuming content)
-- Foreign-key dereferences across service boundaries (validate the referenced object's shape before use)
-- Environment variable reads at process startup (validate types + ranges before runtime use)
-
-**Per language idiom:**
-
-| Stack | Validation primitive |
-|---|---|
-| TypeScript | Zod / Yup / io-ts schema at handler entry |
-| Python | Pydantic model at handler entry; argparse with custom types for CLI |
-| Ruby | dry-validation or ActiveModel validation at controller boundary |
-| Java | Jakarta Bean Validation (JSR 380) annotations; manual validators for non-bean inputs |
-| Go | github.com/go-playground/validator at handler entry; validate.Var for ad-hoc |
-| Bash | argparse-style validation in helper functions; `[[ -n "${var:?}" ]]` for required values |
-
-### 2. Fail-safe defaults
-
-Default behavior denies / refuses / rejects unless an explicit signal permits. The author of a new code path is forced to make the permission decision visible.
-
-INSTEAD of "permit by default, deny on exclusion list": deny by default, permit on explicit allowlist. The allowlist makes new permissions visible; the exclusion list makes new denials invisible.
-
-**Examples by domain:**
-
-- **HTTP routes** — middleware denies all paths by default; routes opt in via explicit definitions. Catch-all 404 vs catch-all 200.
-- **Feature flags** — new flag defaults to OFF; opt-in turns on. INSTEAD of new flag default ON (silently activating in every environment).
-- **CORS** — empty origin list rejects; explicit origins permit. INSTEAD of `*` wildcard.
-- **DB row visibility** — multi-tenant query starts with tenant filter; opt in to cross-tenant only with explicit annotation. INSTEAD of unfiltered base query + per-call tenant filter (easy to forget).
-- **Bash auto-save** — refuse all branches; allowlist enables. INSTEAD of allow all branches; refuse list excludes (PR #1058 anti-pattern).
-
-### 3. Least privilege
-
-Each operation runs with the minimum privileges needed to complete its job. Tokens, credentials, file modes, network access, database permissions — all scoped to the narrowest grant.
-
-INSTEAD of granting broad permissions because tightening is annoying: grant narrow permissions at creation; broaden only with explicit justification.
-
-**Per language idiom:**
-
-| Stack | Least-privilege primitive |
-|---|---|
-| TypeScript | scoped Prisma client / scoped fetch credentials / scoped GitHub PAT |
-| Python | scoped boto3 IAM roles; scoped requests session with restricted cookies |
-| Ruby | scoped ActiveRecord connection pool per concern; scoped Net::HTTP credentials |
-| Java | scoped JDBC connection with role-based grants; scoped HttpClient TLS config |
-| Go | scoped HTTP client; scoped database/sql DSN per role |
-| Bash | `--scope=<minimum>` flags on every CLI; `sudo` disallowed by default; file modes 644/755 by default |
-
-Token discipline (per memory `feedback_never_paste_tokens_in_chat`) is least privilege applied to authentication.
-INSTEAD of broad-org admin tokens: fine-grained PATs scoped to a single target repo + minimum permission set. INSTEAD of pasting credential values into any chat / log / commit: reference credentials by environment-variable name only.
-
-### 4. Complete mediation
-
-Every access to every protected resource passes through the protection mechanism. There are no "trusted" internal paths that skip the check.
-
-INSTEAD of checking authorization at the boundary and trusting internal callers: check at every access point. The cost of one extra check is small; the cost of one missed check can be the whole system.
-
-**Examples by domain:**
-
-- **DB queries** — Row-level security at the database is complete mediation; ORM-side filters are bypass-able if a caller uses raw SQL
-- **HTTP middleware** — Apply auth middleware to a route group; selective-skip is a security bug.
-  INSTEAD of allowing per-route opt-out: route groups are the granularity; new routes inherit the middleware.
-- **Tenant filtering** — Filter at the query builder layer (every query inherits); not at the controller layer (controllers can forget).
-  INSTEAD of controller-layer filtering: query-builder-layer filtering so the tenant context is structurally inseparable from every query.
-- **File access** — Mediate via accessor functions that include the check; raw file handles bypass the check.
-  INSTEAD of granting raw handles for performance: accessor functions own the read/write surface; performance optimization lives inside the accessor.
-- **Bash hook PreToolUse** — Hook fires on every matching tool call, not "first call per session"
-
-### 5. Defense in depth
-
-Multiple independent layers protect the same resource. A single compromise of one layer leaves the resource still protected by the others.
-
-INSTEAD of relying on one strong layer: stack multiple layers, each cheap, with no single layer load-bearing.
-
-**Example stack for bassclef production deploys:**
-
-1. GitHub Environment with `required_reviewers` (separation of privilege)
-2. `deploy-guard.sh` hook BLOCKs without explicit `DEPLOY_PROD=1` env var
-3. `gh pr merge` requires operator account (not agent token)
-4. CI passing gate (test + build + lint + security scan)
-5. Manual smoke-test acknowledgement before traffic shift
-
-Five layers. Compromise of any one (e.g., agent token leaked) still leaves four layers protecting the deploy.
-
-INSTEAD of "we have CI, that's enough": every layer is cheap; every layer catches a different failure class.
-
-### 6. Audit at every layer
-
-Every state-modifying action emits an audit record. The record names: who, what, when, from where, with what authority.
-
-INSTEAD of audit-only-on-failure: audit on every state change so post-incident reconstruction has the data it needs.
-
-**Per language idiom:**
-
-| Stack | Audit primitive |
-|---|---|
-| TypeScript | structured logger (pino, winston) + trace ID at handler entry |
-| Python | structlog or loguru + trace ID; opentelemetry for cross-service |
-| Ruby | structured Rails logger + Lograge; trace ID via request middleware |
-| Java | SLF4J + Logback structured layout; OpenTelemetry tracer |
-| Go | zap or zerolog + trace context; OpenTelemetry SDK |
-| Bash | `trace-helper.sh` writes JSONL to `.claude/state/traces/<session>.jsonl` |
-
-Bassclef's `lib/trace-helper.sh` is the substrate's audit primitive for bash. Every hook fires `trace_record <hook> <verb> <context>` before exit. Override usage (e.g., `SKIP_*=1`) is logged automatically.
-
-## What this standard does NOT do
-
-- **Does not specify cryptographic primitives** — algorithm choice, key length, library selection are out of scope. Use the language's standard library + vetted cryptography library (e.g., libsodium binding, Bouncy Castle).
-- **Does not catalog OWASP top-10 mitigations** — `.claude/rules/security.md` covers the web layer; this standard covers the substrate-internal layer that the web layer rests on.
-- **Does not replace `/security-review`** — that skill applies these principles to a specific PR. This standard is the reference the skill cites.
-- **Does not specify threat models** — Schneier-anchored threat-thinking is a separate luminary candidate (deferred per Phase X+Y+Z bet's Out of scope).
-
-## When this standard fires
-
-| Surface | What to check |
-|---|---|
-| New HTTP handler / route | Boundary validation present? Default behavior fail-safe? |
-| New bash hook | All 8 principles via stack-translation table in `saltzer-schroeder.md` |
-| New CLI tool | Argument validation? Least-privilege credential scope? |
-| New cross-service call | Validation on the response? Audit emit at call site? |
-| Schema migration | Defense in depth via review + dry-run + rollback? |
-| Code review | All 6 disciplines applied? |
-
-## Refs
-
-- `@luminary saltzer-schroeder` — anchor; 8 principles for protection-mechanism design
-- `.claude/rules/security.md` — web-layer rule (`.ts/.tsx/.json/.env/Dockerfile` scope)
-- `.claude/rules/destructive-operations.md` — agent self-assessment companion
-- `standards/bash-hook-safety.md` (Phase X-3) — bash-specific instantiation of these principles
-- `docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md` — goal authoring this standard
-- bassclef#1058 — concrete failure (auto-save scope hole) that motivated this standard
-
-## Composes with
-
-- `standards/destructive-operations.md` style → `.claude/rules/destructive-operations.md` (agent self-assessment)
-- `standards/bassclef-configs-schema.md` § Security scanning (Phase Y-2) — adopter-facing scanner-adapter config
-- `standards/security-scanner-adapter.md` (Phase Y-1) — adapter pattern that uses scanner outputs to enforce these disciplines
-
-## Retirement
-
-This standard retires only if Saltzer & Schroeder's principles are superseded by a fundamentally different protection-mechanism framework. The 8 principles have held for 50 years; retirement is not a near-term concern. The stack-translation tables evolve as bassclef adds support for new languages.