@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/templates/secret-rotation-template.md

@@ -0,0 +1,162 @@
+---
+tier: lite
+---
+
+# Rotate `<SECRET_NAME>`
+
+Runbook for rotating `<SECRET_NAME>` (purpose: `<one-line>`).
+
+Schema: `standards/state-spine/schemas/substrate-secrets.schema.json`.
+Standard: `standards/secrets-lifecycle.md`.
+
+## When to rotate
+
+- Scheduled: every `<rotation_cadence>` (per `substrate.secrets.md`)
+- Triggered: on suspected leak / vendor migration / role change
+- BLOCKED: session-start hook fires within `<alert_threshold_days>` of expiry
+
+## Pre-flight
+
+- [ ] Confirm you have access to the issuing service's admin console
+- [ ] Confirm you have write access to wherever the secret lives
+  (GitHub Actions Secrets / 1Password / `.env` / AWS Secrets Manager)
+- [ ] Pull a fresh `git pull` of bassclef so your `substrate.secrets.md`
+      is current
+- [ ] Identify all consumers of this secret (grep workflows, scripts,
+      hooks); know what stops working if rotation fails mid-procedure
+
+## Procedure
+
+### 1. Generate the new credential
+
+`<service-specific instructions>`
+
+Examples by storage type:
+
+- **GitHub PAT**: github.com → Settings → Developer settings →
+  Personal access tokens → Fine-grained → Generate. Scope: minimum
+  required (e.g., `Contents: write` + `Pull requests: write` for
+  cross-repo PR creation).
+- **Slack incoming webhook**: api.slack.com/apps → your app →
+  Incoming Webhooks → Add New Webhook to Workspace.
+- **Google OAuth refresh token**: re-run the OAuth consent flow
+  (e.g., `npx tsx scripts/google-oauth-bootstrap.ts`).
+- **AWS access key**: console.aws.amazon.com → IAM → Users → your-user
+  → Security credentials → Create access key. Old key stays valid until
+  explicitly deactivated — overlap rotations.
+
+### 2. Update the storage location
+
+`<storage-type-specific instructions>`
+
+Examples:
+
+- **`github_actions_secret`**: github.com → repo → Settings → Secrets
+  and variables → Actions → Update existing secret. New value takes
+  effect for next workflow run.
+- **`env`** (operator's `.env`): edit `.env` file; restart any running
+  process that reads it (dev server, REPL).
+- **`file`**: replace the file at `<reference>` path; ensure permissions
+  match (typically `0600`).
+- **`1password`**: 1Password app → vault → item → edit → save. Any
+  process using the 1Password CLI picks up new value on next read.
+- **`aws_secrets_manager`**: AWS Console → Secrets Manager → secret
+  → Retrieve secret value → Edit → Save. Code reads via
+  `GetSecretValue` API; cached values may need invalidation.
+
+### 3. Update `substrate.secrets.md`
+
+In the entry for `<SECRET_NAME>`:
+
+```yaml
+last_rotated: YYYY-MM-DD     # today
+expires_at: YYYY-MM-DD       # today + rotation_cadence
+```
+
+Commit this update with a small commit:
+
+```bash
+git add substrate.secrets.md
+git commit -m "chore: rotate <SECRET_NAME> — last_rotated + expires_at updated"
+git push
+```
+
+### 4. Verify
+
+Run the status script:
+
+```bash
+bash scripts/secrets-status.sh
+```
+
+The entry should show `✅ OK` with the new `Days` value (close to the
+full cadence in days).
+
+If the secret has a `health_check_command`, run with `--health-check`:
+
+```bash
+bash scripts/secrets-status.sh --health-check
+```
+
+The corresponding `[health: ✓]` should appear.
+
+### 5. Confirm downstream consumers still work
+
+`<test-specific instructions>`
+
+Examples:
+
+- **Slack webhook**: trigger a workflow that posts (e.g., merge a small
+  PR); verify Slack receives the message
+- **GitHub PAT**: trigger a cross-repo workflow; verify PR opens in the
+  consumer repo
+- **Google OAuth**: run `npx tsx ~/src/sunj-labs/poa/scripts/push-to-gdoc.ts --auth-check`
+- **Anthropic API key**: send a test API request via curl
+
+### 6. Revoke the old credential (when applicable)
+
+For credentials that overlap (e.g., AWS access keys), explicitly
+revoke / deactivate the old credential after the new one is verified.
+
+## What might break
+
+`<failure-mode-specific notes>`
+
+Examples:
+
+- **Slack webhook rotation**: any workflow run that fired between the
+  old webhook becoming invalid and the secret update will silently
+  drop messages. Consider rotating during low-activity windows.
+- **GitHub PAT rotation**: cross-repo PRs in flight may need to be
+  re-opened / re-triggered if the workflow run consumed the old token.
+- **Google OAuth refresh token**: the bootstrap flow may surface a
+  "Verify your account" prompt; complete it before tokenizing.
+- **AWS keys**: cached credentials in long-running processes (CI
+  runners, serverless functions) may keep using the old key until
+  cycled.
+
+## Rollback
+
+If the new credential doesn't work:
+
+1. Restore the old credential to the storage location
+2. Revert the `substrate.secrets.md` update
+3. Diagnose: was the new credential generated correctly? Was it
+   pasted with whitespace? Does the issuing service have a
+   propagation delay (some do)?
+4. Once diagnosed: re-attempt rotation OR file an incident-report
+   if the failure mode is novel
+
+## When the runbook itself breaks
+
+If these instructions stop working (e.g., service redesign, deprecated
+API), update this runbook in the same PR that handles the rotation.
+The runbook must stay current — a stale runbook is the same operational
+debt that motivated this whole tracking system.
+
+## Composes with
+
+- `standards/secrets-lifecycle.md` — schema + field reference
+- `scripts/secrets-status.sh` — status verification
+- `.claude/hooks/session-reflection.d/90-secrets-expiry.sh` — alert
+  surface that drives rotation cadence

package/substrate/templates/spec-template.md

@@ -0,0 +1,131 @@
+---
+tier: lite
+---
+
+# SPEC-NNN: [Feature Name]
+
+## Canvas Reference
+Link to product canvas or PR/FAQ.
+
+## Context
+Why now? What triggered this work?
+
+## Requirements
+### Must Have
+- ...
+### Should Have
+- ...
+### Won't Have (this version)
+- ...
+
+## Design
+### User Flow
+Step-by-step, what the user (or system) does.
+
+### Object Model
+What are the core objects? How do they relate?
+(Define objects, not screens.)
+
+### Interface
+Wireframe, CLI spec, API contract — whatever's appropriate.
+
+## Technical Approach
+Architecture, dependencies, risks.
+
+## Patterns Used
+
+(Required when spec drives Construction work. Maps named patterns from bassclef's catalog to where they'll be implemented. Pairs with `@pattern` annotations in code per `.claude/rules/pattern-annotation.md`. Layer 2 of bassclef#478 traceability.)
+
+| Pattern | Catalog path | Implementing file/class | Why this pattern |
+|---------|--------------|--------------------------|------------------|
+| <Name> | `patterns/<shelf>/<source>/<slug>.md` | `src/.../<file>.ts` :: `<ClassName>` | <one-line rationale> |
+
+If a needed pattern has no catalog entry yet, file `/agent-research-spawn` to add it, then update this table. Don't fabricate catalog paths.
+
+If the spec has no conscious pattern choices (e.g., a one-line config edit), state "No load-bearing patterns" — silence is not exemption.
+
+## Deployment & Access Architecture
+
+Answer these before writing code. The answers determine your deployment tier,
+networking, auth, and domain strategy.
+
+### Who accesses this?
+
+| Question | Answer |
+|----------|--------|
+| Is this operator/team-only (internal)? | yes / no |
+| Will trusted external people use it (partners, clients)? | yes / no |
+| Will the public use it (customers, strangers)? | yes / no |
+| Does access need to work from outside the corporate network / VPN? | yes / no |
+
+### What does it need?
+
+| Question | Answer |
+|----------|--------|
+| Does it persist data (database, filesystem)? | yes / no |
+| Does it handle secrets server-side (API keys, OAuth tokens)? | yes / no |
+| Does it need SSR or API routes? | yes / no |
+| Does it call other internal services? | yes / no |
+| Does it need auth (login, user accounts, SSO)? | yes / no |
+
+### Deployment decision
+
+Based on the answers above:
+
+| Condition | Tier |
+|-----------|------|
+| Internal-only, no persistence, validating UI | **Mockup** (prototype, local dev, design tool) |
+| Needs a shareable link, still mock data, no backend | **Staging** (static hosting, internal CDN) |
+| Any "yes" to persistence, secrets, SSR, or service calls | **Production** (full deployment to your infra) |
+| Public users outside corporate network | **Production + edge** (CDN, TLS, public domain) |
+
+### If public-facing, additionally answer:
+
+| Question | Answer |
+|----------|--------|
+| Domain name? | |
+| TLS strategy? | |
+| Auth provider? (OAuth, SSO, magic link, none?) | |
+| Rate limiting needed? | yes / no |
+| Do we need a public status page? | yes / no |
+| GDPR / data handling implications? | |
+
+### Monitoring
+
+| Question | Answer |
+|----------|--------|
+| Healthcheck endpoint path? | `/health` or specify |
+| Add to infrastructure monitoring? | yes / no |
+| LLM/AI observability needed? | yes / no |
+| Cost controls relevant? | yes / no |
+
+## Acceptance Criteria
+How we know it's done. Testable statements.
+
+## Workunits enumerated
+
+REQUIRED for specs that feed `/build` (bassclef#335 + bassclef#367).
+Each WU traces to one INVEST user story and lands as one stacked-atomic
+PR. /build's Phase 1 parser greps for this exact section heading.
+
+Format (one entry per WU):
+
+```markdown
+### WU-N — <imperative title>
+
+**Story refs:** US-NNN[, US-NNN]
+**Branch:** feature/<bet-slug>-stack-N-<wu-slug>
+**Acceptance:**
+- [ ] <inherited from story; testable; observable>
+- [ ] <edge case / extension>
+**Estimated:** ~Nt turns
+
+(per /preview-build Phase 9 contract per bassclef#367)
+```
+
+If the spec doesn't feed `/build` (e.g., bassclef-evolution shaping
+specs, design specs, methodology specs), this section is optional —
+include a brief note explaining why it's omitted.
+
+## Open Questions
+Things we don't know yet.

package/substrate/templates/use-case-template.md

@@ -0,0 +1,194 @@
+---
+tier: lite
+---
+
+# UC-NNN — [imperative goal title]
+
+<!--
+Template for a Cockburn fully-dressed use case.
+See standards/use-case-format.md for the schema + validation rules.
+See .claude/skills/use-case/SKILL.md for the procedure.
+
+Replace NNN with a zero-padded 3-digit number.
+Title is imperative, no period (e.g., "Sign in with email and password").
+Delete all <!-- comment -- > blocks before committing.
+-->
+
+- **Primary actor**: [persona-slug]
+- **Goal level**: 🎯 user-goal
+  <!-- ☁️ summary (multi-session) | 🎯 user-goal (single session, default) | 🐟 subfunction (reused by ≥2 use cases) -->
+- **Scope**: [system-under-design]
+- **Status**: draft
+- **Last validated**: YYYY-MM-DD
+
+## Stakeholders + interests
+
+<!-- At least 2 NON-ACTOR stakeholders required (beyond primary actor).
+     Examples: Compliance, Ops, Support, Billing, Legal, Security, Partners.
+     Each row feeds /decompose's -ility audit — cross-cutting concerns
+     that would otherwise get bolted into implementations later. -->
+
+| Stakeholder | Interest |
+|-------------|----------|
+| [stakeholder] | [what they want to be true about this goal's execution] |
+| [stakeholder] | [...] |
+
+## Preconditions
+
+<!-- Checkable state invariants the use case assumes on entry.
+     "The system is running" is throat-clearing, not a precondition.
+     Valid: "account exists," "user authenticated," "quota below limit." -->
+
+- [state invariant 1]
+- [state invariant 2]
+
+## Minimal guarantees
+
+<!-- What's true after ANY exit (success or extension).
+     Typically: audit logging, state consistency, no secret leakage. -->
+
+- [invariant that holds on any exit]
+
+## Success guarantees
+
+<!-- What's true on successful completion only. -->
+
+- [invariant that holds on success]
+
+## Trigger
+
+<!-- The specific event (actor action, scheduled event, external signal) that starts the flow. -->
+
+- [triggering event]
+
+## Main success scenario
+
+<!-- Numbered list, 3-9 steps, alternating actor↔system.
+     No implementation language ("system calls Postgres" ❌ — say "system retrieves X").
+     >9 steps = split into subfunction use case(s). -->
+
+1. [Actor does X]
+2. [System responds with Y]
+3. [Actor does Z]
+4. [System does W]
+5. [...]
+
+## Extensions
+
+<!-- EVERY step in main scenario MUST have at least one extension considered,
+     OR an explicit line: "*No extensions — [reason]*". Silence is failure.
+
+     Format: Na (step number + letter). Sub-steps: Na1, Na2, Na3.
+
+     Enumeration prompts (Cockburn):
+     1. What if actor input is invalid?
+     2. What if system can't complete step (timeout, dependency, resource)?
+     3. What if precondition silently broke?
+     4. What if actor abandons partway?
+     5. What if concurrent actor changed state?
+-->
+
+- **Na. [condition at step N]**:
+  - Na1. [recovery step 1]
+  - Na2. [recovery step 2]
+  - Na3. Use case ends with [outcome].
+
+- **Nb. [another condition at step N]**:
+  - Nb1. [...]
+  - Nb2. Use case ends with [outcome].
+
+- **Ma. [condition at step M]**:
+  - Ma1. [...]
+
+## Technology / data variations (optional)
+
+<!-- Use when the same logical step has multiple implementation paths
+     with different -ility characteristics. Feeds /decompose with variation
+     points needing Strategy pattern. Omit if not applicable. -->
+
+- *Step N*: [alternative mechanism] — [when used]
+
+## Related information
+
+- **Non-functional requirements**: [rate limits, latency SLOs, accessibility, etc.]
+- **References**: [specs, ADRs, canvases, external docs]
+- **Sliced by stories**: [US-NNN, US-NNN, ...]
+- **JTBD traceability**: [J-N — job-statement]
+- **VPC traceability** (if applicable): [PR-N or GC-N — item]
+
+---
+
+## Worked example — sign in with email and password
+
+<!-- Keep this worked example in the template for reference;
+     /use-case skill strips it when emitting a new file. -->
+
+# UC-001 — Sign in with email and password
+
+- **Primary actor**: cofounder-pair
+- **Goal level**: 🎯 user-goal
+- **Scope**: POA web UI + auth service
+- **Status**: accepted
+- **Last validated**: 2026-04-21
+
+## Stakeholders + interests
+
+| Stakeholder | Interest |
+|-------------|----------|
+| Compliance | Every attempt logged with IP + user-agent |
+| Ops | No password or partial hash leaks into logs |
+| Support | Failed-auth reason visible in support tool (not actor) |
+| Billing | Successful auth increments MAU counter |
+
+## Preconditions
+
+- cofounder-pair account exists in the user table
+- Password has been set (not null)
+
+## Minimal guarantees
+
+- Audit log entry written with timestamp + outcome + user-ID (or null for failed lookup)
+- No password or hash value written to logs
+
+## Success guarantees
+
+- Valid session cookie issued with 24h TTL
+- MAU counter incremented for the actor's tenant
+
+## Trigger
+
+- Actor submits email + password form
+
+## Main success scenario
+
+1. Actor submits email + password.
+2. System looks up account by email.
+3. System verifies password against stored hash.
+4. System issues session cookie with 24h TTL.
+5. System redirects to post-auth landing page.
+
+## Extensions
+
+- **2a. Email not found**:
+  - 2a1. System displays generic "Invalid credentials" (no user enumeration).
+  - 2a2. Audit log entry written with null user-ID.
+  - 2a3. Use case ends with actor unauthenticated.
+- **3a. Password mismatch**:
+  - 3a1. System displays generic "Invalid credentials."
+  - 3a2. Audit log entry written with user-ID + "pw-mismatch" reason.
+  - 3a3. Use case ends with actor unauthenticated.
+- **3b. Account locked (rate-limit exceeded)**:
+  - 3b1. System displays "Account temporarily locked — try again in N minutes."
+  - 3b2. Audit log entry written with "lockout" reason.
+  - 3b3. Use case ends with actor unauthenticated.
+- **4a. Session issue fails (transient)**:
+  - 4a1. System displays "Try again" error.
+  - 4a2. Audit log written with "session-issue-failure" + error code.
+  - 4a3. Use case ends with actor unauthenticated.
+
+## Related information
+
+- **Non-functional requirements**: p95 auth latency <500ms; rate-limit 5 attempts per email per 15min
+- **References**: ADR-003 session management, standards/security.md
+- **Sliced by stories**: US-001 (happy path), US-002 (rate limit UX), US-003 (audit log)
+- **JTBD traceability**: J1 — "Sign in quickly without re-typing credentials on every session"

package/substrate/templates/user-story-template.md

@@ -0,0 +1,107 @@
+---
+tier: lite
+---
+
+# US-NNN — [Imperative title — what the persona accomplishes]
+
+<!--
+  Bassclef user story template. INVEST-shaped per
+  standards/user-story-invest.md. Produced by /user-stories skill.
+
+  Save location:
+    Per-story: docs/user-stories/US-NNN-[slug].md (preferred —
+               granular Git history, easier review)
+    Batch:     docs/user-stories/[iteration-slug].md (acceptable
+               for small iterations or bulk import)
+
+  Filename basename MUST match the US-NNN ID.
+
+  Delete this comment block after copy-paste.
+-->
+
+**ID**: US-NNN
+**Iteration**: [iteration-bet path or slug]
+**Status**: new | refined | in-progress | done | killed
+**INVEST**: PASS | PASS-WARN | WARN | FAIL (computed by /user-stories validate)
+**Estimate**: [story points / t-shirt / hours — team convention]
+
+---
+
+## Story
+
+**As a** [persona slug — e.g., `couple-founders`, NOT "user"]
+**I want to** [observable, testable outcome — what the persona does or experiences, NOT internal mechanism]
+**So that** [benefit grounded in VPC entry or JTBD outcome]
+
+---
+
+## Traceability
+
+<!--
+  REQUIRED: Persona + JTBD. SHOULD: VPC + use-case (when present).
+  Stories without JTBD trace are red flags per
+  standards/user-story-invest.md.
+-->
+
+- **Persona**: [slug] — `docs/personas/[slug].md`
+- **JTBD**: [J-N: job statement] — `docs/design/personas/[persona]/jtbds.md#J-N`
+- **VPC entry** (when present): [PR-N or GC-N] — `docs/value-prop-canvas/[persona].md`
+- **Use-case line** (when /use-case exists): [UC-N step Xa] — `docs/use-cases/[uc-slug].md`
+
+---
+
+## Acceptance criteria
+
+<!--
+  Each criterion = one test assertion. Concrete, observable,
+  threshold-bearing where applicable. NOT "works well" / "is intuitive".
+  Cover happy path + at least one edge / non-functional concern.
+-->
+
+- [ ] [Observable behavior — written as a test assertion]
+- [ ] [Edge case from CTA decision points or use-case extension]
+- [ ] [Non-functional concern when applicable: performance threshold, accessibility, error handling]
+
+---
+
+## INVEST self-check
+
+<!--
+  Each letter answered briefly. Validate with /user-stories validate.
+  Failing one letter = WARN; failing multiple = FAIL.
+-->
+
+- **I** (Independent): [why this story can ship without other stories shipping first]
+- **N** (Negotiable): [what's flexible in implementation vs. what's fixed]
+- **V** (Valuable): [observable value to the named persona — not internal/refactor value]
+- **E** (Estimable): [team can estimate within ~30 min refinement]
+- **S** (Small): [fits in one iteration / sprint — typically 1-5 days]
+- **T** (Testable): [acceptance criteria are concrete, observable, automatable]
+
+---
+
+## Notes
+
+<!--
+  Optional. Conversation log, open questions, deferred decisions,
+  rejection criteria. Stories are conversation tokens — capture the
+  conversation here.
+-->
+
+- [Open question for refinement]
+- [Deferred decision]
+- [Constraint discovered during discussion]
+
+---
+
+## Splits / dependencies
+
+<!--
+  Optional. If this story was split from a larger one, name the parent.
+  If it has acceptable dependencies (infrastructure already in place),
+  surface them.
+-->
+
+- **Split from**: US-NNN (if applicable)
+- **Splits to**: [if this is the parent of others]
+- **Acceptable dependencies**: [infrastructure / platform reality — NOT story dependencies]

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.