@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/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/substrate/standards/writing-guide.md

@@ -0,0 +1,213 @@
+---
+tier: lite
+description: Technical. Direct. For the next agent or session picking up the work.
+---
+
+# Writing Guide — Chronicles & LinkedIn
+
+## Two audiences, two registers
+
+### Chronicles (internal)
+
+Technical. Direct. For the next agent or session picking up the work.
+
+- Name files, functions, skills, hooks by their actual names
+- Include commit refs, issue numbers, file paths
+- Be factual, not promotional — record what happened
+- Open Threads is the most important section
+
+### LinkedIn (external)
+
+Personal. Specific. Story-first. For people who build, invest in, or
+evaluate technology-driven operating models.
+
+---
+
+## LinkedIn Style Guide
+
+### Voice & Tone
+
+First person. Tell the story of what happened. Let the reader draw
+the lesson from the story — don't hand them a pre-digested thesis.
+
+The voice is a builder-operator who has done hard things, learned from
+failures, and shares the specifics openly. Not a consultant summarizing
+from the outside. Not a brand speaking in third person. A person.
+
+The primary voice reference is Sanjay's own writing:
+- "Purpose Has Color" (Medium) — sensory, metaphorical, rooted in
+  lived experience. Santorini blue, Ducor pool, "bluetiful." Charming.
+- "Life Is Too Short to Ship Products That Don't Make a Difference"
+  (Medium) — direct, operational, warm. "Crumple up the stuff that
+  doesn't work, fast." Flywheel as a living thing, not a framework.
+
+These are the anchor. When in doubt, reread them.
+
+Bezos, Jassy, and Collison are secondary references — study how they
+actually write, not the sanitized version LinkedIn thinks they sound
+like. Bezos shareholder letters are full of "we were wrong about this."
+Jassy names the actual service that failed. Collison thinks out loud.
+They share Sanjay's commitment to specificity and naming the real thing.
+But the tone, the warmth, the sensory texture — that's Sanjay's own.
+
+**The sound of it right**:
+- "I built something with three knobs and couldn't remember what two of them did."
+- "Purpose does not charm. Purpose agitates, roils, and compels."
+- "Crumple up the stuff that doesn't work, fast. Build and ship the ones that do, fast."
+- "Charming." (one word, dry, lets the reader smile)
+- "When the person who built the thing can't say what it does without consulting the docs, the thing has a problem."
+
+**The sound of it wrong** (processed cheese — ban these patterns):
+- "Every unnecessary configuration axis in an autonomous system is a governance gap disguised as flexibility." (What does this mean? Who talks like this?)
+- "This taxonomy IS the org chart for your AI workforce." (Thesis statement masquerading as insight)
+- "The most secure, auditable autonomous systems are the ones with the smallest configuration surface." (Corporate whitepaper voice)
+- Any sentence containing: "taxonomy," "governance gap," "ungoverned states," "configuration surface," "enterprise economics," "capital efficiency" as the *point* of the sentence rather than a detail inside a story
+
+### The "Monday morning" test
+
+Read the sentence out loud. Would you say this to a smart friend over
+coffee on a Monday morning? If it sounds like a keynote slide or a
+consulting deck, rewrite it. The friend would interrupt and say "what
+does that actually mean?"
+
+### Story structure, not thesis structure
+
+**Wrong** (thesis-first):
+> Configuration sprawl is governance debt. Every axis you add multiplies
+> the ungoverned states in your system.
+
+**Right** (story-first):
+> I tried to explain my own configuration model on a Monday morning and
+> couldn't. "Standard sequential orchestrator-gated" — what does that
+> even mean? That's when I knew something was wrong.
+
+The thesis can appear — but earned, at the end, after the story makes
+it feel inevitable. Not announced at the top.
+
+### Sentence rhythm
+
+Mix short and long. Short for emphasis. Long when building momentum.
+
+- "So I deleted it." (punchy — the action)
+- "Three axes became two. Twelve combinations became four. The manifest lost a field." (triplet — acceleration)
+- "If I'm steering the session myself, I naturally call in a few agents as needed. If I let the system run itself overnight, it needs the full team. I don't configure that. It just falls out." (longer — builds the logic, then lands)
+
+Avoid: every sentence the same length. Avoid: every paragraph the same
+number of sentences. Rhythm creates feeling. Monotone creates pablum.
+
+### First person, always
+
+Use "I" freely. This is a person writing about things they built and
+broke and learned from. Not a company blog. Not a thought leadership
+platform. A person.
+
+- "I was proud of it for about a week."
+- "I sat with the actual usage."
+- "I was asking myself to decide something the system already knew."
+
+"We" is fine when it genuinely means a team. Never use "we" as a
+corporate "we" that means nobody in particular.
+
+### Metaphors from life, not business school
+
+**Right**: volcanoes, pool water, crayon names, org charts, Monday mornings,
+being unable to explain something to yourself, knobs on a dashboard
+
+**Wrong**: "governance primitives," "coordination frameworks," "configuration
+surfaces," "compliance architectures"
+
+The metaphor should make the reader *see* something. If they have to
+look up the metaphor, it's not a metaphor — it's jargon.
+
+### Technical vocabulary — when to use it
+
+Name real things when they're part of the story: "the manifest,"
+"worktree," "the pre-commit hook," "the boot sequence." These are
+concrete. The reader can picture them.
+
+Don't name abstractions that only exist in your framework: "governance
+substrate," "quality gates," "specification quality." These are labels
+for ideas, and the ideas should be shown through story, not labeled.
+
+**Exception**: If a concept earns its name by being explained through
+a story first, you can name it at the end. "We call this temperance —
+a mandatory pause before the system acts" works because the story
+showed what temperance *is* before naming it.
+
+### What goes in each post
+
+- **What actually happened** — the specific situation, not a category
+- **What went wrong or surprised you** — the tension that makes it a story
+- **What you did about it** — the action, told simply
+- **What it felt like** — the Monday morning confusion, the pride that
+  lasted a week, the "oh" moment when you saw the coupling
+- **The pattern** (earned, at the end) — what someone else might recognize
+  in their own work
+
+### What to leave out
+
+- Thesis statements as openers (earn them)
+- "The key takeaway is..." (the reader gets to decide)
+- Consultant-speak transitions ("Let's examine," "Consider the following")
+- Abstract categories where a specific example would do
+- Sentences that could appear in any company's blog post
+
+### Length
+
+600-1200 words. But only if every paragraph earns its place.
+A 600-word post that tells one story well beats a 1200-word post
+that makes three abstract points.
+
+### Structure
+
+1. **Hook** (1-2 lines) — a specific moment, a confession, something
+   that happened. Not a thesis. Not a question designed to sound profound.
+2. **The story** — what happened, in enough detail that the reader is
+   there with you. Include the wrong turns, the confusion, the feeling.
+3. **The turn** — the moment you saw it differently. This is the heart
+   of the post.
+4. **The pattern** (earned) — what this means beyond your specific
+   situation. Keep it to 2-3 sentences. Trust the reader.
+
+### Two audience variants
+
+Each notable moment can produce two posts:
+
+**Variant A (Board / PE / Search)**: The same story, but land on the
+operating implications. What does this mean for how you run a company,
+evaluate a technology investment, or assess an operator? Use analogies
+to org design, capital allocation, or operational discipline. But still
+tell the story first.
+
+**Variant B (Engineering)**: The same story, with more technical detail.
+Show the code diff, the configuration before and after, the specific
+failure mode. Engineers want to learn something they can apply. But still
+tell the story — engineers hate corporate abstractions even more than
+PE partners do.
+
+### The audience recommendations table
+
+Every draft file includes:
+
+```markdown
+| # | Variant | Title | Primary audience | Hook strength | Publish priority |
+|---|---------|-------|-----------------|--------------|-----------------|
+```
+
+Rate hook strength honestly. "Very strong" = specific, surprising,
+or confessional. "Strongest" = makes the reader stop scrolling.
+"Medium" = solid but expected.
+
+### Feynman Sidebar Convention
+
+When a post references a technical concept that deserves a plain-English
+explanation, flag it:
+
+```
+[FEYNMAN: concept name]
+```
+
+Run /feynman afterward. Weave it in or use it as a comment-thread follow-up.
+The Feynman explanation should sound like you're explaining it to a
+sharp friend who works in a different field — not dumbing it down,
+just making it vivid.

