@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/standards/branch-stacking.md

@@ -0,0 +1,408 @@
+---
+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/dist/lite/standards/code-safety-principles.md

@@ -0,0 +1,176 @@
+---
+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.