@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/standards/whereami-schema.md

@@ -0,0 +1,301 @@
+---
+tier: lite
+description: docs/whereami.md is the authoritative project-state snapshot in any bassclef-substrate repo.
+---
+
+# Whereami Schema
+
+`docs/whereami.md` is the **authoritative project-state snapshot** in
+any bassclef-substrate repo. One per repo, maintained at session-end,
+read at session-start. Functionally it is the current-state header —
+whereas `docs/iteration-bets/` holds the goal.contracts and `chronicle/`
+holds the narrative log, `whereami.md` answers "where is the project
+right now?" in one glance.
+
+## Why this exists
+
+Before this standard: each agent reconstructed project state by
+reading iteration-bets + chronicles + git log + substrate.config.md
+at session-start. This reconstruction:
+
+- Duplicates ~5 reads per session-start
+- Drifts silently when phase or iteration changes without cross-artifact
+  updates
+- Produces inconsistent answers to "what phase are we in?" depending on
+  which agent asked and which files it read
+
+Making whereami load-bearing solves all three by establishing one
+source, maintained at session boundaries.
+
+## The artifact
+
+Location: `docs/whereami.md` (every consumer repo). Bassclef itself
+maintains one at the same path.
+
+Format: Markdown with a standard structure (schema below). Plain prose
+allowed in descriptive fields. No YAML frontmatter — simpler to eyeball.
+
+## Schema
+
+Nine sections, in this order. Missing fields acceptable when no data
+exists yet (new repo, no active iteration); empty sections MUST render
+as "—" rather than be omitted, so the reader knows what's unset vs. what
+was forgotten.
+
+Section 2a (Active sessions registry) is OPTIONAL in singleton mode and
+REQUIRED in plural / parallel mode. Section count is "8 + optional 1."
+
+### 1. Project-level phase
+
+```markdown
+## Project-level phase
+
+phase: [Inception | Elaboration | Construction | Transition]
+note: [one-paragraph description of what this phase means for this repo]
+```
+
+Bassclef values only. If you're tempted to write a custom phase, the
+project is either between standard phases (write "Construction, tail
+end of iteration X") or the phase model doesn't fit (surface as a
+bassclef-evolution proposal, don't invent a value).
+
+### 2. Active iteration
+
+Two shapes — singleton (sequential mode, one goal at a time) and plural
+(parallel mode, multiple bets in flight on the same repo). Singleton is
+the bassclef default; plural is the parallel-fanout extension (Phase
+A WS-2 of example-pipeline bet).
+
+#### Singleton (default — sequential mode)
+
+```markdown
+## Active iteration
+
+iteration_bet: [path to current bet, or "none — between iterations"]
+iteration_started: [YYYY-MM-DD]
+iteration_phase: [current WS or stage within the goal. or "—"]
+previous_bet: [path to last closed bet]
+next_bet: [one-line description of planned next bet, or "—"]
+```
+
+If `iteration_bet` is "none," `iteration_phase` MUST be "—".
+
+#### Plural (parallel mode — Stage 4+)
+
+```markdown
+## Active iteration
+
+iteration_bets:
+  - bet: docs/iteration-bets/2026-04-25-example-pipeline.md
+    started: 2026-04-25
+    phase: Phase A
+    session: 2026-04-26-phase-a-autonomous
+  - bet: docs/iteration-bets/2026-04-26-quorum-prototype-gallery.md
+    started: 2026-04-26
+    phase: WS-1
+    session: 2026-04-26-quorum-wire
+previous_bet: [path to last closed bet]
+next_bet: [one-line description of planned next bet, or "—"]
+```
+
+**Backward-compatibility window**: readers MUST accept BOTH the
+singleton field (`iteration_bet:`) AND the plural field
+(`iteration_bets:`). Writers in sequential mode SHOULD continue using
+the singleton form. The plural form activates when ≥2 bets are
+in-flight against the same repo — typically via worktree-based
+parallel sessions. Plural form deprecates singleton 30 days after
+parallel-mode adoption stabilizes; until then both are valid.
+
+### 2a. Active sessions registry (parallel mode)
+
+```markdown
+## Active sessions
+
+active_sessions:
+  - session_id: 2026-04-26-phase-a-autonomous
+    started: 2026-04-26T01:00:00+0000
+    working_dir: /Users/<operator>/src/<org>/bassclef
+    agent: orchestrator-gated-sequential
+    bet: docs/iteration-bets/2026-04-25-example-pipeline.md
+    tier: longrun
+  - session_id: 2026-04-26-quorum-wire
+    started: 2026-04-26T02:30:00+0000
+    working_dir: /Users/<operator>/src/<org>/bassclef-quorum-worktree
+    agent: builder
+    bet: docs/iteration-bets/2026-04-26-quorum-prototype-gallery.md
+    tier: short
+```
+
+Empty when only one session is active (singleton mode). Each session
+appends an entry at `/longrun prep` and removes its entry at
+`/longrun closeout`. Stale entries (session_id has no live process
+AND age > 24h) are reaped by `bassclef-sync.sh` session-start hook.
+
+The session-id MUST match the session-board filename slug (per
+`standards/session-board.md`) so cross-references resolve cleanly.
+
+### 3. Active agents
+
+```markdown
+## Active agents
+
+[sequential mode]
+- [role-name] ([current task])
+
+[multi-agent mode]
+- [role-name] on branch [branch-name] ([status])
+```
+
+For sequential sessions, typically one entry. For multi-agent /
+multi-worktree sessions, one entry per active agent. If between
+iterations: "None (between iterations)".
+
+### 4. Subsystem phases (table)
+
+```markdown
+## Subsystem phases
+
+| Subsystem | Phase | Last iteration | Notes |
+|-----------|-------|---------------|-------|
+| [name] | [phase] | [YYYY-MM-DD] | [one-line] |
+```
+
+Subsystems are the repo's own decomposition — in bassclef, these are
+standards / skills / agents / SDLC-process / session-continuity /
+design-system. Each consumer repo defines its own list.
+
+### 5. Gate progress (project-level)
+
+```markdown
+## Gate progress (project-level)
+
+### Inception — [COMPLETE (YYYY-MM-DD) | IN PROGRESS | PENDING]
+- [x] Vision doc
+- [x] Risk register populated
+...
+
+### Elaboration — [status]
+- [ ] ADRs drafted
+...
+
+### Construction — [status]
+...
+
+### Transition — [status]
+...
+```
+
+Checkbox format. Gate items are repo-specific. Bassclef values
+only for phase status: COMPLETE / IN PROGRESS / PENDING.
+
+### 6. Risk register
+
+```markdown
+## Risk register
+
+See docs/risk-register.md
+```
+
+One-line pointer. The register itself is a separate artifact; this
+field just establishes the reference. If no register exists, write
+"none yet — file when first risk materializes."
+
+### 7. Last updated (MUST)
+
+```markdown
+## Last updated
+
+2026-04-16T19:00:00Z — session-end
+session: [chronicle filename, e.g., 2026-04-16c-plan-declaration-and-whereami.md]
+```
+
+ISO 8601 UTC timestamp. Auto-stamped by `/session-end` skill when it
+updates whereami. Hook-read to detect staleness.
+
+### 8. Configuration pointer
+
+```markdown
+## Configuration
+
+See substrate.config.md for external resource references.
+```
+
+One-line pointer. Decouples state tracking (whereami) from resource
+references (substrate.config.md) — both are single-source but for
+different concerns.
+
+## Freshness rules
+
+Hook-enforced via `bassclef-sync.sh` section emitted on session-start:
+
+- `last_updated` newer than 3 days → green, session proceeds normally
+- `last_updated` 3–7 days old → warning surfaced, session proceeds
+- `last_updated` older than 7 days → BLOCKED (per `blocked-items.md`)
+- File missing → BLOCKED
+
+Threshold is tuneable. 3 days v1 default. Consumer repos may override
+via `substrate.config.md` field (proposed: `whereami_freshness_days`).
+
+## Who updates it
+
+| Trigger | Who | Action |
+|---------|-----|--------|
+| Session end | `/session-end` skill (MUST tier) | Update last_updated + any field that changed |
+| Phase transition | Closer / operator | Update phase + gate progress |
+| Iteration start | `/autonomous start` or equivalent | Update iteration_bet + active agents |
+| Iteration end | `/session-end` + closeout | Update previous_bet; clear iteration_phase |
+| Subsystem change | Agent performing the change | Update subsystem row with one-line + date |
+
+## Who reads it
+
+| Reader | When | What it expects |
+|--------|------|-----------------|
+| `/sprint` skill | Session-start orientation | Primary source (no longer fallback) |
+| `bassclef-sync.sh` hook | Session-start | Freshness check only |
+| `/substrate-check` skill | On-demand validation | Presence + schema conformance |
+| Operator eyeballing | Any time | Human-readable summary |
+| Chronicle writer | Session-end | Phase context for narrative |
+
+## What whereami is NOT
+
+- **Not the iteration goal** — iteration goal is the scope contract for
+  the current work; whereami references it by path
+- **Not the chronicle** — chronicle is retrospective narrative;
+  whereami is current snapshot
+- **Not substrate.config.md** — that file is resource references
+  (where is X); whereami is state (where are we)
+- **Not a risk register** — register is a separate artifact; whereami
+  points to it
+- **Not an ADR log** — ADRs are decisions; whereami is state
+- **Not `/sprint` output** — `/sprint` READS whereami; it doesn't
+  replace it
+
+## Relationship to other standards
+
+- `standards/substrate-config-schema.md` — same single-source-of-truth
+  pattern, different concern (resources vs. state)
+- `strategy/session-continuity.md` — three-layer memory architecture
+  where whereami is the "current state" layer
+- `strategy/agent-choreography.md` — which agent updates whereami at
+  which gate is defined here
+- `.claude/rules/whereami-load-bearing.md` — enforces read + write
+  obligations per session
+
+## Template
+
+See `templates/whereami-template.md` for a fillable starting
+point. `/autonomous start` creates one when scaffolding a new repo.
+
+## Scrutiny
+
+Bar for adding a schema: the artifact must have load-bearing behavior
+elsewhere in the methodology, or it's documentation for documentation's
+sake. Whereami meets the bar because:
+
+1. `/sprint` will read it as primary source (not fallback)
+2. `bassclef-sync.sh` will block on staleness
+3. `/session-end` will write to it as MUST tier
+4. `/substrate-check` will validate its shape
+
+Without those four hooks, this standard would be shelfware. Ship the
+hooks with the schema.

package/dist/lite/standards/worktree-management.md

@@ -0,0 +1,211 @@
+---
+tier: lite
+description: Defines the lifecycle for git worktrees in autonomous agent sessions.
+---
+
+# Worktree Management Standard
+
+Defines the lifecycle for git worktrees in autonomous agent sessions.
+Worktrees enable parallel branch work but create operational hazards when
+agents crash, hit rate limits, or exhaust context without cleanup.
+
+This standard applies whenever agents use `git worktree add` — whether
+in parallel autonomous mode or manual multi-branch work.
+
+---
+
+## Worktree Lifecycle
+
+```
+CREATE → WORK → COMMIT → PR → CLEANUP
+```
+
+Every worktree must complete this lifecycle. A worktree that skips CLEANUP
+leaves a branch lock, consumes disk, and confuses the next session.
+
+---
+
+## Pre-Session Audit (MUST — session start)
+
+Before creating any new worktrees, audit existing ones:
+
+```bash
+git worktree list
+```
+
+For each worktree that is not the main working tree:
+
+1. **Check if prunable**: `git worktree list` shows `prunable` for worktrees
+   whose directory no longer exists
+2. **Check age**: if the worktree is from a previous session (different date
+   or session ID), it is stale
+3. **Check for uncommitted work**: `git -C <worktree-path> status` — if dirty,
+   the previous agent died mid-work
+
+### Stale worktree resolution
+
+| State | Action |
+|-------|--------|
+| Prunable (directory gone) | `git worktree prune` — safe, just cleans metadata |
+| Clean (no uncommitted changes) | `git worktree remove <path>` — safe to remove |
+| Dirty (uncommitted changes) | Commit as `chore: wip — recovered from stale worktree`, then remove |
+| Branch has open PR | Remove worktree, leave PR open for review |
+| Branch has no PR and no useful commits | Remove worktree, delete branch |
+
+Present stale worktrees to the operator at session start. In orchestrator-gated
+mode, auto-clean prunable and clean worktrees; prompt for dirty ones.
+
+The session-start hook should surface stale worktrees. If it doesn't, the
+agent checks manually.
+
+---
+
+## Creating Worktrees
+
+### Naming convention
+
+```
+.claude/worktrees/<slug>
+```
+
+Where `<slug>` matches the branch's short description. Example:
+`feature/100-stack-1-worktree-mgmt` → `.claude/worktrees/worktree-mgmt`
+
+### Creation checklist
+
+1. Verify the branch doesn't already exist: `git branch --list <name>`
+2. Create from main (not from another worktree's branch):
+   ```bash
+   git worktree add .claude/worktrees/<slug> -b <branch-name>
+   ```
+3. Record the worktree in the stack manifest if one exists
+4. Never `cd` into the worktree — use `git -C <path>` for all operations
+
+### Why never `cd` into a worktree
+
+If the agent's working directory is inside a worktree and the worktree is
+removed (by cleanup, crash recovery, or another agent), the shell's cwd
+becomes invalid. All subsequent commands fail with "Unable to read current
+working directory." This was observed in POA parallel run 2026-04-07.
+
+Instead:
+```bash
+# Good — run from main working tree
+git -C .claude/worktrees/my-feature add .
+git -C .claude/worktrees/my-feature commit -m "feat: description"
+
+# Bad — changes cwd, creates cleanup hazard
+cd .claude/worktrees/my-feature
+git add .
+```
+
+---
+
+## File Watcher Conflicts
+
+### Problem
+
+Dev servers (Next.js, Vite), linters (ESLint watch mode), formatters
+(Prettier watch), and IDE file sync tools monitor the filesystem. When a
+worktree agent writes a file, watchers may:
+
+- Revert the file to their cached state
+- Trigger a rebuild that overwrites agent output
+- Lock files that the agent needs to write
+
+### Mitigation
+
+Before creating worktrees for parallel work:
+
+1. **Stop all file watchers**: dev server, lint --watch, test --watch
+2. **Check for processes holding files**:
+   ```bash
+   lsof +D <worktree-path> 2>/dev/null
+   ```
+3. **If watchers can't be stopped** (e.g., IDE integration), document in
+   the stack manifest that this branch is not parallel-safe
+
+The `/autonomous start` boot sequence should check for running dev servers
+and warn before spawning parallel agents.
+
+### IDE-specific notes
+
+- **VS Code**: File watcher is aggressive. If the worktree is inside the
+  project directory (which `.claude/worktrees/` is), VS Code will watch it.
+  Consider creating worktrees outside the project directory for parallel runs.
+- **Cursor/JetBrains**: Similar behavior. Same mitigation.
+
+---
+
+## Cleanup Protocol (MUST — before session end)
+
+Every agent that creates a worktree MUST clean it up before exiting.
+This is part of the graceful exit protocol (see `standards/graceful-exit.md`).
+
+### Normal cleanup (work complete, PR open)
+
+```bash
+git worktree remove .claude/worktrees/<slug>
+```
+
+If the branch was merged, also delete the branch:
+```bash
+git branch -d <branch-name>
+```
+
+### Abnormal cleanup (agent dying, context exhaustion)
+
+If the agent knows it's about to die (context pressure, rate limit, budget):
+
+1. Commit any in-progress work: `git -C <worktree-path> commit -am "chore: wip"`
+2. Push the branch: `git -C <worktree-path> push -u origin <branch>`
+3. Remove the worktree: `git worktree remove <path>`
+4. Note in checkpoint: "worktree cleaned, branch pushed, PR not yet open"
+
+If the agent dies without cleanup (crash, kill, timeout), the next session's
+pre-session audit handles recovery.
+
+### Cleanup order
+
+When multiple worktrees exist:
+
+1. Remove worktrees with merged PRs first (safest)
+2. Remove worktrees with open PRs next (work is preserved in the PR)
+3. Remove worktrees with unpushed work last (commit and push first)
+
+---
+
+## Rate Limit Awareness
+
+Parallel worktree agents multiply API request rate against the same account
+quota. This was observed in POA 2026-04-07: 3 agents = 3x RPM pressure,
+causing 429 errors.
+
+### Mitigations
+
+| Strategy | When to use |
+|----------|------------|
+| Sequential mode | Default. Zero rate limit risk. Recommended for most work. |
+| Staggered starts | If parallel: delay 30s between agent spawns |
+| Reduced context | Send only relevant files to each agent, not full repo |
+| Fewer parallel agents | Max 2 concurrent for most account tiers |
+
+### Rate limit detection
+
+If an agent receives a 429 or rate limit error:
+
+1. Do NOT retry immediately — this makes it worse
+2. Wait the duration specified in the Retry-After header (or 60s default)
+3. If rate limits persist after 3 retries: save state, report to operator,
+   recommend switching to sequential mode
+
+---
+
+## Relationship to Other Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `standards/graceful-exit.md` | Worktree cleanup is a MUST gate in exit protocol |
+| `standards/branch-stacking.md` | Stack manifest tracks worktree branches |
+| `.claude/rules/cost-governance.md` | Rate limit cost of parallel worktrees |
+| `strategy/agent-choreography.md` | Orchestrator manages worktree lifecycle in parallel mode |