package/substrate/templates/deferred-action-template.md

@@ -0,0 +1,45 @@
+---
+tier: lite
+id: <ISO-ts>-<slug>
+created_by_session: <chronicle-slug>
+created_in: desktop | ephemeral-mobile | ephemeral-ci | cloud-web
+created_at: <ISO-8601 UTC>
+pending_action: <verb-phrase-slug>
+requires_capability: [<capability>, <capability>]
+priority: medium
+origin_skill: /<skill-name>
+resolves_when: |
+  <one-to-two sentences describing the end state>
+---
+
+## Context
+
+<One paragraph. Why was the work deferred? What produced it? Who needs
+it and by when? Enough for a resolver without prior session context to
+understand the gap.>
+
+## Command to execute
+
+<Exact copy-pasteable command, env vars, agent instruction. If
+multi-step, a small checklist. If operator judgment is required,
+state "operator action" and describe what the operator decides.>
+
+```bash
+# example
+npx tsx scripts/push-to-gdoc.ts \
+  --file docs/release-notes/2026-04-20-internal.md \
+  --doc-id "$CHANGELOG_DOC_ID"
+```
+
+## On completion
+
+- [ ] Verify downstream state (e.g., Google Doc shows the pushed content)
+- [ ] `git mv docs/deferred-actions/<id>.md docs/deferred-actions/completed/<id>.md`
+- [ ] `git commit -m "chore: resolve deferred action <id>"`
+- [ ] (Optional) Note resolution in chronicle footnote if scope warrants
+
+## Cross-refs
+
+- <Related PR(s) or issue(s)>
+- <Chronicle entry that originated the deferral>
+- <Memory entries, prior deferred actions, or standards>

