@thebassclef/lite 0.1.3 → 1.0.1

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

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

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

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

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

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