@thebassclef/lite 0.1.3 → 1.0.1

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

@@ -1,150 +0,0 @@
-#!/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/substrate/standards/adr-template.md

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

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

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