@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/standards/project-directory-layout.md

@@ -0,0 +1,276 @@
+---
+tier: lite
+description: Standard directory structure for sunj-labs repositories.
+---
+
+# Project Directory Layout
+
+Standard directory structure for sunj-labs repositories. The goal: a new adopter cloning a bassclef-consumer repo can locate any artifact in under 30 seconds without asking.
+
+> **Which page do I want?** Two related pages cover "where does X go?":
+>
+> - **This page (Directory Layout)** — the methodology tree. Answers: "I'm writing a canvas / spec / ADR / chronicle — which directory does it live in?" Use when you're producing an SDLC artifact and need to know where to put it.
+> - **[File structure](https://github.com/sunj-labs/bassclef/wiki/File-structure)** — the installation footprint. Answers: "What did `/onboard-repo` actually write into my repo? What's safe to edit vs. bassclef-managed?" Use when you're inspecting what landed after install or deciding what to commit vs. gitignore.
+>
+> If you're asking "where does this artifact go?" you want Directory Layout. If you're asking "what just got installed?" you want File structure.
+
+This standard replaces the prior 2026-01 snapshot. See `docs/audits/2026-05-12-directory-skill-overlap-audit.md` for the inventory that motivated this rewrite.
+
+## Mental model
+
+Every artifact has one home. The SDLC produces artifacts in a predictable flow:
+
+```
+idea → canvas → spec → design → prototype → build → chronicle
+       (strategy/) (specs/) (designs/) (prototypes/) (src/) (chronicle/)
+```
+
+### Two repo shapes — why your app repo and bassclef look almost identical except for `docs/`
+
+The two layouts you'll see on this page (App repo and Bassclef) have the same SDLC artifact categories. The only structural difference is where those categories live:
+
+- **App repo** (yours): SDLC artifacts nest under `docs/` so they don't compete with `src/` at the top. Your application code is what readers expect to see first when they open the repo.
+- **Bassclef** (the methodology repo): the entire repo IS the methodology. There is no `src/` at the top. SDLC artifact categories hoist to root because that's the load-bearing content.
+
+Same artifacts, different nesting. A canvas in your app repo lives at `docs/strategy/canvases/`. A canvas in bassclef lives at `strategy/canvases/`. The path-prefix is the only delta.
+
+| Artifact | App repo (your repo) | Bassclef (this repo) |
+|---|---|---|
+| Canvas | `docs/strategy/canvases/` | `strategy/canvases/` |
+| Spec | `docs/specs/` | `docs/specs/` (bassclef happens to use docs/specs too) |
+| ADR | `docs/architecture/decisions/` | `architecture/decisions/` |
+| C4 diagram | `docs/architecture/c4/` | `architecture/c4/` |
+| Design tokens | `docs/designs/` | `design/` |
+| Chronicle | `docs/chronicle/` | `chronicle/` |
+| Decomposition | `docs/decompositions/` | `docs/decompositions/` |
+| Iteration goal | `docs/iteration-bets/` | `docs/iteration-bets/` |
+
+The asymmetry is intentional, not legacy. App repos need `src/` at the top; bassclef doesn't have one to compete with. Same conceptual flow (`idea → canvas → spec → ...`), different root-level placement.
+
+## App repo layout
+
+Legend:
+
+- 🔵 **bassclef-managed** — the substrate writes/owns these paths. Skills, rules, hooks, agents, and SDLC artifacts produced by the methodology.
+- ⚪ **your code** — your application. Bassclef doesn't touch `src/`, your migrations, your tests. Names below are illustrative; replace with your stack's conventions.
+
+```
+⚪ src/                            # your application code
+⚪ your-database-migrations/       # e.g. prisma/, alembic/, knex/ — if applicable
+⚪ public/                         # your static assets
+⚪ scripts/                        # your build / deploy / utility scripts
+⚪ tests/                          # your test suites (unit / integration / e2e)
+⚪ data/                           # your data files, snapshots (not docs)
+
+🔵 .claude/                        # bassclef substrate (skills, rules, hooks, agents)
+
+🔵 docs/                           # SDLC artifacts produced by the methodology
+🔵   strategy/
+🔵     canvases/                   # product canvases (Thesis → Shape → Build)
+🔵     pr-faqs/                    # PR/FAQ documents
+🔵     research/                   # research notes
+🔵   specs/                        # structured specs from canvases
+🔵   decompositions/               # /decompose output (responsibility audit + pattern map)
+🔵   designs/                      # design artifacts (tokens, mocks, references)
+🔵   ia-models/                    # information architecture models
+🔵   interaction-design/           # interaction design artifacts
+🔵   prototypes/                   # visual + technical prototypes (HTML, screenshots, gallery indexes)
+🔵   visual-reviews/               # /visual-review output
+🔵   architecture/
+🔵     decisions/                  # ADRs
+🔵     c4/                         # C4 diagrams
+🔵     erd/                        # entity-relationship diagrams
+🔵     reviews/                    # /architect-review output
+
+🔵   # iteration + roadmap
+🔵   roadmaps/                     # multi-week strategic frames (compose N bets)
+🔵   iteration-bets/               # time budget + scope per iteration
+🔵   branch-stacks/                # stack manifests for multi-branch work
+
+🔵   # session lifecycle artifacts
+🔵   chronicle/                    # session narratives (dated, append-only)
+🔵   sessions/                     # session-board coordinator artifacts (multi-bet longruns)
+🔵   sdlc-traces/                  # session hook logs
+🔵   deferred-actions/             # cross-session handoff entries
+🔵   audits/                       # audit reports (adopter-readiness, directory drift, etc.)
+🔵   sibling-validations/          # validation reports from sibling-repo runs
+
+🔵   # comms + ops
+🔵   journals/              # journal-entry drafts (operator narrative voice; publishable to LinkedIn, Substack, etc.)
+🔵   journal-export/              # journal-entry corpus exports to brand-team Google Doc
+🔵   release-notes/                # per-release notes
+🔵   demos/                        # demo runbooks
+🔵   runbooks/                     # operational runbooks
+🔵   research/                     # operator research notes
+🔵   learnings/                    # captured learnings (sister to design/discoveries in bassclef)
+🔵   longrun-plans/                # /longrun pre-flight artifacts
+🔵   metrics/                      # operator-facing metrics dashboards
+```
+
+Stack-specific entries (database migrations, framework public folders, build tool config) live alongside `src/` per your stack's conventions — bassclef doesn't move your code. The 🔵 rows are what the substrate writes; the ⚪ rows are placeholders showing where your code lives relative to the substrate.
+
+Optional `docs/strategy/` subdivision matches bassclef's `strategy/` root — same artifact types, different nesting.
+
+## Bassclef (methodology repo) layout
+
+```
+.claude/                      # bassclef's substrate (skills, rules, hooks, agents)
+architecture/                 # ADRs + C4 + ERD + reviews (hoisted from docs/architecture/)
+  decisions/
+chronicle/                    # session narratives (hoisted from docs/chronicle/)
+design/                       # design principles, object model, tokens (hoisted from docs/designs/)
+  discoveries/                # earned-wisdom principles (bassclef-only)
+lib/                          # state-spine accessor library (lib/state.sh)
+patterns/                     # pattern catalog (GoF / Fowler / Smarter Patterns / etc)
+sdlc-portable/                # exportable SDLC bundles
+standards/                    # engineering standards (this file lives here)
+  state-spine/                # state-spine schemas
+state/                        # state-spine markers + projections (runtime)
+scripts/                      # bassclef-specific utility scripts
+strategy/                     # canvases + templates (hoisted from docs/strategy/)
+  canvases/
+  templates/
+tests/                        # bassclef hook tests
+docs/                         # everything else from the app-repo layout above
+  audits/
+  branch-stacks/
+  baselayer/                  # baselayer-publish strategy + queue (bassclef-specific)
+  decompositions/
+  deferred-actions/
+  demos/
+  designs/
+  iteration-bets/
+  ia-models/
+  input-artifacts/            # rendered input artifacts from /interpret-input
+  interaction-design/
+  interviews/                 # interview transcripts feeding canvases
+  learnings/
+  journals/
+  journal-export/
+  longrun-plans/
+  metrics/
+  release-notes/
+  research/
+  roadmaps/
+  runbooks/
+  sdlc-traces/
+  sessions/
+  sibling-validations/
+specs/                        # at bassclef root by exception (currently 1 file); migrate to docs/specs/
+```
+
+## One artifact, one location — the bassclef map
+
+Reference for adopters: "I have artifact X — where does it go?"
+
+| Artifact | App repo path | Bassclef path | Produced by |
+|---|---|---|---|
+| Canvas | `docs/strategy/canvases/` | `strategy/canvases/` | `/canvas` |
+| Spec | `docs/specs/` | (use `docs/specs/`; legacy `specs/` slated for removal) | `/spec` |
+| ADR | `docs/architecture/decisions/` | `architecture/decisions/` | `/architect-review`, manual |
+| C4 diagram | `docs/architecture/c4/` | `architecture/c4/` | `/architect-review` |
+| Decomposition | `docs/decompositions/` | `docs/decompositions/` | `/decompose` |
+| Design tokens / mocks | `docs/designs/` | `design/` | `/frontend-design`, manual |
+| IA model | `docs/ia-models/` | `docs/ia-models/` | `/ia-model` |
+| Interaction design | `docs/interaction-design/` | `docs/interaction-design/` | `/interaction-design` |
+| Prototypes | `docs/prototypes/` | `docs/prototypes/` | `/preview`, `/preview-build`, `/tech-prototype` (see "Skill family for prototypes") |
+| Visual review | `docs/visual-reviews/` | `docs/visual-reviews/` | `/visual-review` |
+| Chronicle | `docs/chronicle/` | `chronicle/` | `/chronicle`, `/session-end` |
+| Journal entry | `docs/operator-private/journals/` | `docs/operator-private/journals/` | `/journal` |
+| Release note | `docs/release-notes/` | `docs/release-notes/` | `/release-notes` |
+| Iteration goal | `docs/iteration-bets/` | `docs/iteration-bets/` | manual / `/longrun prep` |
+| Roadmap | `docs/roadmaps/` | `docs/roadmaps/` | manual |
+| Stack manifest | `docs/branch-stacks/` (SENTINEL_bassclef_name) | `docs/branch-stacks/` | `/longrun prep` (see "Stack manifest path migration") |
+| Session board | `docs/sessions/` | `docs/sessions/` | `/longrun prep` (multi-bet only) |
+| SDLC trace | `docs/sdlc-traces/` | `docs/sdlc-traces/` | hooks |
+| Deferred action | `docs/deferred-actions/` | `docs/deferred-actions/` | session-rescue, skills that defer |
+| Audit report | `docs/audits/` | `docs/audits/` | manual / agent audit runs |
+| Sibling validation | `docs/sibling-validations/` | `docs/sibling-validations/` | sibling-validation runs |
+| Demo runbook | `docs/demos/` | `docs/demos/` | manual |
+| Operational runbook | `docs/runbooks/` | `docs/runbooks/` | manual |
+| Research note | `docs/research/` | `docs/research/` | `/agent-research-spawn`, manual |
+| Learning | `docs/learnings/` | `docs/learnings/` | manual (bassclef: design/discoveries/ for earned wisdom) |
+| Metrics dashboard | `docs/metrics/` | `docs/metrics/` | `/metrics` |
+| Longrun plan | `docs/longrun-plans/` | `docs/longrun-plans/` | `/longrun prep` |
+| Input artifact | `docs/input-artifacts/` | `docs/input-artifacts/` | `/interpret-input` |
+| Interview transcript | `docs/interviews/` | `docs/interviews/` | manual / `/interview` (when shipped) |
+| Journal-entry corpus | `docs/journal-corpus/` | `docs/journal-corpus/` | `/journal-export` |
+| PR/FAQ | `docs/strategy/pr-faqs/` | `templates/pr-faq.md` (template only) | `/canvas` |
+
+## Skill family for prototypes — three bassclef surfaces (per ADR-020)
+
+Three skills, two axes. Adopter decision tree:
+
+| If you want | Use | Sizes |
+|---|---|---|
+| Visual mock variants only (clickable, on a subdomain) | `/preview` | quick (~30 min, 2 variants) / light (~2h, 3 variants + Anthropic baseline) |
+| Visual mock variants + buildable plan (spec + decomposition + migration) | `/preview-build` | medium (~1 day) / full (audit-grade) |
+| Pre-build risk gate (accuracy / integration / UX-visual / structural) | `/tech-prototype` | per shape |
+
+Two skills are deprecated per ADR-020 (2026-05-12):
+
+- `/prototype-variants` → use `/preview light` (light size already includes luminary champion-challenger)
+- `/prototype-gallery` → use `/preview` (any size; `/preview` already produces a shareable gallery URL per ADR-016)
+
+The deprecated skills remain invocable for ≥3 months while existing canvases / bets / chronicles that reference them get migrated. Full retirement schedule is in ADR-020 §"Migration plan."
+
+## Stack manifest path migration
+
+The directory layout standard names `docs/branch-stacks/` as bassclef. Reality has stack manifests split between `docs/branch-stacks/` (13 files) and `docs/stacks/` (36 files). The 36:13 split tilts toward the alias.
+
+**Decision (this version):** `docs/branch-stacks/` is the SENTINEL_bassclef_name; `docs/stacks/` is being migrated. New manifests land in `docs/branch-stacks/`. A follow-on migration relocates the 36 files in `docs/stacks/` and updates references.
+
+**Migration ticket:** TBD (filed after this standard merges).
+
+## Rules
+
+### One location per artifact
+
+Every artifact type has exactly one directory. No duplicates, no fallback chains. If you're unsure where something goes, check the bassclef map above.
+
+### Create on use, not upfront
+
+Don't scaffold empty directories. Create a directory when the first file needs it. The standard defines WHERE things go, not that every directory must exist from day one.
+
+### Add a new directory? Update this standard
+
+When a skill or workflow needs a new top-level directory under `docs/` (or bassclef's root), update the bassclef map in the same PR. Standard-vs-reality drift is the bug class this rewrite addresses; we don't want to grow another generation of it.
+
+### Naming conventions
+
+- Chronicles: `YYYY-MM-DD-slug.md`
+- Journal entries: `YYYY-MM-DD.md`
+- Iteration goals: `YYYY-MM-DD-slug.md`
+- Roadmaps: `YYYY-MM-DD-slug.md`
+- Canvases: `canvas-{name}.md` or `product-canvas.md`
+- ADRs: `ADR-NNN-short-description.md`
+- Specs: `SPEC-NNN-short-description.md` or `{feature-name}.md`
+- Session boards: `YYYY-MM-DD-slug.md`
+- Stack manifests: `YYYY-MM-DD-slug.md`
+- Audits: `YYYY-MM-DD-slug.md`
+- Sibling validations: `YYYY-MM-DD-slug.md`
+- Decompositions: `slug.md` (no date prefix; one per system/component)
+
+### Composition between artifacts
+
+Roadmaps, iteration goals, and stack manifests compose into a work-decomposition tree. Cross-references are typed in frontmatter, not implicit-by-prose. See `standards/artifact-composition.md`.
+
+### Brownfield retrofit
+
+When adopting bassclef in an existing repo:
+
+1. **Don't move existing application code.** Bassclef's substrate goes in `.claude/`; your app stays where it is.
+2. **Create `docs/` if it doesn't exist.** Bassclef wants its artifacts there.
+3. **Map existing methodology docs to the bassclef paths.** If you have `notes/` with iteration plans, move them to `docs/iteration-bets/`. If you have `architecture/` at root, move to `docs/architecture/` (app repo) or hoist to root (if bassclef-style methodology repo).
+4. **Add a one-time `docs/legacy/` subdirectory if needed.** Preserves pre-bassclef content with attribution; delete after migration completes.
+5. **Update your README.md** to point at `docs/` for the methodology layer.
+
+### What does NOT go in `docs/`
+
+- Application code (`src/`)
+- Database snapshots and data files (`data/`)
+- Build artifacts (`.next/`, `dist/`, `build/`)
+- Secrets and credentials (`.env` — never committed)
+- Node modules (`node_modules/`)
+- Playwright MCP artifacts (`.playwright-mcp/`, gitignored)
+- Substrate scripts (`.claude/hooks/`, `.claude/skills/`, etc — that's bassclef)

package/substrate/standards/release-tagging.md

@@ -0,0 +1,137 @@
+---
+tier: lite
+description: Every release of bassclef carries a semantic version tag.
+---
+
+# Release tagging
+
+Every release of bassclef carries a semantic version tag. The tag names what adopters can pin, roll back to, and read a changelog against. This standard names when tags cut, how versions bump, and what the release notes carry.
+
+Bassclef ships to public bassclef via `/release` PRs (per ADR-029). Before this standard, the substrate carried no version tags — adopters could not name what version they ran. Wave 1 dispatch needs a version anchor for support requests, rollback, and changelog reads.
+
+Per bassclef-upstream#614 (WU-1 of bet 2026-07-03b).
+
+## Scope
+
+Applies to:
+
+- `sunj-labs/bassclef-upstream` — the source-of-truth repo. Tags here name the cut point substrate work shipped from.
+- `sunj-labs/bassclef` — the public downstream repo adopters pull from. Tags here name what adopters see.
+
+Both repos carry the same tag name for each release. Adopters read the public tag; operators read the upstream tag when tracing "which cut point shipped this rule / hook / skill". Per ADR-039.
+
+## When tags cut
+
+Tags cut in two moments:
+
+1. **Upstream tag** — after the operator merges the `/release` PR on public bassclef. The `scripts/release-to-bassclef.sh` script tags upstream at the source SHA (currently `release-YYYY-MM-DD-<sha>` marker); this standard adds the semver tag on top.
+2. **Public tag** — immediately after the upstream tag lands, on the merged commit of the `/release` PR in public bassclef.
+
+Tags never cut mid-work. The `/release` dispatch is the single trigger.
+
+## Semver policy
+
+Bassclef follows semver (major.minor.patch). Each level names a kind of change adopters see.
+
+| Level | When it bumps | Examples |
+|---|---|---|
+| **major** | Adopter-observable breaking change | Repo rename, tier vocabulary change, an ADR-031-level break |
+| **minor** | New substrate surface adopters can call on | New rule, hook, skill, standard, luminary, agent |
+| **patch** | Cure or hardening; no new surface | Bug fix, wordlist amendment, refactor, doc rewrite |
+
+When a release carries multiple change classes, the highest applies. Two new rules plus a bug fix cut a minor bump.
+
+The first tag is `v0.1.0` — bassclef has shipped for 8 months plus 1500+ commits and holds ADR-035 substrate-as-system, which is stable enough to name.
+
+## Release notes
+
+Every release page carries release notes grouped by the substrate surfaces the release touched. The `/release` SKILL drafts these from the PRs the release picked up.
+
+Group order:
+
+1. **Rules** — new or amended
+2. **Hooks** — new or refactored
+3. **Skills** — new, amended, or retired
+4. **Standards** — new or amended
+5. **Luminaries** — new full or stub
+6. **Agents** — new or amended
+7. **ADRs** — new decisions
+8. **Cures** — bug fixes + hardening + wordlist amendments
+9. **Sync + release + install** — infrastructure changes that reach adopters at session-start
+
+Each group carries one line per PR. Links to the PR + the source ticket.
+
+Release notes render in three places:
+
+- **GitHub Release page** — the primary surface adopters see
+- **Public bassclef README banner** — a one-line "Latest: v0.1.0 shipped 2026-07-04" link at the top
+- **Adopter changelog** — `docs/changelog.md` in public bassclef; append-only
+
+## Where tags live
+
+- Bassclef-upstream: `v0.1.0`, `v0.1.1`, `v0.2.0`, ... cut on `main` at the release commit
+- Public bassclef: same tag names cut on `main` at the merged release commit
+
+Tags are signed only when the operator's GPG key is present. Unsigned tags still ship; signing is a follow-on when the release pipeline runs on the operator's own machine.
+
+Prior release-marker tags (`release-YYYY-MM-DD-<sha>`) stay in place. They serve a different purpose — naming which SHA a release PR built from. Semver tags name what adopters get. Both patterns co-exist.
+
+## Rollback
+
+When a release breaks adopters, the operator can:
+
+1. Roll adopter setups back — `bassclef-sync` in an adopter checkout can point at the prior tag via `.bassclef-source.json` `git_ref` field
+2. Issue a patch tag with the cure — `v0.1.1` fixes what `v0.1.0` broke
+3. Yank the tag only as a last resort — leaves a hole in the version sequence and confuses adopters running the yanked version
+
+Prefer forward-fix (option 2) over rollback (option 1) over yank (option 3).
+
+## Anti-patterns
+
+These shapes fail this standard.
+
+**Cut a tag between releases.** Tags cut only on `/release` dispatch. Every tag names an adopter-observable release moment.
+
+INSTEAD: hold cure work in `main` until the next release window. Batch multiple cures into one patch tag.
+
+**Bump minor for a cure.** Cures without a new surface stay in patch. Minor bumps signal "new stuff adopters can call on".
+
+INSTEAD: hold the standard bar. When in doubt, bump patch; adopters read patch bumps as "safe to pull".
+
+**Ship a release with no release notes.** Every tag carries a release page with the group-shape breakdown.
+
+INSTEAD: the `/release` SKILL drafts the notes from the PRs the release picked up. If drafting fails, the release blocks until the operator writes the notes by hand.
+
+**Different tags on upstream vs public.** The two repos carry the same tag names. Adopters read public; operators trace back through matching upstream tags.
+
+INSTEAD: `/release` cuts both tags in the same dispatch, with the same name.
+
+## Override
+
+`SKIP_RELEASE_TAG=1 <command>` for `/release` dispatches that ship substrate without a version bump (rare — mainly for infrastructure fixes that ship before the next planned release window). Logged via trace-helper.
+
+INSTEAD of overriding routine work: hold the change until the release window. The discipline compounds across every adopter version pin.
+
+## Composes with
+
+- `.claude/skills/release/SKILL.md` — the operator surface that dispatches releases + cuts tags
+- `scripts/release-to-bassclef.sh` — the release pipeline this standard adds tag cutting to
+- ADR-029 — release pipeline (parent threadhitecture)
+- ADR-039 — bassclef-upstream vs public bassclef tagging split (this standard's ADR)
+- ADR-031 — we-don't-break-adopters (major bumps signal what would otherwise break adopters)
+- `.claude/rules/we-dont-break-adopters.md` — sister discipline; ADR-031 methodology layer
+- `@luminary linus-torvalds` — kernel version discipline (stable API contract per tag)
+- `@luminary frederick-brooks` — conceptual integrity across versions
+- `@luminary michael-nygard` — stability patterns (the release page IS the adopter-facing steady state)
+
+## Refs
+
+- bassclef-upstream#614 — this standard's filing ticket
+- Parent goal: `docs/iteration-bets/2026-07-03b-wave-1-launch-prep.md` WU-1
+- Parent roadmap: `docs/roadmaps/2026-06-28-early-adopter-launch.md` Phase XI Batten Down
+- ADR-029 release pipeline (Sanjay P. + Claude Opus, 2026-06)
+- ADR-039 release tagging split (this bet WU-1)
+
+## Retirement condition
+
+This standard retires only if bassclef stops shipping to adopters. Semver policy may evolve (e.g., stricter major-bump criteria); the discipline of tagging every release survives.