@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/standards/cold-adopter-harness.md

@@ -0,0 +1,205 @@
+---
+tier: lite
+description: The cold-adopter harness is a structural validator that approximates a brand-new operator cloning bassclef on a fresh laptop.
+---
+
+# Cold-adopter harness — standard
+
+The cold-adopter harness is a structural validator that approximates a brand-new operator cloning bassclef on a fresh laptop. It catches the failure class where substrate changes silently break adoption — broken symlinks, missing tier-tagged files, invalid `settings.json`, dangling references to files that exist on the developer's machine but not in a clean clone.
+
+This standard documents the V1 shape (shape a per `bassclef-upstream#333`): structural-only checks against a fresh fetch of public bassclef HEAD. Shape b (sync round-trip) and shape c (skill round-trip + CI integration) are deferred follow-ons named in the parent ticket.
+
+## Invocation
+
+```bash
+# Default: fetch public bassclef HEAD into a tmpdir + run checks
+scripts/cold-adopter-harness.sh
+
+# Run against an existing directory (used by tests + ad-hoc validation)
+scripts/cold-adopter-harness.sh --target /path/to/tree
+
+# Help text
+scripts/cold-adopter-harness.sh --help
+```
+
+## Exit codes (Hoare postcondition)
+
+| Code | Meaning |
+|---|---|
+| 0 | All 5 structural checks pass |
+| 2 | At least one structural check fails |
+| 3 | Setup failure (network, no public bassclef, target missing) |
+
+## 5 structural checks
+
+Each check is implemented as a separate function in `scripts/cold-adopter-harness.sh`.
+
+| Function | What it asserts | When it fails |
+|---|---|---|
+| `check_settings_json` | `.claude/settings.json` parses as valid JSON when present | hand-edit corrupted the file; merge dropped a brace |
+| `check_hooks_executable` | All `.claude/hooks/*.sh` carry the executable bit | git fetch dropped permissions; rename lost +x |
+| `check_tier_tags` | Every `tier:` frontmatter value is `lite`, `standard`, `ultra`, `upstream`, or `private` | typo (`tier: standar`) or new tier value not yet documented |
+| `check_bassclef_source_schema` | `.bassclef-source.json` parses + carries `source_url` when present | adopter hand-rolled the file or copied from a different repo |
+| `check_no_broken_symlinks` | `find -type l` finds no dangling targets in the tree | substrate rename left a symlink pointing at the old path |
+
+Each check returns silently on absence (no `.claude/settings.json`? OK — not every adopter carries one) and reports `FAIL` on presence-with-defect.
+
+## Override
+
+```bash
+SKIP_COLD_ADOPTER_HARNESS=1 scripts/cold-adopter-harness.sh
+```
+
+Logged via `trace-helper.sh`. Use only when the harness itself is under maintenance OR when the cold-adopter contract is genuinely irrelevant to the current task (rare — the discipline holds in most cases).
+
+## Why this exists
+
+Six vendoring-gap failures surfaced on bet 25b (PR #334) the first time CI fired on bassclef-upstream — every gap was the class "file exists on public bassclef but missing on upstream." Each was diagnosed individually; the harness names the class and runs against it before bets ship. The discipline parallels `@luminary michael-feathers` Working Effectively with Legacy Code — a characterization test locks the observable contract.
+
+## Composes with
+
+- `.claude/rules/we-dont-break-adopters.md` — the harness IS the mechanical layer for the adopter-compat stance
+- `.claude/rules/testing-tier-config.md` Tier 0 — harness ships test-first with `.claude/hooks/tests/cold-adopter-harness.test.sh`
+- `.claude/rules/bootstrap-pair-discipline.md` — the harness is the runtime pair for substrate primitives that need adopter-side validation
+- `scripts/release-to-bassclef.sh` — sister at the release boundary; harness fires before release, andon scan fires during
+- `architecture/audits/2026-06-24-release-tree-origin.md` — the asymmetry the harness measures
+
+## Distinct from
+
+- `release-to-bassclef.sh` — that script publishes changes downstream; this harness validates state. Both ship together but operate on different boundaries.
+- `scripts/secrets-status.sh` — that script reports secret lifecycle; this harness reports substrate-shape integrity.
+- Pre-commit hooks — those fire at write time; this harness fires at validation time (operator-triggered today; CI-triggered when shape c lands).
+
+## Shape b — sync round-trip (V2, bassclef-upstream#341)
+
+Shape b extends shape a by composing the 5 structural checks with a sixth check that verifies post-sync surface consistency: when `settings.json` carries a statusLine reference, the script it references must exist on disk. Closes the regression class surfaced by #340 (`additive_merge_settings` cp-fallback dropping `statusLine` reference silently).
+
+### Invocation
+
+```bash
+# Run shape b against an existing tree (composes shape a + statusLine check)
+scripts/cold-adopter-harness-sync.sh --target /path/to/tree
+
+# Structural-only (delegates to shape a, 5 checks)
+scripts/cold-adopter-harness-sync.sh --mode structural --target /path/to/tree
+
+# Live fetch: clone public bassclef HEAD into tmpdir + run
+scripts/cold-adopter-harness-sync.sh --fetch
+
+# Help text
+scripts/cold-adopter-harness-sync.sh --help
+```
+
+### Exit codes (same shape as shape a)
+
+| Code | Meaning |
+|---|---|
+| 0 | All 6 checks pass (5 structural + 1 statusLine consistency) |
+| 2 | At least one check fails |
+| 3 | Setup failure (shape a foundation missing, target missing, fetch error) |
+
+### Sixth check
+
+| Function | What it asserts | When it fails |
+|---|---|---|
+| `check_statusline_consistency` | When `.claude/settings.json` carries a `statusLine.command` of shape `bash <path>`, the referenced script exists on disk | The cp-fallback path silently dropped the ref (per #340); or the operator hand-edited the ref to point at a now-renamed script |
+
+When `settings.json` does NOT carry a statusLine reference, the check passes silently (not all adopters carry one). When `settings.json` fails to parse at all, the check defers to shape a's `check_settings_json` finding (avoids redundant noise).
+
+### Seventh + Eighth checks (shape c — bassclef-upstream#341 WU-3)
+
+Shape c extends the harness with workflow-loop smoke checks. Both run after shape a's 5 structural checks + shape b's 6th statusLine consistency check, totaling 8 checks per run.
+
+| Function | What it asserts | When it fails |
+|---|---|---|
+| `check_state_spine_smoke` | `lib/state.sh` exists at the target's expected path AND sources cleanly AND defines `state_whereami_get` (the canonical read accessor) | `lib/state.sh` missing (broken symlink, never shipped); the library fails to source (syntax error after recent edit); the canonical accessor function went missing or got renamed without a rename-compat shim |
+| `check_skills_parse_smoke` | `/sprint`, `/whereami`, `/substrate-check` SKILL.md files all exist + carry parseable YAML frontmatter | A workflow-loop skill went missing (rename without compat shim); a SKILL.md got hand-edited to drop the frontmatter block; the frontmatter close marker `---` is missing |
+
+Why these three skills specifically: they form the workflow-loop orientation triad every adopter session uses at session-start. `/sprint` shows what's in flight; `/whereami` shows project-state; `/substrate-check` validates the substrate wiring. A regression in any of them breaks adopter onboarding silently.
+
+Why `check_state_spine_smoke` checks function-definition (not return-data): adopter Shape (A JSON vs B markdown) varies; the accessor's return value depends on whether `docs/whereami.json` exists locally. The smoke proof is that the library SOURCES + the accessor function IS DEFINED. Data-correctness validation is per-accessor; out of scope for shape-c smoke.
+
+### Override
+
+```bash
+SKIP_COLD_ADOPTER_HARNESS_SYNC=1 scripts/cold-adopter-harness-sync.sh
+```
+
+Logged via `trace-helper.sh`. Same discipline as shape a.
+
+### Live end-to-end sync invocation (deferred to shape c)
+
+Shape b currently validates a target's post-sync state structurally — it does NOT invoke `presence/install/bassclef-sync.template.sh` end-to-end against a fake consumer + fake HOME inside the harness. That live invocation lands with shape c (workflow round-trip + CI integration) per `bassclef-upstream#341` § Shape c. The `--fetch` flag does the safest piece (clone + structural validation) without requiring fake HOME plumbing.
+
+## V3 (shape c — deferred per `bassclef-upstream#341`)
+
+- **Shape c** — workflow round-trip + CI integration. Composes shape b. After sync, invokes `/sprint`, `/whereami`, `/substrate-check` against the cold dir + sources `lib/state.sh` for state-spine smoke. Runs in GitHub Actions on PR — PR-blocking when shape c fails. Catches breakage in the actual workflow loop. Filed as next bet after shape b lands.
+
+V1 (shape a) ships the foundation; V2 (shape b) adds statusLine consistency; V3 (shape c) lands the CI gate.
+
+## Shape d — mechanism-fidelity check classes (bet 27c WU-5, bassclef-upstream#417)
+
+Shape d adds 4 check classes that catch every future instance of the "rule names a mechanism that does not fire" failure class. Each class composes `lib/mechanism-fidelity.sh` (shipped bet 27c WU-3) — the shared deep module. The audit skill (`.claude/skills/audit-rule-mechanism-fidelity/`, WU-4) and the harness (this Shape d, WU-5) share the same impl; no duplicated logic.
+
+### Invocation
+
+Shape d fires as part of `--mode sync` (default). No new mode flag; the 4 checks run after Shape c's state-spine + skills-parse smokes.
+
+```bash
+scripts/cold-adopter-harness-sync.sh --mode sync --target <dir>
+```
+
+When `<target>/lib/mechanism-fidelity.sh` is absent (pre-bet-27c-WU-3 install layout), Shape d emits a SKIP finding and the harness proceeds without the 4 checks.
+
+### V1 ADVISORY mode
+
+Shape d ships in V1 as ADVISORY: findings record to the SYNC_FINDINGS array with `ADVISORY (Shape d V1; will BLOCK in V2):` prefix but do NOT increment SYNC_FAIL_COUNT. The harness exits 0 even with Shape d findings present.
+
+This pattern lets the PR-CI gate ship while WU-6 audit produces the full findings doc + WU-7 sizes the cure bet (Bet C-pre-2) from those findings. After cures land, the V2 flip changes ADVISORY to BLOCK; the harness then fails CI on any Shape d finding.
+
+### The 4 check classes
+
+**Check 9 — `hook-wiring-presence`** — For each hook in `.claude/hooks/*.sh` (except `trace-helper.sh`), the harness calls `verify_hook_wired` from the lib. The lib greps `<target>/.claude/settings.json` and `$HOME/.claude/settings.json` for the hook name. PASS when wired in at least one; ADVISORY when wired in neither.
+
+Catches: hooks shipped without their paired settings.json entry (the "hook-wire-on-author" failure mode named in `.claude/rules/hook-wire-on-author.md`).
+
+**Check 10 — `hook-path-resolution-under-install-class`** — For each hook, `verify_path_resolution` checks for the Class A pattern: hook reads `SCRIPT_DIR/../../<project-resource>` but declares `# install-class: operator`. Mismatch = Class A failure (under `$HOME` wiring, `SCRIPT_DIR/../../` resolves to a nonexistent path). PASS when no risky pattern OR risky pattern + `install-class: dual`/`project`. ADVISORY when Class A or undeclared with risky pattern.
+
+Catches: the failure mode the `turn-prose-kiss-check.sh` cure (PR #427) closed; prevents repeats.
+
+**Check 11 — `hook-end-to-end-smoke`** — For each hook: `bash -n` syntax check + invocation with empty JSON stdin (`{}`). Assert exit code is in `{0, 2, 3}` (success or known block codes). Other codes indicate a real crash. Conservative: invokes with empty stdin to exercise the hook's graceful-skip path; does not exercise full hook behavior.
+
+Catches: hooks that fail to parse OR crash with unexpected exit codes when invoked normally.
+
+**Check 12 — `rule-mechanism-claim-fidelity`** — For each rule under `.claude/rules/*.md`, `scan_rule_for_mechanism_claims` extracts hook references. For each claim, the harness runs the 5-step verification cascade (`verify_hook_exists` + `verify_hook_wired` + `verify_path_resolution` + `verify_hook_test_pins_contract`) and `classify_finding` returns one of 7 labels (CLEAN / DEAD-LETTER / UNWIRED / PATH-BROKEN / TEST-MISSING / METHODOLOGY-ONLY / SILENT-PASS). PASS when all claims classify CLEAN; ADVISORY otherwise with classification per claim.
+
+False-positive filter (V1): claims that reference `.sh` files outside `.claude/hooks/` are skipped (lib references like `state.sh`, script references like `release-to-bassclef.sh`, doc example names like `foo.sh`). The audit skill (WU-4) uses the broader scanner without this filter to classify ALL claims; the harness applies the filter to focus PR-CI signal on hook-related claims only.
+
+### Composition with prior shapes
+
+| Layer | Shape | Checks |
+|---|---|---|
+| Foundation | a | 1-5 (structural validity) |
+| Sync round-trip | b | 6 (statusLine) |
+| Workflow round-trip | c | 7-8 (state-spine + skills-parse) |
+| **Mechanism fidelity** | **d** | **9-12 (wiring + path + smoke + rule-claim)** |
+
+Shape a is mandatory. Shape b/c are mandatory under `--mode sync`. Shape d is mandatory when `lib/mechanism-fidelity.sh` is present in target.
+
+### V2 (BLOCK flip — deferred to follow-on)
+
+V2 flips Shape d findings from ADVISORY to BLOCK after Bet C-pre-2 cures land. The flip is a single-line code change in the harness (`shape_d_advisory()` → identical to a `FAIL:` accumulator). No methodology change; the discipline already exists in V1.
+
+V2 ships when the audit skill's first findings table (`architecture/audits/2026-06-27-mechanism-fidelity.md`, WU-6 product) drives down to zero remaining findings under the V1 false-positive filter.
+
+## Refs
+
+- `bassclef-upstream#333` — this standard's filing ticket
+- `bassclef-upstream#320` — parent epic
+- bet `docs/iteration-bets/2026-06-25e-cold-adopter-harness.md` — ship vehicle
+- `architecture/audits/2026-06-24-release-tree-origin.md` — WU-11 of bet 24c surfaced the asymmetry
+- `docs/deferred-actions/completed/2026-06-25T00-31-00Z-cold-adopter-harness-decision-pending.md` — operator decision recorded
+
+## Retirement condition
+
+This standard retires only if bassclef stops having adopters. The harness's surface area may grow (more checks, more shapes) but the discipline of validating the adopter-observable contract before ship survives.

package/dist/lite/standards/data-management.md

@@ -0,0 +1,135 @@
+---
+tier: lite
+description: Verify with data, not empty state. An empty page that renders is not verification — it proves the template works, not the feature.
+---
+
+# Data Management Standard
+
+## Principle
+
+Verify with data, not empty state. An empty page that renders is not
+verification — it proves the template works, not the feature.
+
+---
+
+## Schema Migration Workflow
+
+When a branch adds or modifies Prisma schema:
+
+### Before migration (SHOULD)
+
+1. **Snapshot the local dev DB** — rollback point
+   ```bash
+   pg_dump -Fc $DATABASE_URL > docs/db-snapshots/YYYY-MM-DD-pre-{name}.dump
+   ```
+   Store in `docs/db-snapshots/` (create if missing). Not committed to git
+   (add to `.gitignore`) — too large. Just a local safety net.
+
+### Apply migration (MUST)
+
+2. **Run migration**
+   ```bash
+   npx prisma migrate dev --name descriptive_name
+   ```
+   This creates the migration file AND applies it locally.
+
+3. **Regenerate client** (MUST — see schema-management.md)
+   ```bash
+   npx prisma generate
+   ```
+   Then restart the dev server. The cached Prisma client won't pick up
+   new models without a restart.
+
+4. **Commit the migration file** with the schema change.
+
+### After migration — seed test data (MUST for new entities)
+
+5. **Write a seed script for new entities**
+   - Location: `prisma/seeds/` or `scripts/seed-{entity}.ts`
+   - Use factories, not hardcoded data (per testing.md)
+   - Each new entity gets a seed file
+   - Seeds are idempotent (safe to re-run, use upsert)
+   - Seeds create realistic data:
+     - Real-looking names, emails, phone numbers
+     - Realistic distributions (not all the same value)
+     - Time-spread data (some recent, some old) for testing
+       time-based queries like "needs attention"
+   - Minimum: 5-10 records per new entity
+   - Link to existing entities where relationships exist
+
+6. **Run the seed**
+   ```bash
+   npx tsx prisma/seeds/seed-{entity}.ts
+   ```
+
+### Verify with data (MUST)
+
+7. **Verify the feature works with seeded data**
+   - UI renders data, not just empty state
+   - API returns seeded records
+   - Queries that filter/sort/group work correctly
+   - Time-based logic (e.g., "needs attention after 7 days") has
+     both qualifying and non-qualifying records to test
+
+---
+
+## Restoring from Production (for realistic local testing)
+
+When you need real data patterns (not just seed data):
+
+1. **Snapshot prod** (read-only):
+   ```bash
+   pg_dump -Fc $PROD_DATABASE_URL > docs/db-snapshots/YYYY-MM-DD-prod.dump
+   ```
+
+2. **Restore to local dev**:
+   ```bash
+   pg_restore --clean --no-owner -d $DATABASE_URL docs/db-snapshots/YYYY-MM-DD-prod.dump
+   ```
+
+3. **Apply pending migrations** (prod may be behind local schema):
+   ```bash
+   npx prisma migrate dev
+   npx prisma generate
+   ```
+
+4. **Seed new entities** that don't exist in prod yet:
+   ```bash
+   npx tsx prisma/seeds/seed-{new-entity}.ts
+   ```
+
+5. **Restart dev server** and verify.
+
+**Rules**:
+- NEVER modify production data. Read-only access to prod.
+- All writes are to local dev only.
+- Prod snapshots are NOT committed to git (add to `.gitignore`).
+
+---
+
+## Verify Gate Update
+
+The `/verify` gate for schema changes must include:
+
+| Check | What | Why |
+|-------|------|-----|
+| Migration applies | `prisma migrate dev` succeeds | Schema is valid |
+| Client regenerates | `prisma generate` succeeds | Client knows new models |
+| Seed runs | Seed script creates data | New entities have test data |
+| App renders with data | UI shows seeded records | Not just empty state |
+| API returns data | Endpoints return seeded records | Queries work |
+| Tests pass | `vitest run` passes | No regressions |
+
+An empty-state screenshot is NOT verification for a schema change.
+
+---
+
+## Seed Data Conventions
+
+- **Factories over hardcoded data** — per testing.md
+- **Naming**: `test_{what}_{scenario}` for test data factory functions
+- **Realistic**: use `faker` or realistic patterns, not "test1", "test2"
+- **Idempotent**: use `upsert` or check-before-create
+- **Minimal**: 5-10 records per entity is enough for dev verification
+- **Time-aware**: spread records across time for testing recency queries
+- **Relational**: link to existing entities (deals, users) where applicable

package/dist/lite/standards/frontend-stack/nextjs-prisma.md

@@ -0,0 +1,124 @@
+---
+tier: lite
+description: "The operator's reference stack. Stack-specific instantiation of standards/frontend-stack.md for adopters who pick the same stack."
+---
+
+# Frontend Stack — Next.js + Prisma + Postgres + EC2-Tailscale
+
+The operator's reference stack. Stack-specific instantiation of `standards/frontend-stack.md` for adopters who pick the same stack.
+
+## When this sibling fires
+
+When adopter's `.claude/bassclef-configs.jsonc` has:
+
+```jsonc
+"tech_stack": {
+  "frontend": "nextjs",
+  "backend": "nodejs",
+  "orm": "prisma",
+  "pkg_manager": "npm",
+  "deploy": "ec2-tailscale"
+}
+```
+
+The loader (future ticket) reads this sibling and applies the stack-specific guidance below in addition to the universal principle in the parent standard.
+
+## Decision
+
+Full TypeScript stack. One language from database to UI.
+
+See [ADR-008](../../architecture/decisions/ADR-008-full-typescript-stack.md) for rationale.
+
+## Stack
+
+```
+Next.js 14+ (App Router)
+├── TypeScript (strict)   — end-to-end type safety
+├── Prisma + Postgres     — ORM, migrations, type-safe queries
+├── NextAuth.js           — auth for operator, family, collaborators
+├── BullMQ + Redis        — async job queue, scheduling, retries
+├── Anthropic TS SDK      — LLM calls inside tools
+├── Langfuse TS SDK       — tracing, evals
+├── Tailwind CSS          — design tokens map to utilities
+├── shadcn/ui             — copy-paste components you own
+└── Deploy: Docker on EC2 via Tailscale
+```
+
+## Project Structure
+
+```
+app/
+├── (dashboard)/          — authenticated pages
+│   ├── deals/
+│   ├── tools/
+│   └── admin/queues/     — Bull Board (operator-only)
+├── api/
+│   ├── health/           — healthcheck endpoint
+│   ├── tools/            — tool trigger endpoints
+│   └── auth/             — NextAuth routes
+├── layout.tsx
+└── page.tsx
+src/
+├── tools/                — tool implementations
+│   ├── registry.ts       — tool registry (name, description, params, run fn)
+│   ├── scrappy-scrapper.ts
+│   ├── deal-scorer.ts
+│   └── inbox-classifier.ts
+├── lib/
+│   ├── queue.ts          — BullMQ queue + worker setup
+│   ├── langfuse.ts       — Langfuse client
+│   └── anthropic.ts      — Anthropic client wrapper
+└── components/
+    └── ui/               — shadcn/ui components
+prisma/
+├── schema.prisma         — single source of truth for DB schema
+├── migrations/           — Prisma migrations (committed to git)
+└── seed.ts               — deterministic seed data
+```
+
+## Conventions
+
+- Components live in `/src/components/ui/` (shadcn/ui, modified to use design tokens).
+- Pages use App Router conventions (`/app/page.tsx`, `/app/layout.tsx`).
+- Design tokens from `platform-docs/design/design-tokens.css` map to Tailwind config.
+- No external component libraries beyond shadcn/ui. You own every component.
+- **Tailwind v4 + bassclef symlinks**: Tailwind v4's `@import "tailwindcss"`
+  auto-scans all project files. Symlinks in `.claude/skills/` that point to
+  `../bassclef/` cause Turbopack to follow paths outside the project root
+  and crash. Add this to `globals.css` after the import:
+  ```css
+  @import "tailwindcss";
+  @source not "../../.claude";
+  ```
+  This excludes the `.claude/` directory from Tailwind's content scanning.
+  The bassclef-sync script should check for this and warn if missing.
+- Tools are registered in `src/tools/registry.ts`. Every tool is a typed function with metadata.
+- Prisma schema is the single source of truth for database structure.
+- Environment variables in `.env.local` (local) and Docker env (production). Never committed.
+
+## Key Commands
+
+```bash
+# Local development
+docker-compose -f docker-compose.dev.yml up -d   # Postgres + Redis
+npm run dev                                        # Next.js hot reload
+
+# Database
+npx prisma migrate dev                             # Create/apply migration
+npx prisma db seed                                 # Seed data
+npx prisma studio                                  # Visual DB browser
+
+# Testing
+npx vitest                                         # Watch mode
+npx vitest run                                     # CI mode
+
+# Production deploy
+git push origin main                               # Triggers full CI/CD pipeline
+```
+
+## Refs
+
+- Parent standard: `standards/frontend-stack.md`
+- ARCH-T0 #1133 — operator-stack-leakage audit + remediation
+- bassclef#1313 — this sibling (frontend-stack Path A WU-8 of bet 2026-06-20e)
+- ADR-008 — operator-side rationale for this stack

package/dist/lite/standards/lite-manifest-schema-changes.md

@@ -34,6 +34,33 @@ Every entry stays in this file for the life of the manifest. Never pruned. When
 
 ## Entries (newest first)
 
+### Goal 2026-09-17c — one tier declaration per file (v1.8.1 → v1.8.2, 2026-09-17)
+
+- **Change type:** content-change (27 content hashes; no entries added or removed)
+- **Fields:** none changed. 420 entries before and after. 26 files lose a stale second `# tier:` line; `script/generate-lite-manifest` changes because the uniqueness check lands in it.
+- **Version bump:** v1.8.1 → v1.8.2 (patch; content-hash change only; no schema shape shift, no entry count change). PR #1720 landed 1.8.1 first, so this follows it directly; an earlier draft of this entry said it would skip 1.8.1.
+- **Rationale:** bassclef-upstream#1724. `scripts/apply-lite-widen.sh` inserted a tier tag above an existing one instead of replacing it, whenever the file had a shebang. Its awk streamed, so the shebang rule fired on line 1 and set the done flag before the real tier line on line 2 was ever reached. 26 files ended up with two tier lines that disagreed — 24 read `lite` then `standard`, 2 read `lite` then `upstream`. Every reader takes the first match, so the shipped tier was correct throughout and nothing warned. Verified before cleaning: all 26 have at least one lite parent in the substrate graph, so `lite` is the value reachability derives per ADR-056 D7, and the second line was the pre-widen leftover. The awk now reads the file, decides, then emits. The generator gained a check that counts tier declarations and exits 5 on a repeat.
+- **Downstream cure:** none. Patch bump; adopters on sync pick it up at the next `bassclef-sync`. No file changes tier.
+- **Old shape retired:** none.
+
+### Goal 2026-09-17b — shellcheck directive + generator version is the source of truth (v1.8.0 → v1.8.1, 2026-09-17)
+
+- **Change type:** content-change (2 content hashes; no entries added or removed)
+- **Fields:** none changed. 420 entries before and after. Two `content_hash` values move — `hook/10-abrupt-stop-recovery` (the #1719 fix: a fresh install is no longer read as an abrupt stop) and `script/generate-lite-manifest` (the version constant below).
+- **Version bump:** v1.8.0 → v1.8.1 (patch; content-hash change only; no schema shape shift, no entry count change).
+- **Rationale:** bassclef-upstream#1719 + PR #1720. Two fixes. The `SC1090` finding on the new test file now carries an in-file `# shellcheck source=/dev/null` directive rather than an allowlist row, so the suppression stays with the line it explains. Separately, `scripts/generate-lite-manifest.sh` held `MANIFEST_VERSION="1.7.0"` while the committed manifest read `1.8.0`, so every regeneration silently downgraded the version and the drift check then failed on a version nobody had changed. The constant is now `1.8.1` and the script is the one place the version lives.
+- **Downstream cure:** none. Patch bump; adopters on sync pick it up at the next `bassclef-sync`.
+- **Old shape retired:** none.
+
+### Goal 2026-09-16a — catalog-closure gate + widen to reachability (v1.6.1 → v1.8.0, 2026-09-17)
+
+- **Change type:** content-add (125 new entries) + policy-change (generator now gates on reachability)
+- **Fields:** none changed. 292 → 420 entries. Added by type: 47 hook (26 `session-reflection.d/` fragments + 21 retagged), 32 skill, 17 standard, 14 rule, 8 luminary, 3 lib, 3 template, 1 root-doc (`.claude/bassclef-orientation.md`). Zero entries removed (fixture guard at `.claude/hooks/tests/fixtures/2026-09-16-lite-catalog-closure/`).
+- **Version bump:** v1.6.1 → v1.8.0 (minor; additive content; existing type values only; no schema shape shift). Corrected 2026-09-17: this entry originally read v1.7.0 / 417 entries. No v1.7.0 manifest was ever committed — `93192ea0` took the manifest straight from v1.6.1 (292 entries) to v1.8.0 (420), because the first-run bundle rode in the same PR as the catalog widen.
+- **Rationale:** cli#90 + bassclef-upstream#1690. Lite entries referenced 96 files tagged `standard` (skills a lite skill dispatches, rules a lite rule composes, hooks the lite wiring fires, standards a lite rule cites) that never shipped. Same class as the hooks + libs gap cured for cli#82; ADR-056 D1 covered `source` closure only. `scripts/generate-lite-manifest.sh` now runs a manifest-seeded reachability walk (`scripts/walk-substrate-graph.py --closure-vs-manifest`) after the tag scan and exits 3 naming every reachable-but-untagged file. Tags stay the source of what ships; the walk validates them. `scripts/apply-lite-widen.sh --apply` retags to fixed point. `adrs` excluded (bassclef governance, cited as footnotes); two conditional citations sit in `standards/lite-closure-allowlist.txt` with reasons. Fragments and the orientation doc now ship via the manifest, so cli 1.1.1+ can retire its recursive hook-tree copy.
+- **Downstream cure:** none for cli 1.1.0+ (reads `manifest_version` major only; 1.8.x picks up automatically). Adopters on sync get the 128 files at next `bassclef-sync`. Consumers that pin an exact entry count must update (292 → 420). A consumer that pinned v1.7.0 on the strength of the original entry will not find it; pin v1.8.0.
+- **Old shape retired:** none — additive. The closure gate is on by default; `--no-closure-check` / `SKIP_LITE_CLOSURE_CHECK=1` bypass, logged.
+
 ### Goal 14c Step 6 — Zeller luminary added at lite tier (v1.6.0 → v1.6.1, 2026-09-15)
 
 - **Change type:** content-add (1 new luminary entry at lite tier)