@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/standards/bash-hook-safety.md

@@ -0,0 +1,246 @@
+---
+tier: lite
+description: "This standard codifies the defensive coding discipline for bassclef's bash hooks (.claude/hooks/.sh) + supporting bash scripts (scripts/.sh, lib/*.sh)."
+---
+
+# Bash Hook Safety Standard
+
+This standard codifies the defensive coding discipline for bassclef's bash hooks (`.claude/hooks/*.sh`) + supporting bash scripts (`scripts/*.sh`, `lib/*.sh`). It is the bash-specific instantiation of `standards/code-safety-principles.md`.
+
+## Why this standard exists
+
+Bassclef's hooks are bash scripts that fire on every tool call. They sit between the operator's intent and every Edit / Write / Bash invocation. A bug in a hook is amplified: every session in every consumer repo runs the hook on every tool call. Three months of substrate-evolution surfaced four same-shape failures (bassclef#1027, #1054, #1058, #1060) — all in bash code, all caught after PR open, all preventable by hooks at the moment of failure.
+
+The existing `.claude/rules/security.md` is scoped to web-application source files (`.ts`, `.tsx`, `.json`, `.env`, `Dockerfile`). It does not cover `.sh`. This standard closes that gap with hook-specific discipline anchored to Saltzer & Schroeder's 8 principles per `@luminary saltzer-schroeder`.
+
+## Anchors
+
+- `@luminary saltzer-schroeder` — the 8 protection-mechanism principles this standard instantiates
+- `@luminary john-ousterhout` — Deep modules + define-errors-out-of-existence framing for hook interface design
+- `@luminary kent-beck` — TDD discipline for hooks (Tier 0 per `.claude/rules/testing-tier-config.md`)
+- `standards/code-safety-principles.md` — language-agnostic principles this standard instantiates for bash
+
+## The seven disciplines
+
+### 1. Strict mode at the top
+
+Every bash hook + script starts with:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+```
+
+- `-e` exits on any command failure
+- `-u` exits on undefined variable use
+- `-o pipefail` makes pipelines fail if any stage fails (default is "last stage's exit code only")
+
+INSTEAD of "I'll handle errors explicitly where they matter": strict mode makes errors loud by default. Explicit error handling overrides apply per-command via `command || true` or `command 2>/dev/null` with intent.
+
+**Why mandatory**: bash's default behavior is "continue on error, use the empty string for undefined variables." Bassclef's hooks run in environments where silent failure causes incorrect downstream state. PR #1054 demonstrated this: `log()` function's quiet-mode toggle behavior depended on an unset variable being treated as false; strict mode would have surfaced the bug at write-time.
+
+### 2. Quote every variable expansion
+
+Every `$var` or `${var}` reference inside a string context gets double-quoted:
+
+```bash
+# Correct
+file_path="$1"
+if [[ -f "$file_path" ]]; then
+  cat "$file_path"
+fi
+
+# Wrong — word-splits on spaces; glob-expands; breaks on empty
+if [[ -f $1 ]]; then
+  cat $1
+fi
+```
+
+INSTEAD of "I know this variable will never contain a space": quote universally. The cost of consistent quoting is zero; the cost of one missed quote in a path with a space is silent corruption.
+
+**Exception**: `local` declarations of arrays + variables that intentionally word-split (rare; document with an inline comment).
+
+### 3. `local` in functions
+
+Every variable declared inside a function uses `local`:
+
+```bash
+parse_config() {
+  local config_path="$1"
+  local mode="${2:-default}"
+  # ...
+}
+```
+
+INSTEAD of relying on bash's default of global scope: `local` keeps function-internal state inside the function. A function that pollutes parent scope is a defect waiting to surface — the bug appears when a different caller reuses the same variable name.
+
+### 4. Trap EXIT for cleanup
+
+Hooks that create temporary files, lock files, or background processes register a trap for cleanup:
+
+```bash
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# ... use $TMP_DIR ...
+# Cleanup happens automatically on any exit path
+```
+
+INSTEAD of "I'll clean up at the end of the happy path": cleanup at every exit path including error paths and SIGINT. `trap '...' EXIT` runs the cleanup regardless of how the script exits.
+
+For hooks specifically: clean up `/tmp` markers, release `flock`s, kill background `tee`s.
+
+### 5. Explicit return codes
+
+Hook exit codes carry meaning. Bassclef's hook protocol:
+
+- `0` — allow the tool call (default)
+- `1` — generic non-blocking failure (usually a bug in the hook itself; logged but doesn't block)
+- `2` — BLOCK the tool call (the operator-facing surface)
+- `>2` — reserved; treat as `1`
+
+Every hook ends with explicit `exit 0` (or `exit 2` on block). Relying on bash's "exit code of last command" default produces silent breakage when refactors reorder statements.
+INSTEAD of implicit "last-command exit code": explicit `exit N` at every termination point. Hook readers should see the exit value next to the BLOCK decision.
+
+### 6. Glob-tolerance via fallthrough
+
+Bash's `for f in pattern/*` fails silently when the pattern matches nothing — the loop body runs once with the literal pattern string. The shape that tolerates empty match:
+
+```bash
+shopt -s nullglob   # empty match = empty loop, not literal pattern
+
+for f in "$dir"/*.json; do
+  process "$f"
+done
+
+shopt -u nullglob   # restore default
+```
+
+INSTEAD of assuming a glob always matches: `nullglob` makes empty-match an empty loop. The hook handles "no files" naturally.
+
+For one-off patterns: `[[ ${#files[@]} -gt 0 ]]` after assigning to an array via `files=("$dir"/*.json)`.
+
+### 7. Audit emission at every exit path
+
+Every hook emits a trace record before exit:
+
+```bash
+source "$(dirname "$0")/../lib/trace-helper.sh"
+
+# ... hook body ...
+
+trace_record "hook-name" "decision" "context"
+exit 0
+```
+
+INSTEAD of audit-only-on-block: audit on allow + block + override usage + skip path. Post-incident reconstruction needs the full trace.
+
+## Common idioms
+
+### `find | head` under `set -euo pipefail` — SIGPIPE kills the script
+
+Under `set -euo pipefail`, piping `find` into `head -N` can silently kill the script when `find` produces more than N results. `head` closes stdin after N lines, `find` receives SIGPIPE from the closed pipe, `find` exits 141, and `pipefail` promotes 141 to the pipeline exit code. `set -e` then kills the script silently.
+
+Anti-pattern:
+
+```bash
+set -euo pipefail
+broken=$(find . -type l \! -exec test -e {} \; -print 2>/dev/null | head -10)
+# ^ script may exit here with no error output when find produces >10 results
+```
+
+INSTEAD — Option 5d (preferred): bash-native array truncation. No pipe means no SIGPIPE.
+
+```bash
+set -euo pipefail
+readarray -t all_broken < <(find . -type l \! -exec test -e {} \; -print 2>/dev/null)
+broken="$(printf '%s\n' "${all_broken[@]:0:10}")"
+```
+
+Three alternatives, each with tradeoffs:
+
+- **SIGPIPE catch** — `find ... 2>/dev/null | head -10 || true`. Swallows all pipeline errors including real ones; less specific than the SIGPIPE-only class.
+- **No-pipe restructure** — `find ... -print | while read; do ... done` with an explicit counter break. More lines; keeps structural-code style.
+- **Fallthrough with `|| true`** — cheapest to write; hides every non-zero pipeline exit; least safe under production loads.
+
+Option 5d preserves the structural read shape AND removes the SIGPIPE vector at the source. Strictly stronger error propagation than SIGPIPE catch — the pipe never exists, so no pipe error class can fire.
+
+Anchors:
+
+- `@luminary linus-torvalds` — adopter contract on observable script behavior; silent-exit is worse than loud-fail
+- `@luminary michael-feathers` — characterization test pins the FAIL contract (find-produces-N-plus-1 case) before the fix ships
+
+Per sunj-labs/bassclef-upstream#912. Cure 4 shipped inside the #901 install-corrupts-tree epic; PR #892 carries the exemplar. See the ticket body for the second-AI consultation write-up + the linus lens shift from Option 1 (SIGPIPE catch) to Option 5d.
+
+## The Saltzer & Schroeder stack-translation
+
+This standard's seven disciplines instantiate Saltzer & Schroeder's 8 principles (per `@luminary saltzer-schroeder` stack-translation table):
+
+| Saltzer & Schroeder principle | Bash discipline |
+|---|---|
+| Economy of mechanism | Hook body ≤200 lines; helpers in `lib/*.sh` |
+| Fail-safe defaults | Strict mode `set -euo pipefail`; default `exit 2` on uncertainty |
+| Complete mediation | PreToolUse fires on every matching call |
+| Open design | Triggers documented in `docs/hooks-index.md`; BLOCK banners name the read path |
+| Separation of privilege | Destructive hooks require multiple independent signals |
+| Least privilege | `cd` only when needed; scope git/file ops to specific paths |
+| Least common mechanism | Per-hook trace; per-hook test; no global state between hooks |
+| Psychological acceptability | `SKIP_<HOOK>=1` per-call override; logged via trace-helper |
+
+## Shellcheck
+
+Every bash hook + script passes `shellcheck` (current version). Tier 0 strict-TDD discipline per `.claude/rules/testing-tier-config.md` extends to shellcheck: an edit that introduces a shellcheck finding fails CI per Phase X-4's shellcheck workflow.
+
+**Local install**:
+
+| OS | Command |
+|---|---|
+| macOS | `brew install shellcheck` |
+| Ubuntu/Debian | `apt install shellcheck` |
+| Fedora | `dnf install ShellCheck` |
+| Arch | `pacman -S shellcheck` |
+| Container builds | Add `shellcheck` to the base image |
+
+**Local run**:
+
+```bash
+shellcheck .claude/hooks/*.sh scripts/*.sh lib/*.sh
+```
+
+**Phase X-4** ships the CI workflow that runs shellcheck on every PR + a baseline allowlist (`.claude/hooks/shellcheck-allowlist.txt`) with 60-day grace through 2026-08-17 for existing findings.
+
+## What this standard does NOT do
+
+- Does not cover language interop (bash calling Python, Python calling bash) — handle at the boundary
+- Does not specify which utilities to use (`gh` vs `curl` vs `jq` vs `yq`) — that is a stack-choice question
+- Does not cover bash 4+ features absent from macOS's default install (`${var^^}` uppercase conversion, associative arrays) — bash 3.2 compatibility is the baseline.
+  INSTEAD of using a bash 4+ feature implicitly: opt in via explicit shebang line (`#!/usr/bin/env bash` with version check) or fallback shape.
+
+## When this standard fires
+
+| Surface | Check |
+|---|---|
+| New hook in `.claude/hooks/` | All 7 disciplines + shellcheck-clean + sibling test (Tier 0) |
+| New script in `scripts/` | All 7 disciplines + shellcheck-clean (Tier 1) |
+| Edit to existing hook | Same — Phase A's testing-tier hook BLOCKs without test mtime ≤ source mtime |
+| Code review on PR touching `.sh` | Reviewer applies the 7 disciplines |
+| `/security-review` skill invocation | Skill cites this standard for any `.sh` change |
+
+## Refs
+
+- `@luminary saltzer-schroeder` — anchor
+- `@luminary john-ousterhout` — Deep modules framing for hook interface design
+- `@luminary kent-beck` — TDD anchor; Tier 0 strict-TDD discipline applies
+- `standards/code-safety-principles.md` — language-agnostic principles this standard instantiates
+- `.claude/rules/destructive-operations.md` — agent self-assessment companion
+- `.claude/rules/security.md` — web-layer rule (`.ts/.tsx/.json/.env/Dockerfile` scope); this standard extends to bash
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD discipline for hooks
+- `.claude/rules/defensive-bash.md` — companion methodology rule (auto-loaded; points here)
+- `.github/workflows/shellcheck.yml` (Phase X-4) — CI enforcement
+- bassclef#1054 — `log()` quiet-mode bug (strict-mode would have caught at write-time)
+- bassclef#1058 — auto-save scope hole (fail-safe-defaults + least-privilege violation)
+- docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md — goal authoring this standard
+
+## Retirement
+
+This standard retires only if bassclef migrates off bash for its hook implementation language (e.g., adopting Python or Go for hooks). The 7 disciplines themselves remain valid; the language-specific instantiation changes.

package/substrate/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.