@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/templates/memory-proposal-template.md

@@ -0,0 +1,77 @@
+---
+tier: lite
+id: <ISO-ts>-memory-<topic-slug>
+created_by_session: <chronicle-slug>
+created_in: ephemeral-mobile | cloud-web
+created_at: <ISO-8601 UTC>
+pending_action: apply-memory-proposal
+requires_capability: [memory-write]
+priority: medium
+origin_skill: /<skill-that-proposed-it>
+resolves_when: |
+  Proposed memory file exists at the target path and MEMORY.md index
+  references it. Proposal file git mv'd to
+  docs/deferred-actions/completed/.
+---
+
+## Context
+
+Mobile or cloud-web session identified a memory entry worth adding
+but couldn't write to `~/.claude/projects/.../memory/` (ephemeral
+sandboxes lack filesystem access to the operator's real home).
+
+Surface the proposal here; a capable desktop session reviews and
+applies it per the Command section below.
+
+## Proposed memory entry
+
+**Target path**: `~/.claude/projects/<project>/memory/<category>_<topic>.md`
+
+**Frontmatter + body** (copy-paste into the target file verbatim):
+
+```markdown
+---
+name: <one-line title>
+description: <one-line description for MEMORY.md index>
+type: <user | feedback | project | reference>
+---
+
+<memory content — follow the auto memory guide's structure for this type:
+- user: role, preferences, responsibilities, knowledge
+- feedback: rule + Why + How to apply
+- project: fact/decision + Why + How to apply
+- reference: pointer to external resource + purpose>
+```
+
+**MEMORY.md index line to append**:
+
+```
+- [<title>](<filename>.md) — <one-line hook>
+```
+
+## Command to execute
+
+Operator action. Resolving session:
+
+1. Read the proposed content above
+2. Apply it verbatim (or edit first if the content needs refinement)
+3. Verify via the auto-memory guide in the main system prompt:
+   - frontmatter fields correct for the memory type
+   - content conforms to the type's structure
+   - MEMORY.md index line added (≤150 chars)
+4. Confirm the entry works: next session-start will load MEMORY.md
+   and the index line surfaces the new entry
+
+## On completion
+
+- [ ] Memory file exists at target path with correct frontmatter
+- [ ] MEMORY.md index updated with the new entry line
+- [ ] `git mv docs/deferred-actions/<id>.md docs/deferred-actions/completed/<id>.md`
+- [ ] `git commit -m "chore: apply memory proposal <id>"`
+
+## Cross-refs
+
+- <chronicle that originated the proposal>
+- <related memory entries, if the proposal extends or contradicts existing memory>
+- `.claude/rules/session-artifacts.md`
+- `.claude/rules/deferred-actions.md`

package/substrate/templates/persona-template.md

