@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/standards/whereami-schema.md

@@ -1,301 +0,0 @@
----
-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/substrate/standards/worktree-management.md

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