@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/scripts/render-lite-manifest-doc.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# tier: lite
+# Render human-readable companion doc from lite-manifest.json.
+#
+# Reads lite-manifest.json at repo root by default; writes docs/lite-manifest.md.
+# The companion doc IS the human-readable projection of the machine-readable
+# manifest — same source of truth, two projections per Ousterhout deep-modules.
+#
+# Per bassclef-upstream#1020 Step 4. Session 2026-08-01d option b.
+#
+# Cures per pre-mortem risk ledger docs/risk-ledgers/2026-08-01c-lite-manifest.md:
+#   F3.4 — prominent version banner at top; every regeneration bumps timestamp
+#   F-b.N3 — anchor on schema file (stable path) not manifest file (may move)
+#
+# Usage:
+#   scripts/render-lite-manifest-doc.sh                    # reads root manifest, writes docs/lite-manifest.md
+#   scripts/render-lite-manifest-doc.sh --dry-run          # prints to stdout
+#   scripts/render-lite-manifest-doc.sh --input PATH       # read manifest from PATH
+#   scripts/render-lite-manifest-doc.sh --output PATH      # write to PATH
+#   scripts/render-lite-manifest-doc.sh --root PATH        # override repo root
+
+set -euo pipefail
+
+DRY_RUN=0
+INPUT_PATH=""
+OUTPUT_PATH=""
+REPO_ROOT_OVERRIDE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --input) INPUT_PATH="${2:-}"; shift 2 ;;
+    --output) OUTPUT_PATH="${2:-}"; shift 2 ;;
+    --root) REPO_ROOT_OVERRIDE="${2:-}"; shift 2 ;;
+    -h|--help)
+      grep -E '^# ' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *) echo "Unknown arg: $1 (use --help)" >&2; exit 1 ;;
+  esac
+done
+
+if [[ -n "$REPO_ROOT_OVERRIDE" ]]; then
+  REPO_ROOT="$REPO_ROOT_OVERRIDE"
+else
+  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+
+if [[ -z "$REPO_ROOT" || ! -d "$REPO_ROOT" ]]; then
+  echo "render-lite-manifest-doc: cannot resolve repo root" >&2
+  exit 1
+fi
+
+[[ -z "$INPUT_PATH" ]] && INPUT_PATH="${REPO_ROOT}/lite-manifest.json"
+[[ -z "$OUTPUT_PATH" ]] && OUTPUT_PATH="${REPO_ROOT}/docs/lite-manifest.md"
+
+if [[ ! -f "$INPUT_PATH" ]]; then
+  echo "render-lite-manifest-doc: manifest not found at $INPUT_PATH" >&2
+  echo "Run scripts/generate-lite-manifest.sh first." >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "render-lite-manifest-doc: missing dependency: jq" >&2
+  exit 1
+fi
+
+VERSION=$(jq -r '.manifest_version' "$INPUT_PATH")
+GENERATED=$(jq -r '.generated_at' "$INPUT_PATH")
+COMMIT=$(jq -r '.upstream_commit' "$INPUT_PATH")
+SHORT_COMMIT="${COMMIT:0:7}"
+TOTAL=$(jq '.entries | length' "$INPUT_PATH")
+
+# Emit doc to stdout via function; caller decides where to redirect.
+render_doc() {
+  echo "# Lite manifest — v${VERSION}"
+  echo ""
+  echo "<!-- Auto-generated by scripts/render-lite-manifest-doc.sh from lite-manifest.json. Do not edit by hand. -->"
+  echo ""
+  echo "**Version:** \`${VERSION}\`  "
+  echo "**Generated:** \`${GENERATED}\`  "
+  echo "**Upstream commit:** \`${SHORT_COMMIT}\`  "
+  echo "**Total entries:** ${TOTAL}  "
+  echo "**Schema:** [\`standards/lite-manifest.schema.json\`](../standards/lite-manifest.schema.json)  "
+  echo "**Machine-readable:** [\`lite-manifest.json\`](../lite-manifest.json) (at repo root)"
+  echo ""
+  echo "> Partners pin against \`manifest_version\`. Membership changes ship as manifest bumps with a changelog entry. Adding an entry is a minor bump; removing is a major bump (breaks partners); description or content-hash change without membership change is a patch bump."
+
+  render_section "skill"    "Skills"
+  render_section "rule"     "Rules"
+  render_section "hook"     "Hooks"
+  render_section "luminary" "Luminaries"
+  render_section "agent"    "Agents"
+  render_section "standard" "Standards"
+  render_section "adr"      "Architecture Decision Records"
+  # Per #1392 Shape 3 (goal 2026-08-27a) — 5 install surfaces bassclef-cli needs
+  render_section "lib"               "Shared Libraries"
+  render_section "script"            "Scripts"
+  render_section "presence-template" "Install Templates"
+  render_section "template"          "Content Templates"
+  render_section "root-doc"          "Root Documentation"
+
+  echo ""
+  echo "---"
+  echo ""
+  echo "## For partners"
+  echo ""
+  echo "- Fetch the manifest from repo root: \`lite-manifest.json\`"
+  echo "- Validate against the schema at \`standards/lite-manifest.schema.json\` (JSON Schema draft 2020-12 strict)"
+  echo "- Pin your build to a specific \`manifest_version\`; upgrade deliberately"
+  echo "- Every \`entries[].path\` is repo-relative; the source file at that path is the authoritative content"
+  echo "- Use \`entries[].content_hash\` to cache-invalidate"
+  echo ""
+  echo "## Semver bump policy"
+  echo ""
+  echo "| Change | Bump |"
+  echo "|---|---|"
+  echo "| Entry added to \`entries[]\` | Minor |"
+  echo "| Entry removed from \`entries[]\` | Major (breaks partners) |"
+  echo "| Description or content_hash change without membership change | Patch |"
+  echo "| Schema shape change (new field added) | Minor |"
+  echo "| Schema shape change (field removed or type changed) | Major |"
+  echo ""
+  echo "Refs — bassclef-upstream#1020 (this manifest) + bassclef-upstream#1030 (root location) + ADR-040 (lite profile) + ADR-031 (we don't break adopters)."
+}
+
+render_section() {
+  local surface_type="$1"
+  local title="$2"
+  local count
+  count=$(jq --arg t "$surface_type" '[.entries[] | select(.type == $t)] | length' "$INPUT_PATH")
+  [[ "$count" -eq "0" ]] && return
+
+  echo ""
+  echo "## ${title} (${count})"
+  echo ""
+  jq -r --arg t "$surface_type" '
+    .entries[] | select(.type == $t) |
+    "- **" + .slug + "** — `" + .path + "`" +
+      (if .description then "  \n  " + .description else "" end)
+  ' "$INPUT_PATH"
+}
+
+if [[ "$DRY_RUN" == "1" ]]; then
+  render_doc
+else
+  mkdir -p "$(dirname "$OUTPUT_PATH")"
+  render_doc > "$OUTPUT_PATH"
+  echo "Wrote $OUTPUT_PATH ($TOTAL entries; commit $SHORT_COMMIT)" >&2
+fi

package/dist/lite/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/dist/lite/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/dist/lite/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)