package/substrate/templates/whereami-template.md

@@ -0,0 +1,101 @@
+---
+tier: lite
+---
+
+# Whereami — [repo-name]
+
+Current project-state snapshot. Schema: `standards/whereami-schema.md`.
+Read at session-start, updated at session-end. Missing fields render
+as "—" rather than be omitted.
+
+## Project-level phase
+
+phase: [Inception | Elaboration | Construction | Transition]
+note: [one-paragraph description of what this phase means for this repo]
+
+## Active iteration
+
+[Singleton form — sequential mode default]
+iteration_bet: [docs/iteration-bets/YYYY-MM-DD-name.md or "none — between iterations"]
+iteration_started: [YYYY-MM-DD or —]
+iteration_phase: [current WS or stage within the bet, or —]
+previous_bet: [docs/iteration-bets/YYYY-MM-DD-name.md or —]
+next_bet: [one-line description of planned next bet, or —]
+
+[Plural form — parallel mode (Stage 4+); use INSTEAD of singleton when ≥2 bets in flight]
+[iteration_bets:]
+[  - bet: docs/iteration-bets/YYYY-MM-DD-bet-A.md]
+[    started: YYYY-MM-DD]
+[    phase: Phase X]
+[    session: YYYY-MM-DD-session-slug]
+[previous_bet: ...]
+[next_bet: ...]
+
+## Active sessions
+
+[Singleton mode — section may be omitted; or list one entry for the active session]
+[Plural / parallel mode — REQUIRED, one entry per live session]
+active_sessions: []
+
+[Example populated entry:]
+[active_sessions:]
+[  - session_id: YYYY-MM-DD-session-slug]
+[    started: YYYY-MM-DDTHH:MM:SS+0000]
+[    working_dir: /path/to/repo]
+[    agent: orchestrator-gated-sequential | builder | designer | ...]
+[    bet: docs/iteration-bets/YYYY-MM-DD-bet.md]
+[    tier: longrun | short | hotfix]
+
+## Active agents
+
+[sequential mode — typically one entry]
+- [role-name] ([current task])
+
+[multi-agent mode — one entry per active agent]
+- [role-name] on branch [branch-name] ([status])
+
+[between iterations]
+- None (between iterations)
+
+## Subsystem phases
+
+| Subsystem | Phase | Last iteration | Notes |
+|-----------|-------|---------------|-------|
+| [subsystem-1] | [Inception/Elaboration/Construction/Transition] | [YYYY-MM-DD] | [one-line] |
+| [subsystem-2] | [phase] | [YYYY-MM-DD] | [one-line] |
+
+## Gate progress (project-level)
+
+### Inception — [COMPLETE (YYYY-MM-DD) | IN PROGRESS | PENDING]
+- [ ] Vision doc (canvas or equivalent)
+- [ ] Risk register populated
+- [ ] Appetite set
+- [ ] Viability hypothesis written
+- [ ] Build/buy/defer decision
+
+### Elaboration — [status]
+- [ ] Architecture decisions (ADRs)
+- [ ] Standards defined
+- [ ] Design principles established
+- [ ] Object model documented
+
+### Construction — [status]
+- [ ] [repo-specific Construction items]
+
+### Transition — [status]
+- [ ] Production deploy gate configured
+- [ ] Smoke tests green
+- [ ] Release notes published
+- [ ] Chronicle closeout
+
+## Risk register
+
+See docs/risk-register.md
+
+[or if no register yet]
+
+none yet — file when first risk materializes
+
+## Configuration
+
+See substrate.config.md for external resource references.