@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/presence/install/bassclef-sync.template.sh

@@ -1357,7 +1357,7 @@ fi
 # bassclef#611 — clarity-check propagation. Writes a tiny consumer-side
 # workflow that calls bassclef's reusable clarity-check workflow.
 #
-# Vendor binding tier: GitHub-Actions-Locked per standards/vendor-bindings.md.
+# Vendor binding tier: GitHub-Actions-Locked (per bassclef vendor-bindings standard; see operator substrate for full spec).
 # ADO/GitLab/Bitbucket migration tracked at bassclef#629.
 #
 # Skip paths:

package/substrate/scripts/generate-lite-manifest.sh

@@ -28,7 +28,7 @@
 
 set -euo pipefail
 
-MANIFEST_VERSION="1.5.1"
+MANIFEST_VERSION="1.5.7"
 
 # --- arg parse ---
 DRY_RUN=0
@@ -117,9 +117,22 @@ extract_hook_tier() {
     || true
 }
 
+# Normalize `—` YAML escape to literal em-dash character. Closes
+# bassclef-upstream#1548 — YAML frontmatter with double-quoted strings can
+# carry `—` as a 6-char literal; jq preserves it as `\\u2014` in JSON
+# output, which downstream renderers write verbatim into MDX. Adopters see
+# raw `—` on the live site. Normalizing at extraction time lets jq
+# emit the standard `—` JSON escape sequence, which parses cleanly to
+# em-dash at every consumer.
+normalize_em_dash() {
+  local val="$1"
+  echo "${val//\\u2014/—}"
+}
+
 # Extract description from markdown YAML frontmatter (first line of description: field).
 extract_yaml_description() {
-  awk '
+  local val
+  val=$(awk '
     /^---$/ { c++; if (c == 2) exit; next }
     c == 1 && /^description:[[:space:]]/ {
       sub(/^description:[[:space:]]*/, "")
@@ -130,7 +143,8 @@ extract_yaml_description() {
       print
       exit
     }
-  ' "$1"
+  ' "$1")
+  normalize_em_dash "$val"
 }
 
 # Extract a `<field>:` inline YAML list from the frontmatter as a JSON array string.
@@ -183,7 +197,8 @@ extract_yaml_outputs() {
 # Returns empty string when the field is absent, quoting normalized like
 # extract_yaml_description does.
 _extract_yaml_string_field() {
-  awk -v f="$2" '
+  local val
+  val=$(awk -v f="$2" '
     /^---$/ { c++; if (c == 2) exit; next }
     c == 1 && $0 ~ ("^" f ":[[:space:]]") {
       sub("^" f ":[[:space:]]*", "")
@@ -194,7 +209,8 @@ _extract_yaml_string_field() {
       print
       exit
     }
-  ' "$1"
+  ' "$1")
+  normalize_em_dash "$val"
 }
 
 # Extract `problem:` frontmatter field per bassclef-web#268 + web#265 Stage 1

package/substrate/standards/adr-template.md

@@ -0,0 +1,86 @@
+---
+tier: lite
+id: ADR-NNN
+title: <Short title — present-tense imperative, ≤80 chars>
+status: proposed
+date: <YYYY-MM-DD>
+supersedes: null
+superseded_by: null
+---
+
+# ADR-NNN — <Title>
+
+## Context
+
+What is the issue motivating this decision? Describe the forces at play. Include constraints (technical, business, organizational), prior options considered, and what's driving the need for a decision now.
+
+Keep this section descriptive, not prescriptive. The reader should understand the situation before encountering the decision.
+
+## Decision
+
+What did we decide? State the choice in one or two sentences.
+
+Follow with the rationale — why this option, not the alternatives.
+
+## Status
+
+`proposed` | `accepted` | `deprecated` | `superseded`
+
+Lifecycle:
+- `proposed` — drafted, under review
+- `accepted` — adopted; load-bearing
+- `deprecated` — no longer recommended, but not yet replaced
+- `superseded` — replaced by ADR-MMM (note in `superseded_by` frontmatter)
+
+## Consequences
+
+What becomes easier? Harder? More expensive? Cheaper?
+
+What follow-on work does this decision enable or block?
+
+What invariants does this decision establish? Future decisions must respect them.
+
+## References
+
+- Related ADRs: ADR-XXX, ADR-YYY
+- External sources: links to RFCs, blog posts, library docs that informed the decision
+- Source incidents: PRs, chronicles, or tickets that surfaced the need
+
+---
+
+## How to use this template
+
+1. Copy this file to your project's ADR directory:
+   - `docs/adrs/ADR-NNN-<slug>.md` (most common)
+   - `architecture/decisions/ADR-NNN-<slug>.md` (bassclef's own layout)
+2. Pick the next sequential ADR number (look at existing files)
+3. Replace the placeholder content; fill every section
+4. Set status to `proposed` on draft; flip to `accepted` after operator review
+5. Touch the marker: `mkdir -p state/markers/adr && touch state/markers/adr/<decision-slug>-ADR-NNN.md`
+6. Commit alongside the architectural change
+
+## When to write an ADR
+
+Per `.claude/rules/adr-discipline.md`, ADRs are required for load-bearing decisions:
+
+- Schema changes (ORM schema files, migration creation)
+- Framework or library choice at the platform level (not per-component)
+- Deployment topology changes (orchestrator, region, service-mesh, single-vs-multi-region)
+- Cross-cutting concerns (auth, logging, multi-tenancy, observability stack)
+- Interface boundaries between bounded contexts (per Evans DDD)
+- Deprecating or superseding a prior ADR
+
+Skip ADRs for:
+- Routine code changes (bug fixes, feature additions within an existing pattern)
+- Component-level library choices (which icon library, which date-picker)
+- Cosmetic refactors (variable renames, file reorganizations without behavior change)
+
+When in doubt, write the ADR. The marginal cost is ten minutes; the value to future you reading "why" is large.
+
+## Refs
+
+- Michael Nygard's original ADR proposal: [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+- bassclef#1149 — adr-discipline rule + hook
+- `.claude/rules/adr-discipline.md` — the rule that fires
+- `.claude/hooks/adr-discipline-check.sh` — the mechanical check
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires

package/substrate/standards/api-conventions/nextjs.md

@@ -0,0 +1,84 @@
+---
+tier: lite
+description: Stack-specific instantiation of .claude/rules/api-conventions.md for Next.js App Router.
+---
+
+# API Conventions — Next.js App Router
+
+Stack-specific instantiation of `.claude/rules/api-conventions.md` for Next.js App Router. Composed under ARCH-T0 #1133 Path A.
+
+## When this sibling fires
+
+When adopter's `.claude/bassclef-configs.jsonc` has `tech_stack.frontend: nextjs`. The loader (future ticket) reads this sibling and applies the Next.js-specific guidance below in addition to the universal principles in the parent rule.
+
+Until the loader ships, this sibling is discoverable via the cross-reference table in the parent rule.
+
+## File location
+
+- API routes live under `src/app/api/`
+- Route handler files: `src/app/api/[resource]/route.ts`
+- Nested resources: `src/app/api/[parent]/[parentId]/[child]/route.ts`
+- Dynamic segments use bracket syntax per Next.js App Router conventions
+
+## Globs (for hook + tooling targeting)
+
+- `src/app/api/**/*.ts`
+- `src/app/api/**/*.tsx`
+
+These globs scope hooks + linting rules that fire only when the adopter is on Next.js.
+
+## Auth conventions
+
+Next.js-specific auth helpers:
+
+- Use `getServerSession()` from NextAuth.js (or equivalent for the adopter's auth provider) for session retrieval in route handlers
+- Middleware at `src/middleware.ts` runs before route handlers; use it for auth gating, redirects, tenant resolution
+- API routes that modify data MUST check the session at handler entry; no exceptions
+
+## Validation conventions
+
+Recommended Next.js + TypeScript stack pattern:
+
+- Use Zod schemas for request body validation
+- Parse + validate at the start of the route handler:
+
+```typescript
+import { z } from "zod";
+
+const CreateDealSchema = z.object({
+  title: z.string().min(1).max(200),
+  amount: z.number().positive(),
+});
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const parsed = CreateDealSchema.safeParse(body);
+  if (!parsed.success) {
+    return Response.json(
+      { error: { code: "VALIDATION_ERROR", message: "Invalid input", details: parsed.error.issues } },
+      { status: 400 }
+    );
+  }
+  // ...
+}
+```
+
+## Tenant context resolution
+
+For multi-tenant Next.js apps:
+
+- Tenant context resolved in middleware or at route boundary
+- Passed through to queries via React Server Components context or explicit function arguments
+- Never resolved inside ORM query callbacks (race conditions, leak risk)
+
+## Composition with universal principles
+
+Apply the universal principles from `.claude/rules/api-conventions.md` first; the Next.js-specific patterns above add detail without overriding. When the two conflict (e.g., a Next.js convention contradicts the universal route-naming rule), the universal principle wins; file a `/promote` ticket if you believe the convention should be amended.
+
+## Refs
+
+- Parent rule: `.claude/rules/api-conventions.md`
+- ARCH-T0 #1133 — operator-stack-leakage audit + remediation
+- bassclef#1309 — this sibling (api-conventions Path A WU-6 of bet 2026-06-20e)
+- bassclef#1150 T18 — sister Path A (migration-discipline)
+- Next.js App Router docs: https://nextjs.org/docs/app/building-your-application/routing/route-handlers

package/substrate/standards/artifact-composition.md

@@ -0,0 +1,209 @@
+---
+tier: lite
+description: The substrate has three artifact classes that logically compose into a work-decomposition tree.
+---
+
+# Artifact-Composition Standard
+
+The substrate has three artifact classes that logically compose into a
+work-decomposition tree. This standard codifies that hierarchy and the
+typed cross-references that make it walkable.
+
+## The composition tree
+
+```
+Roadmap (multi-week, multi-stage strategic frame)
+  └── Stage
+        └── Iteration goal (scoped commitment, fixed time budget)
+              └── Phase
+                    └── Stack manifest (physical implementation plan)
+                          └── WS branch → PR → merged
+```
+
+Each level is a separate artifact in a separate directory. The
+relationship between levels is expressed via **typed frontmatter
+fields** — not implicit-by-date-prefix or implicit-by-prose-citation.
+
+## When this standard applies
+
+Required for every roadmap, iteration goal, and stack manifest written
+in any sunj-labs repo (bassclef + consumers via bassclef-sync).
+
+Optional for older artifacts predating this standard — backfill
+opportunistically when touching them, not as a forcing migration.
+
+## Required + optional cross-references
+
+| Artifact class | Location | Required frontmatter | Optional frontmatter |
+|---|---|---|---|
+| Roadmap | `docs/roadmaps/` | — | `bets: [list of paths]` (populated as bets shape) |
+| Iteration goal | `docs/iteration-bets/` | — | `parent_roadmap: <path>`, `stack_manifest: <path>` |
+| Stack manifest | `docs/stacks/` (or `docs/branch-stacks/` — see note) | `bet: <path>` | `parent_roadmap: <path>` (transitive convenience) |
+
+**Required** = if the relationship exists, the field MUST be present in
+frontmatter. A bet that descends from a roadmap MUST set
+`parent_roadmap:`. A bet that doesn't descend from any roadmap (small
+one-off bets) doesn't have the field.
+
+**Optional** = the field is present when the artifact has a downward
+relationship the parent should know about. A roadmap's `bets:` list
+can be empty until the first goal shapes; populating it is a
+maintenance discipline.
+
+### Note on stack-manifest directory
+
+The standard's earlier `standards/project-directory-layout.md` named
+`docs/branch-stacks/` for stack manifests. Actual usage in bassclef
+landed at `docs/stacks/`. Both paths exist in some repos. Consolidation
+is a separate cleanup; this standard accepts either as a valid stack-
+manifest location and points at whichever the artifact resolves to.
+
+## Cross-reference integrity rule
+
+**A half-broken cross-reference is a substrate-defect.** Specifically:
+
+| Pattern | Signal |
+|---|---|
+| Prose citation present, frontmatter field missing | Substrate-defect — fix the artifact |
+| Frontmatter field present, target path doesn't exist | Substrate-defect — broken link |
+| Frontmatter field present, target's reciprocal field missing | Substrate-defect — one-way reference |
+
+Reciprocal-field discipline:
+
+- A bet with `parent_roadmap:` SHOULD appear in that roadmap's `bets:`
+  list (the parent maintains the index).
+- A bet with `stack_manifest:` MUST point to a stack manifest whose
+  `bet:` field points back at this bet.
+- A stack manifest with `parent_roadmap:` SHOULD point to a roadmap
+  whose `bets:` list includes the manifest's parent goal.
+
+These reciprocal checks are surface-level mechanical: a future
+`/compose` skill (or `/sprint --tree` extension) can validate them
+in one pass. Today they're agent self-discipline at artifact write
+time.
+
+## Why typed, not implicit-by-prose
+
+The substrate already had implicit composition by date-prefix
+convention (a roadmap at `2026-04-25-...` is "the parent of" a bet at
+`2026-04-25-...` simply because they share a date). That implicit
+convention failed:
+
+- Bets without roadmaps share dates with bets that have them
+- Stack manifests reference bets via prose mention with no parseable
+  link
+- New session pickup has to read three directories and infer
+  relationships from filenames
+
+Typed frontmatter:
+
+- Makes the relationship machine-readable (skills can walk the tree)
+- Survives renames (path is explicit, not derived)
+- Self-documents at the artifact level (a reader of any one artifact
+  sees its parent + children without external context)
+
+## Walkable lineage
+
+Given a typed cross-reference graph, any tool can render the lineage
+from any starting point:
+
+```
+$ /compose docs/iteration-bets/2026-04-25-example-pipeline.md
+
+Lineage:
+  docs/roadmaps/2026-04-25-example-roadmap.md
+    └── docs/iteration-bets/2026-04-25-example-pipeline.md (active, Phase A0)
+          └── docs/stacks/2026-04-25-pipeline-stack.md (6 WSes, 1 pr-open)
+
+Siblings (other bets descending from same roadmap):
+  - (none yet — pipeline is sole child)
+```
+
+The `/compose` skill is a separate /promote (bassclef#275 Part 3,
+deferred from this WS). Until it ships, agents walk the lineage
+manually by reading frontmatter — but the discipline is the same.
+
+## Anti-patterns
+
+**Don't substitute prose for frontmatter fields.** "This bet descends
+from a historical example roadmap" in the body is not a substitute for
+`parent_roadmap: docs/roadmaps/...` in the frontmatter. Prose is for
+narrative; frontmatter is for the machine-readable graph.
+
+**Don't forget reciprocal updates.** When you set `stack_manifest:` on
+a bet, also update the stack manifest's `bet:` field if it doesn't
+already point back. One-way edges silently break the walkable lineage.
+
+**Don't backfill mass migrations.** Older artifacts predating this
+standard don't need a forcing PR. Backfill opportunistically when you
+touch them. The cost of mass backfill (large diff, no behavior change)
+exceeds the value of consistency-now.
+
+**Don't add fields not in the table above.** If a new relationship
+shape emerges (e.g., a bet that supersedes a prior bet), propose
+extending this standard before adding ad-hoc frontmatter fields.
+Schema discipline matters because tools will eventually parse this.
+
+## Composition with other standards
+
+- `standards/project-directory-layout.md` — defines WHERE artifacts
+  go; this standard defines HOW they reference each other. Pair, not
+  replace.
+- `standards/branch-stacking.md` — stack-manifest content discipline;
+  this standard adds the `bet:` and `parent_roadmap:` cross-refs.
+- `standards/session-board.md` — session-board references active bets
+  by path in its `active_bets:` frontmatter; that's another typed
+  cross-ref pattern (session → bets), but the session-board owns the
+  schema for that one.
+- `.claude/rules/artifact-ingestion.md` — "Sources read" block is the
+  ingestion pattern at write time; cross-refs are the persistent graph
+  the ingestion block samples from.
+
+## Enforcement
+
+Methodology-level today. Future mechanical enforcement:
+
+1. `/compose` skill validates reciprocal references and surfaces
+   half-broken edges.
+2. `/sprint` extension renders the lineage tree as an orientation aid
+   at session start.
+3. A hook on PR creation could grep the touched bet/manifest/roadmap
+   files for required-field presence and flag missing cross-refs.
+
+Until those exist, the discipline is agent self-check at artifact
+write time. The "Sources read" block in any new artifact is the
+natural moment to verify cross-refs resolve — both directions.
+
+## Override
+
+There is no override. Cross-references are either typed in frontmatter
+or they don't exist. Prose-only references don't count toward the
+graph and a future tooling pass will flag them.
+
+If a relationship genuinely doesn't exist (e.g., a one-off bet with no
+parent roadmap), don't fabricate one. Omit the field entirely. Empty
+fields are not the same as missing relationships — only set a field
+when the relationship it expresses is real.
+
+## Retirement condition
+
+This standard retires when (a) all bassclef and consumer-repo
+roadmap/bet/stack artifacts conform AND (b) the `/compose` skill is
+shipped and validated AND (c) cross-ref drift hasn't surfaced as an
+operator-visible defect for ≥6 months.
+
+Until then, it's load-bearing for any session that writes or modifies
+an artifact in any of the three classes.
+
+## Relationship to other standards/rules
+
+- `standards/project-directory-layout.md` — directory destinations
+  (where) paired with this standard's relationships (how)
+- `standards/branch-stacking.md` — stack-manifest internal schema;
+  this standard adds the upward cross-refs
+- `standards/session-board.md` — session-level coordinator; references
+  bets by path (sibling cross-ref pattern)
+- `.claude/rules/artifact-ingestion.md` — write-time discipline that
+  surfaces cross-ref work
+- bassclef#275 — promotion issue this standard partially closes
+  (Part 1; the dir mv is WS-A0-4, the `/compose` skill is deferred)