@@ -0,0 +1,200 @@
+---
+tier: lite
+---
+
+# Persona — [Name]
+
+<!--
+  Bassclef persona template. Pichler-shaped with evidence-traceability.
+  Referenced by /personas skill (.claude/skills/personas/SKILL.md) and
+  validated by standards/persona-schema.md.
+
+  Delete this comment block after copy-paste.
+
+  Save location:
+    Preferred: docs/personas/{slug}.md
+    Legacy (backward-compat with /jtbd-tasks + /synthetic-user):
+      docs/design/personas/{slug}.md
+
+  The filename basename MUST match the `slug` field below.
+-->
+
+**Slug:** [url-safe-identifier]
+**Name:** [Human-readable display name]
+**Archetype:** [One-line categorical framing — e.g., "PE operator managing 50+ active deals", "Bootstrapped couple founders", "Tier-2 SaaS customer-success manager"]
+**Evidence quality:** [High | Medium | Low | — (unsourced default)]
+**Generated:** [YYYY-MM-DD] via [/psychographic-mine | /auto-user-research | manual research | operator-default]
+**Source synthesis:** [path to research doc, or "—"]
+
+---
+
+## Provenance
+
+<!--
+  Required for any persona with a claim about behavior, pain points, or
+  workflows. Every claim should trace to a source. Orphan claims
+  (claims without citation) surface as WARN in /personas validate.
+
+  If this is an operator-default, state so plainly:
+    "Operator-default; not research-backed."
+-->
+
+Persona built from:
+- **[Source 1 name]** — [link or repo-local path]. [One-line characterization of what this source establishes]
+- **[Source 2 name]** — [link]. [Characterization]
+- **[Source 3+ as applicable]**
+
+---
+
+## Goal
+
+<!--
+  REQUIRED. One sentence. What this persona is trying to accomplish
+  that the product hires to help with.
+
+  Not a feature. An outcome.
+-->
+
+[One-sentence goal. Start with a verb. End with an outcome, not a feature.]
+
+---
+
+## Role / Context
+
+<!--
+  Pichler "context" field + enough environmental grounding that
+  downstream skills can frame tasks, jargon level, and viewport
+  appropriately.
+-->
+
+- **Relationship / cohort:** [e.g., married 5+ years, solo founder, cross-functional IC]
+- **Organizational stage:** [e.g., bootstrapped pre-seed, Series B, established enterprise]
+- **Revenue / scale context:** [if applicable]
+- **Team size:** [self, 2, 10, 100+]
+- **Industry:** [specific or range]
+
+**Representative example (composite OK):** [Name + age + one-line bio so
+downstream skills can render concrete scenarios. Mark explicitly as
+composite vs. real if from research.]
+
+---
+
+## Workflows (today)
+
+<!--
+  Pichler "tasks" + "approach" combined. How they currently operate,
+  what tools they use, what rhythm they follow.
+-->
+
+### How they currently work
+
+- [Primary tool / pattern / rhythm]
+- [Secondary tools]
+- [Coordination / collaboration mechanism if relevant]
+
+### Daily or typical rhythm
+
+- [Morning routine]
+- [Workday pattern]
+- [Evening / end-of-day]
+
+---
+
+## Pain points (with evidence trace)
+
+<!--
+  Each pain should cite a source. Formatting convention:
+    > *Source trace: [source-N reference] — "[direct quote]"*
+
+  This is the evidence-traceability rule. Orphan pains (no trace)
+  are WARN in /personas validate.
+-->
+
+### P1 — [Concise pain label]
+
+[One-paragraph description of the pain — what triggers it, how it
+manifests, what it costs them.]
+
+> *Source trace: [source reference] — "[direct quote or paraphrase]"*
+
+### P2 — [Concise pain label]
+
+[Description]
+
+> *Source trace: [source reference]*
+
+### P3+ as applicable
+
+---
+
+## Workarounds they've built
+
+<!--
+  Important for JTBD reasoning and /value-prop-canvas Jobs mapping.
+  The workaround is the "status quo" alternative in the Strategyzer
+  Value Map.
+-->
+
+- [Workaround 1] — [effectiveness] — [source trace if applicable]
+- [Workaround 2] — ...
+
+---
+
+## Knowledge / jargon comfort
+
+<!--
+  Pichler "knowledge" field. Drives /synthetic-user viewport,
+  /visual-review jargon checks, /spec copy tier.
+-->
+
+- **Domain expertise:** [novice / working-knowledge / expert]
+- **Technical fluency:** [what they use confidently; what they avoid]
+- **Jargon comfort:** [specific terms known vs. need-plain-language]
+
+---
+
+## Biography
+
+<!--
+  Pichler "biography" field. Short — 2-3 sentences. Formative
+  background, not life story. Use this to give downstream skills a
+  narrative anchor for synthesis and testing.
+-->
+
+[Short biographical framing — age range, prior roles, formative influences, what brought them to this goal.]
+
+---
+
+## Quotes / voice samples
+
+<!--
+  Optional but highly valuable. Direct or paraphrased language from
+  source material. Drives /synthetic-user test narration and
+  /value-prop-canvas Gains articulation.
+-->
+
+> "[Direct quote from source]"
+> — [source reference]
+
+> "[Another quote]"
+> — [source]
+
+---
+
+## Anti-persona / NOT this persona
+
+<!--
+  Optional. Who this persona is explicitly NOT. Prevents downstream
+  skills from conflating adjacent cohorts.
+-->
+
+- NOT: [adjacent cohort that might get confused]
+- NOT: [another adjacent cohort]
+
+---
+
+## Further reading
+
+- Roman Pichler, *The Persona Template* — https://www.romanpichler.com/the-persona-template/
+- Alan Cooper, *The Inmates Are Running the Asylum* — archetype-based persona framework (complementary to Pichler)
+- Agile Alliance, *Personas* glossary — https://agilealliance.org/glossary/personas/

package/substrate/templates/pr-faq.md

@@ -0,0 +1,45 @@
+---
+tier: lite
+---
+
+# [Initiative Name] — Press Release / FAQ
+
+## Press Release (Written as if launching today)
+
+### Headline
+One sentence. What did we ship and why does anyone care?
+
+### Subheadline
+Who is this for and what do they get?
+
+### Problem Paragraph
+The world before this existed. Pain. Friction. Cost.
+
+### Solution Paragraph
+What we built. How it works. What changes.
+
+### Quote (You)
+Why you built it. What you believe.
+
+### How It Works
+Three steps. Maximum.
+
+### Quote (Customer)
+A fictional but realistic customer reaction.
+
+### Call to Action
+What the reader does next.
+
+---
+
+## FAQ
+
+### Customer FAQ
+Q: What does this cost?
+Q: How is my data handled?
+Q: What if it breaks something?
+
+### Internal FAQ
+Q: How long will this take to build?
+Q: What's the biggest technical risk?
+Q: What do we explicitly NOT build in v1?

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.