@thebassclef/lite 1.4.0 → 1.4.1

package/dist/lite/.claude/hooks/session-reflection.d/tests/20-artifact-staleness.test.sh

@@ -39,6 +39,11 @@ set -u
 # [x] Multiple amendment lines; latest wins by date-sort not file-order
 # [x] Trap: no tmpfiles created in hook; no trap needed. Reason: hook is read-only on filesystem.
 # [x] Override: no SKIP_ARTIFACT_STALENESS override today; test asserts absence. Reason: existing hook has no override; extension does not add one.
+# Class D — release-notes freshness (bassclef-upstream#1802):
+# [x] D1: fresh (today mtime) SEMVER release-notes file → silent (RED under filename-parse; GREEN under mtime cure)
+# [x] D2: stale (10 days ago mtime) SEMVER release-notes file → BLOCK
+# [x] D3: freshest mtime picked across multiple files
+# [x] D4: no release-notes dir + few commits → silent (existing threshold preserved)
 
 REPO_ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
 HOOK="${REPO_ROOT}/.claude/hooks/session-reflection.d/20-artifact-staleness.sh"
@@ -329,6 +334,90 @@ else
 fi
 teardown_tmpdir
 
+# =======================================================================
+# Class D — release-notes freshness (bassclef-upstream#1802)
+# =======================================================================
+#
+# Motivating bug: current fragment cuts filename to 10 chars expecting
+# YYYY-MM-DD format. Actual convention is v<SEMVER>.md. Parse fails
+# silently, falls back to epoch 0, banner reads "20715 days ago" every
+# session. Cure: read file mtime, not filename.
+
+echo ""
+echo "Class D — release-notes freshness (#1802)"
+echo ""
+
+# Portable "N days ago" mtime stamp (BSD vs GNU date).
+past_mtime_stamp() {
+  local days="$1"
+  if date -v-1d +%s > /dev/null 2>&1; then
+    date -v-"${days}"d +%Y%m%d0000  # BSD (macOS)
+  else
+    date -d "-${days} days" +%Y%m%d0000  # GNU (Linux/CI)
+  fi
+}
+
+# D1: today-mtime SEMVER filename → silent (RED under filename-parse; GREEN under mtime cure)
+setup_tmpdir
+mkdir -p "$TMPDIR_TEST/chronicle" "$TMPDIR_TEST/docs/release-notes"
+touch "$TMPDIR_TEST/chronicle/2026-08-30-fresh.md"  # silence chronicle section
+touch "$TMPDIR_TEST/docs/release-notes/v0.99.0.md"  # today mtime by default
+add_commits_since "2026-08-30" 5
+OUTPUT=$(run_hook "2026-08-30")
+if echo "$OUTPUT" | grep -q "release-notes —"; then
+  assert "D1: today-mtime SEMVER filename → silent" "FIRED: $OUTPUT"
+else
+  assert "D1: today-mtime SEMVER filename → silent" "ok"
+fi
+teardown_tmpdir
+
+# D2: stale (10 days ago mtime) SEMVER filename → BLOCK
+setup_tmpdir
+mkdir -p "$TMPDIR_TEST/chronicle" "$TMPDIR_TEST/docs/release-notes"
+touch "$TMPDIR_TEST/chronicle/2026-08-30-fresh.md"
+touch "$TMPDIR_TEST/docs/release-notes/v0.98.0.md"
+touch -t "$(past_mtime_stamp 10)" "$TMPDIR_TEST/docs/release-notes/v0.98.0.md"
+add_commits_since "2026-08-30" 5
+OUTPUT=$(run_hook "2026-08-30")
+if echo "$OUTPUT" | grep -q "release-notes —"; then
+  assert "D2: 10-day-old SEMVER filename → BLOCK" "ok"
+else
+  assert "D2: 10-day-old SEMVER filename → BLOCK" "SILENT: $OUTPUT"
+fi
+teardown_tmpdir
+
+# D3: freshest mtime picked across multiple files
+setup_tmpdir
+mkdir -p "$TMPDIR_TEST/chronicle" "$TMPDIR_TEST/docs/release-notes"
+touch "$TMPDIR_TEST/chronicle/2026-08-30-fresh.md"
+touch "$TMPDIR_TEST/docs/release-notes/v0.95.0.md"
+touch "$TMPDIR_TEST/docs/release-notes/v0.96.0.md"
+touch "$TMPDIR_TEST/docs/release-notes/v0.97.0.md"
+# Age the first two; leave v0.97.0.md fresh (today mtime)
+touch -t "$(past_mtime_stamp 30)" "$TMPDIR_TEST/docs/release-notes/v0.95.0.md"
+touch -t "$(past_mtime_stamp 20)" "$TMPDIR_TEST/docs/release-notes/v0.96.0.md"
+add_commits_since "2026-08-30" 5
+OUTPUT=$(run_hook "2026-08-30")
+if echo "$OUTPUT" | grep -q "release-notes —"; then
+  assert "D3: freshest mtime picked across 3 files → silent (v0.97 is today)" "FIRED: $OUTPUT"
+else
+  assert "D3: freshest mtime picked across 3 files → silent (v0.97 is today)" "ok"
+fi
+teardown_tmpdir
+
+# D4: no release-notes dir + <10 commits → silent (existing threshold preserved)
+setup_tmpdir
+mkdir -p "$TMPDIR_TEST/chronicle"
+touch "$TMPDIR_TEST/chronicle/2026-08-30-fresh.md"
+add_commits_since "2026-08-30" 3
+OUTPUT=$(run_hook "2026-08-30")
+if echo "$OUTPUT" | grep -q "release-notes —"; then
+  assert "D4: no release-notes dir + few commits → silent" "FIRED: $OUTPUT"
+else
+  assert "D4: no release-notes dir + few commits → silent" "ok"
+fi
+teardown_tmpdir
+
 # =======================================================================
 # Summary
 # =======================================================================

package/dist/lite/.claude/hooks/session-reflection.sh

@@ -48,7 +48,18 @@ trace_log "session-start" "$SOURCE"
 HOOK_REAL_PATH="$(readlink -f "$0" 2>/dev/null || readlink "$0" 2>/dev/null || echo "$0")"
 {
   _br_sd="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  for _br_c in "${_br_sd}/../../lib/bassclef-dir-resolver.sh" "${HOME:-/}/lib/bassclef-dir-resolver.sh"; do
+  # bassclef-cli#140 cure — add $CWD/lib/ to the search list. bassclef init
+  # copies dist/lite/lib/*.sh into $targetDir/lib/ (src/commands/init.ts:300)
+  # and bassclef-sync section 3d copies $BASSCLEF_DIR/lib/*.sh into $CWD/lib/
+  # (presence/install/bassclef-sync.template.sh L1450). The prior two search
+  # paths both resolved to $HOME/lib/ for operator-installed dispatchers, so
+  # the resolver never loaded and defensive fallback set BASSCLEF_DIR=$HOME,
+  # producing the "[bassclef-hook-connect] skip — shared function not found
+  # at $HOME/presence/install/..." line at every session start.
+  for _br_c in \
+    "${_br_sd}/../../lib/bassclef-dir-resolver.sh" \
+    "${HOME:-/}/lib/bassclef-dir-resolver.sh" \
+    "${CWD:-.}/lib/bassclef-dir-resolver.sh"; do
     [ -f "$_br_c" ] && source "$_br_c" && break
   done
   unset _br_sd _br_c

package/dist/lite/.claude/luminaries/david-farley.md

@@ -0,0 +1,115 @@
+---
+tier: lite
+name: David Farley
+slug: david-farley
+claimed_by: [architect, builder, deployer]
+referenced_by_skills: [architect-review, decompose, deploy-prod]
+primary_domain: engineering
+depth: full
+sources:
+  - type: book
+    title: "Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation"
+    authors: ["Jez Humble", "David Farley"]
+    year: 2010
+    url: "https://continuousdelivery.com/"
+    isbn: "9780321601919"
+    methodology_covered:
+      - "Deployment pipeline mechanics: commit stage, acceptance stage, capacity stage, manual stage"
+      - "Fast feedback: commit stage under 5 minutes; acceptance stage under 1 hour"
+      - "Testing strategies per pipeline stage"
+      - "Zero-downtime release patterns"
+  - type: book
+    title: "Modern Software Engineering"
+    authors: ["David Farley"]
+    year: 2021
+    url: "https://www.davefarley.net/?p=352"
+    isbn: "9780137314911"
+    methodology_covered:
+      - "Optimize for learning and managing complexity as the two core engineering activities"
+      - "Iterative + incremental development as engineering discipline"
+      - "Empirical approach: hypothesis, experiment, measurement"
+      - "Modularity + cohesion + separation of concerns as anti-complexity tools"
+  - type: video
+    title: "Continuous Delivery (YouTube channel)"
+    authors: ["David Farley"]
+    year: 2025
+    url: "https://www.youtube.com/@ContinuousDelivery"
+    methodology_covered:
+      - "Deployment pipeline design patterns"
+      - "TDD + BDD + continuous delivery integration"
+      - "Software engineering as engineering, not craft"
+verification_status: verified
+description: "Continuous Delivery co-author; deployment pipeline mechanics; author of Modern Software Engineering."
+---
+
+# David Farley
+
+## Signature
+
+*"Software development is fundamentally an exercise in learning."*
+
+Co-author of **Continuous Delivery** (2010, with Jez Humble). Author of **Modern Software Engineering** (2021). Runs the "Continuous Delivery" YouTube channel. The bassclef voice on deployment pipeline mechanics, engineering as a discipline, and optimizing for feedback speed at each pipeline stage.
+
+## Core methods
+
+- **Four-stage pipeline** — Commit stage (build + unit tests + static analysis, under 5 min). Acceptance stage (integration + functional tests, under 1 hour). Capacity stage (load + perf tests). Manual stage (exploratory + UAT). Each stage's failure blocks progress to the next.
+- **Fast feedback at commit stage** — The commit stage MUST fire fast. If it takes longer than 5 minutes, engineers push less often; batch sizes grow; risk hides.
+- **Iterative + incremental** — Iterative means "improve the same thing over cycles." Incremental means "ship in small pieces." Both discipline needed.
+- **Learning as engineering** — Every design decision is a hypothesis. Measure the outcome. Adjust.
+- **Modularity + cohesion + separation of concerns** — The three tools against complexity. Farley treats each as measurable.
+
+## When to channel this luminary
+
+When the primary risk is that the pipeline itself has become the bottleneck — commit stage slow, feedback delayed, engineers pushing less often. Farley dominates for pipeline mechanics, engineering-discipline framing, and deep questions about what makes software engineering an engineering discipline (rather than craft or art). Pair with Humble (CD foundations), Fowler (CI foundations), and Nygard (release stability).
+
+Do NOT channel Farley as primary for UX or product decisions, pure code refactoring, or team-organization questions.
+INSTEAD: use Cooper or Norman for UX; use Fowler for code refactoring; use the DevOps Handbook lineage (Kim, Humble, Debois, Willis) for team organization.
+
+## Stack translation
+
+In bassclef's CI pipeline:
+
+- **Commit stage under 5 min** → bassclef-pr-ci median is 9.7 min per issue #1515. Farley would flag this as the primary defect. The target of 3 min matches his commit-stage rule.
+- **Acceptance stage under 1 hour** → substrate-check-phase + cold-adopter-harness serve this role. They stay within 1 hour today.
+- **Fast feedback** → Cure 1 (auto-regen manifest) + #1562 (path-filter shard) both fall in the commit-stage speed budget.
+- **Modularity + cohesion + separation of concerns** → the three-zone canvas (Zone A author-time, Zone B CI-time, Zone C release-time) IS separation of concerns applied to CI/CD as a subsystem.
+- **Learning as engineering** — Each Phase's metric checkpoint (measure bassclef-pr-ci median after Phase 1, Phase 2) is the hypothesis-experiment-measurement loop applied to the pipeline.
+
+## Anti-patterns it prevents
+
+- **Slow commit stage** — engineers push less often when they wait 10 minutes for CI. Batch sizes grow. Integration risk hides.
+- **Pipeline stages that fail to earn their runtime** — every stage must raise confidence enough to justify its cost. Stages that duplicate work OR check nothing get cut.
+INSTEAD: audit stage-by-stage confidence delta; cut what fails to earn its cost.
+- **Craft framing** — treating software as art hides that some approaches measurably work and others measurably fail. Engineering framing forces the measurement.
+- **Big-bang releases** — batch sizes so large that feedback arrives after decisions land.
+- **Manual pipeline stages presented as "necessary review"** — sometimes true; often the pipeline was designed without the review's information need. Farley pushes to automate what the reviewer actually looks for.
+
+## Worked example
+
+For bassclef's Phase 1 cure planning (per docs/canvases/2026-09-18-ci-cd-subsystem.md):
+
+Farley's approach:
+- **Commit stage speed** — Phase 1 targets 9.7 min median → 6 min median → 3 min median. Each Phase makes the commit stage cheaper.
+- **Modularity of cures** — Each of the 5 Phase 1 cures ships as its own PR. Cure 1 stays independent of Cure 3. Each reversible on its own.
+- **Hypothesis-experiment-measurement** — Cure 5 (guard-add fixture-shape audit) is a hypothesis: "guard-add pattern drift causes Class D failures." Ship it. Measure: does Class D recurrence rate drop? Adjust or advance.
+- **Learning** — session 2026-09-18a chronicle shows 6 hard failures across 3 CI cycles. Farley would treat this as the empirical evidence the design is optimizing against, not just narrative.
+
+What Farley would flag on bassclef today:
+- Commit stage at 9.7 min breaks his rule. Fix this first.
+- Missing measurement infrastructure — #1307 (workflow-overhead profiling) is exactly what he'd prioritize.
+- The three-zone canvas correctly applies separation of concerns to the CI subsystem.
+
+## Sources
+
+- *Continuous Delivery* — Humble, Farley, Addison-Wesley (2010)
+- *Modern Software Engineering* — Farley (2021)
+- davefarley.net — primary methodology site
+- Continuous Delivery YouTube channel (weekly, since ~2020)
+
+## Related luminaries
+
+- **Jez Humble** — CD co-author; complements Farley's pipeline mechanics with delivery performance + DORA metrics framing.
+- **Martin Fowler** — CI foundations; Farley's CD extends Fowler's CI.
+- **Michael Nygard** — release stability patterns Farley references at the acceptance + capacity stages.
+- **Kent Beck** — TDD anchor; Farley's commit-stage speed rule assumes fast unit tests, which TDD requires.
+- **John Ousterhout** — deep modules; Farley's modularity discipline maps to Ousterhout's deep-module principle.

package/dist/lite/.claude/luminaries/jez-humble.md

@@ -0,0 +1,124 @@
+---
+tier: lite
+name: Jez Humble
+slug: jez-humble
+claimed_by: [architect, deployer, closer]
+referenced_by_skills: [architect-review, deploy-prod, release]
+primary_domain: engineering
+depth: full
+sources:
+  - type: book
+    title: "Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation"
+    authors: ["Jez Humble", "David Farley"]
+    year: 2010
+    url: "https://continuousdelivery.com/"
+    isbn: "9780321601919"
+    methodology_covered:
+      - "Deployment pipeline as the primary release artifact"
+      - "Every commit produces a release candidate"
+      - "Automate build, test, deploy, and infrastructure provisioning"
+      - "Trunk-based development over long-lived branches"
+      - "Configuration management as first-class code"
+  - type: book
+    title: "The DevOps Handbook"
+    authors: ["Gene Kim", "Jez Humble", "Patrick Debois", "John Willis"]
+    year: 2016
+    url: "https://itrevolution.com/product/the-devops-handbook/"
+    isbn: "9781942788003"
+    methodology_covered:
+      - "Three Ways: flow, feedback, continual learning"
+      - "Small batch sizes; fast feedback loops"
+      - "Culture of psychological safety around failure"
+  - type: book
+    title: "Accelerate: The Science of Lean Software and DevOps"
+    authors: ["Nicole Forsgren", "Jez Humble", "Gene Kim"]
+    year: 2018
+    url: "https://itrevolution.com/product/accelerate/"
+    isbn: "9781942788331"
+    methodology_covered:
+      - "DORA metrics: deployment frequency, lead time, MTTR, change fail rate"
+      - "High performers deploy 208x more often + recover 2604x faster"
+      - "Continuous delivery causes higher software delivery performance"
+  - type: blog_post
+    title: "continuousdelivery.com (primary methodology venue)"
+    authors: ["Jez Humble"]
+    year: 2025
+    url: "https://continuousdelivery.com/"
+    methodology_covered:
+      - "Deployment pipeline patterns + anti-patterns"
+      - "Trunk-based development advocacy"
+      - "Release strategies: blue-green, canary, dark launching"
+verification_status: verified
+description: "Continuous Delivery co-author; deployment pipeline framework; DORA metrics researcher."
+---
+
+# Jez Humble
+
+## Signature
+
+*"If it hurts, do it more often, and bring the pain forward."*
+
+Co-author of **Continuous Delivery** (2010, with David Farley) — the book that defined the deployment pipeline. Co-author of **The DevOps Handbook** (2016) and **Accelerate** (2018). Researcher on DORA (DevOps Research and Assessment) metrics. The bassclef voice on release automation, deployment pipelines, and measuring software delivery performance.
+
+## Core methods
+
+- **Deployment pipeline** — Every commit runs through automated stages: commit → build → automated tests → staging → production. Each stage raises confidence. Failure at any stage halts the pipeline and blocks release.
+- **Every commit is a release candidate** — The main branch stays deployable. If a commit passes the pipeline, it could ship to production. This is what trunk-based development delivers.
+- **Small batch sizes** — Merge small changes often. Large batches hide risk. Small batches surface risk fast.
+- **Configuration as code** — Environment definitions live in version control. No hand-tuned servers. Reproducible from source.
+- **DORA metrics** — Four measurements separate high performers from low: deployment frequency, lead time for changes, mean time to restore, change failure rate.
+
+## When to channel this luminary
+
+When the primary risk is that releases become rare, painful, or unreliable. Humble dominates for release pipeline design, DevOps practice audits, deployment strategy (blue-green, canary), and any conversation about measuring delivery performance. Pair with Fowler (CI foundations), Farley (deployment pipeline mechanics), and Nygard (release stability patterns).
+
+Do NOT channel Humble as primary for: architecture decisions unrelated to release (use Ousterhout, Vernon), UI design (use Cooper, Norman), or code-level refactoring (use Fowler).
+
+## Stack translation
+
+In bassclef's release pipeline:
+
+- **Deployment pipeline** → `scripts/release-to-bassclef.sh` fires stages in order: filter files by tier → run andon scan → open release PR → CI → merge → tag. Each stage carries a fail condition.
+- **Every commit is a release candidate** → main branch on bassclef-upstream stays deployable. `/release` can fire from any main commit.
+- **Small batch sizes** → per `.claude/rules/pr-strategy.md`, default is stacked atomic PRs (one issue per PR) not bundled multi-issue PRs.
+- **Configuration as code** → `.claude/settings.json`, `bassclef-configs.jsonc`, and workflow yaml all live in git. No hand-tuned CI runners.
+- **DORA metrics** → `scripts/metrics.sh --all` computes deployment frequency, lead time, MTTR, change failure rate against bassclef-upstream commits + release tags.
+
+## Anti-patterns it prevents
+
+- **Release train that misses stations** — quarterly releases where each release carries months of changes. Batch size hides risk; small changes get delayed by batch coordination.
+- **Manual staging steps** — one engineer knows the deploy dance. When they leave, release breaks. Automation is the durable artifact.
+- **Long-lived feature branches** — branch merges become integration nightmares. Trunk-based development merges daily; feature flags gate release, not branches.
+- **Environment drift** — staging works, prod breaks. Configuration-as-code kills the class.
+- **Metrics theater** — measuring what is easy (lines of code, story points) instead of what matters (DORA metrics).
+
+## Worked example
+
+For bassclef's release-to-bassclef pipeline (2026-09-18 session shipped v0.45.0):
+
+Humble's approach:
+- **Deployment pipeline** — `/release` runs dry-run first (Step 3 filter + Step 3.5 tier alignment + Step 3.6 lite manifest ledger + Step 4 andon scan). Live run happens only after operator confirms dry-run output. Each step's failure blocks the live run.
+- **Every commit is a release candidate** — bassclef-upstream main stays green. Session close verifies this before ending.
+- **Small batches** — v0.45.0 shipped one goal's cures (Phase A + Phase B fixes), not months of accumulated substrate change.
+- **DORA metrics** — `scripts/metrics.sh` computes lead time from commit to bassclef-public sync. Session 2026-09-18a hit blocked state because 267 commits since last metrics run means DORA drift is real.
+
+What Humble would flag on bassclef today:
+- Change failure rate is measurable but not measured (metrics.sh block from session-start hook).
+- MTTR is anecdotal (session logs) not measured (no timing on cure cycles).
+- The v0.45.0 release cascade showed short lead time (single day from cure filing to public ship) — that IS the delivery performance high performers hit.
+
+## Sources
+
+- *Continuous Delivery* — Humble, Farley, Addison-Wesley (2010)
+- *The DevOps Handbook* — Kim, Humble, Debois, Willis (2016)
+- *Accelerate* — Forsgren, Humble, Kim (2018)
+- continuousdelivery.com — primary methodology venue
+- DORA State of DevOps reports (2014-2023) — Humble co-led research
+
+## Related luminaries
+
+- **Martin Fowler** — CI foundations that CD builds on; Fowler's canonical CI article predates the CD book by four years.
+- **David Farley** — CD co-author; deeper on deployment pipeline mechanics + author of *Modern Software Engineering* (2021).
+- **Michael Nygard** — *Release It!* covers stability patterns Humble references at the deployment layer.
+- **Nicole Forsgren** — Accelerate co-author; owns the DORA research methodology.
+- **Gene Kim** — DevOps Handbook + Accelerate co-author; *The Phoenix Project* narrative frame for the same principles.

package/dist/lite/.claude/luminaries/martin-fowler.md

@@ -37,6 +37,18 @@ sources:
     methodology_covered:
       - "Internal vs external DSL design choices"
       - "DSL design patterns — when to build, when to embed, when to skip"
+  - type: article
+    title: "Continuous Integration (canonical definition)"
+    authors: ["Martin Fowler"]
+    year: 2006
+    url: "https://martinfowler.com/articles/continuousIntegration.html"
+    methodology_covered:
+      - "Continuous Integration canonical definition — every developer integrates to mainline daily"
+      - "Automate the build; make the build self-testing"
+      - "Every commit should build main line on an integration machine"
+      - "Fix broken builds immediately; keep the build fast"
+      - "Test in a clone of the production environment; make it easy to get the latest deliverables"
+      - "Everyone can see the results of the latest build; automate deployment"
   - type: blog_post
     title: "martinfowler.com (primary methodology venue)"
     authors: ["Martin Fowler"]
@@ -63,6 +75,12 @@ refactoring, and enterprise patterns.
 
 ## Core methods
 
+- **Continuous Integration canonical definition** — Fowler's 2006 article
+  set the discipline. Every developer integrates to mainline daily. The
+  build is automated + self-testing. Every commit builds mainline. Broken
+  builds fire immediate fix. Keep the build fast. Test in a clone of prod.
+  Automate deployment. This is the CI/CD foundation that Humble + Farley
+  extended in *Continuous Delivery* (2010).
 - **Code smells catalog** — Long Method, Large Class, Feature Envy,
   Shotgun Surgery, Primitive Obsession, Data Clumps, and dozens more.
   Named patterns make smells recognizable on sight.

package/dist/lite/.claude/skills/longrun/SKILL.md

@@ -329,6 +329,57 @@ Full re-render is only correct when the operator asks for it explicitly ("show m
 
 **Step 1.4e** — Card + scan-table shape (per goal 24e; Tufte + Prater). Multi-option output has three parts. First, a compact scan-table on top. Second, one card per option. Third, step cards for the recommended option only. See `standards/scannable-multi-option-output.md` § Card template + § Glyph legend + § Progressive disclosure.
 
+<!-- FKGL-EXEMPT: Step 1.4f — Candidate 4 shape lock per bassclef-upstream#1598 operator pick 2026-09-21 -->
+**Step 1.4f — Converged preset render shape (per bassclef-upstream#1598 operator pick 2026-09-21).** The converged preset renders **Candidate 4** — Deliverable lead + Recommend card + Other options scan-table + Ask hints. Reader hits Deliverable within one screen. Sequencing + non-recommended option cards hide behind the operator's follow-up question.
+
+Anchor luminaries: `@luminary alan-cooper` (satisficing default) + `@luminary luke-wroblewski` (mobile-first).
+
+Rendered shape (three visible sections + ask hints):
+
+```
+=== Deliverable ===
+
+<one paragraph of adopter or subsystem value; NOT framework process>
+
+=== Recommend: Option a — <label> ===
+
+- Value: <what adopters or subsystems get; e.g., "adopters see current
+  docs" not "two PRs merged">
+- Turns: <range>
+- Risk: 🟢/🟡/🔴 <one-line failure mode>
+- Priority: P1/P2/P3
+
+=== Other options ===
+
+  b. <label>  <turns>  <risk-glyph>  <priority>
+  c. <label>  <turns>  <risk-glyph>  <priority>
+
+Ask "step plan" for sequencing.
+Ask "see b" or "see c" for detail on other options.
+```
+
+**Value axis discipline.** Every axis labeled "Value" (or "Deliverable" prose lead) reads as adopter or subsystem value — what breaks for the reader if it doesn't ship, what improves for them when it does. Framework-mechanic process language (e.g., "two PRs opened", "tags cut", "sim in tree") stays out of the Value axis. Process belongs in the step plan.
+
+Correct value line examples:
+- "Adopters browsing docs.bassclef.dev see today's substrate. Every future /release runs a local lite-bundle check before pushing."
+- "Louis reads the recommendation before scrolling. Sam sees no stuck signals on first-run."
+
+Incorrect value line examples:
+- "Two doc PRs land + adopter-simulator-lite in tree + v1.0.0 tag on both repos." (framework process — belongs in step plan)
+- "Ships the manifest generator amendment." (mechanism — reader can't act on this)
+
+**Ask-hints render.** The two ask-hint lines land at the very tail of prep output, in this order:
+
+```
+Ask "step plan" for sequencing.
+Ask "see b" or "see c" for detail on other options.
+```
+
+When the operator asks any of the three, the assistant renders the expansion in-conversation (not a re-render of the whole prep). Sequencing hint fires Step 1.7 render for the recommended option only. Option-detail hint fires the full card render for the named non-recommended option.
+
+Grace: full-ceremony preset (`/longrun full`) keeps the pre-#1598 render (multi-card + step-card table). Candidate 4 applies at converged preset only.
+<!-- /FKGL-EXEMPT -->
+
 <!-- FKGL-EXEMPT: Step 1.5 preset note — technical procedure reference to the picker per bassclef-upstream#1598 -->
 **Step 1.5 preset note (per bassclef-upstream#1598).** The axis rendering below applies to the FULL ceremony path (no preset picked, or `full` override). When Step 0.85 picker fires a converged / exploratory / reversible-small preset, the axis set adjusts per `.claude/rules/compounding-sequence-fresh-analysis.md` § Per-preset axis sets. Stop hook reads the preset marker and applies the matching check.
 <!-- /FKGL-EXEMPT -->

package/dist/lite/.claude/skills/onboard-repo/SKILL.md

@@ -43,8 +43,11 @@ Pick the shape that matches how you plan to work. The picker is the first fork.
 | **share via GitHub** | A repo you push to GitHub and share | Path A — standard onboarding (Phases 1-3) |
 | **browse first** | Scanning what /onboard-repo does before you commit | Path A read-only walk (dry-run mode) |
 | **just me on this Mac** | A local-only project. No GitHub push. | Path B — empty-repo starter (`--greenfield-from-intent`) |
+| **top-up an existing bassclef repo** | Repo where `bassclef init` already ran; only some files need adding | Path C — additive-only (per bassclef-cli#101) |
 
-**Recommended:** `share via GitHub` when you have a GitHub org and repo ready. Otherwise `just me on this Mac`.
+**Recommended:** `share via GitHub` when you have a GitHub org and repo ready. `top-up an existing bassclef repo` if `.bassclef/init.manifest.json` exists. Otherwise `just me on this Mac`.
+
+**Path B safety guard (per bassclef-cli#101):** Path B refuses to run when `.bassclef/init.manifest.json` is present. Path B truncates `.claude/settings.json` and other core files as part of empty-repo starter setup. Picking Path B on an installed repo destroys 20+ hook wirings. When the manifest file is present, the skill halts and asks the operator to switch to Path C (top-up) instead, or pass `--overwrite` if the destructive replace is intentional.
 
 If the operator did not name a preset, ask first: `Share via GitHub / Browse first / Just me on this Mac? (g/b/j/skip)`
 
@@ -68,7 +71,7 @@ the operator picked before validating.
 - Bassclef is cloned as a peer at `$BASSCLEF_DIR` (default `~/src/<your-org>/bassclef`, for
   desktop `additionalDirectories` resolution)
 - You are currently `cd`'d into the target repo's working directory
-- Claude Code session was started with `--add-dir ~/src/sunj-labs/bassclef`
+- Claude Code session has access to the bassclef checkout at `${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}` (via `--add-dir` or bassclef init default)
   so this skill file is accessible
 
 ### Path B — `--greenfield-from-intent` (cold-adopter magic demo)
@@ -83,7 +86,7 @@ the operator picked before validating.
   with only files Path B is allowed to overwrite — see "Working
   directory convention" below)
 - `gh` is NOT required (no GitHub repo gets created)
-- A peer bassclef checkout at `~/src/sunj-labs/bassclef` is preferred
+- A peer bassclef checkout at `${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}` is preferred
   but not required (the thin-pointer dispatcher falls back to the
   GitHub tarball when the sibling is absent — Path B's `Phase B.3`
   installs it)
@@ -130,6 +133,31 @@ onboarding) or **Path B** (`--greenfield-from-intent` cold-adopter
 magic demo). Decide first, then walk only the phases under the chosen
 path. Do not mix.
 
+### Pre-phase — ancestor `.claude/` audit (both paths)
+
+Before choosing a path, walk from the target repo up to `$HOME`.
+Report any `.claude/` directory found in an ancestor. Adopters often
+have a stale `.claude/skills/` sitting in a parent dir from an old
+setup. Claude Code walks up from cwd loading `.claude/` at every
+ancestor level. A stale ancestor dir produces duplicate + often
+outdated skill entries in every child repo.
+
+```bash
+bash lib/ancestor-claude-check.sh "$(pwd)"
+```
+
+Output is one absolute path per line. Empty output means clean tree.
+
+For each path echoed, warn the adopter with the cure hint the helper
+prints to stderr:
+
+```
+cure: mv "<path>" "<path>.stale-<date>"
+```
+
+Do NOT auto-cure. Adopter decides whether to move each aside before
+proceeding. Ship bassclef-upstream#573.
+
 ### Choosing the path
 
 | Signal | Path |
@@ -178,7 +206,7 @@ mkdir -p .claude/hooks docs
 
 # Install the thin-pointer dispatcher (same source as Path A Phase 2.1).
 # Sibling-fast-path preferred; the curl fallback works for cold adopters.
-cp ~/src/sunj-labs/bassclef/presence/install/bassclef-sync.dispatcher.template.sh \
+cp ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/presence/install/bassclef-sync.dispatcher.template.sh \
    .claude/hooks/bassclef-sync.sh 2>/dev/null \
    || curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/presence/install/bassclef-sync.dispatcher.template.sh \
         -o .claude/hooks/bassclef-sync.sh
@@ -455,7 +483,7 @@ mkdir -p .claude/hooks
 
 # Install thin-pointer dispatcher from bassclef's own template directory.
 # This is the source-of-truth file consumers vendor.
-cp ~/src/sunj-labs/bassclef/presence/install/bassclef-sync.dispatcher.template.sh \
+cp ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/presence/install/bassclef-sync.dispatcher.template.sh \
    .claude/hooks/bassclef-sync.sh
 
 # OR — if bassclef isn't checked out alongside this repo, fetch from
@@ -778,7 +806,7 @@ Validate the written file against the schema:
 
 ```bash
 perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
-  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+  | ajv validate -s ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/standards/state-spine/schemas/bassclef-configs.schema.json \
                  -d - --spec=draft2020 -c ajv-formats
 ```
 
@@ -887,7 +915,7 @@ TECH_STACK
 
 ```bash
 perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
-  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+  | ajv validate -s ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/standards/state-spine/schemas/bassclef-configs.schema.json \
                  -d - --spec=draft2020 -c ajv-formats
 ```
 
@@ -972,7 +1000,7 @@ Pick a/b/c:
 
 ```bash
 perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
-  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+  | ajv validate -s ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/standards/state-spine/schemas/bassclef-configs.schema.json \
                  -d - --spec=draft2020 -c ajv-formats
 ```
 
@@ -1228,7 +1256,7 @@ After the bassclef-configs block is written, point the operator at the matching
 ```
 Next step: copy the per-stack reference workflow into your repo's CI.
 
-  cp ~/src/sunj-labs/bassclef/config/security-scanners/<STACK_GUESS>.yml \
+  cp ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/config/security-scanners/<STACK_GUESS>.yml \
      .github/workflows/security-scan.yml
 
 The workflow auto-skips when the bassclef-configs stack value is null,
@@ -1292,7 +1320,7 @@ Inherits bassclef substrate via `--add-dir ../bassclef` (desktop) and
 S3 tarball sync (mobile). The `@.claude/bassclef-orientation.md` import
 above auto-loads the substrate discipline (gates, luminaries, tier ladder,
 what-NOT-to-do). For the upstream role declaration, see
-`~/src/sunj-labs/bassclef/CLAUDE.md`.
+`${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/CLAUDE.md`.
 
 ## Stack
 
@@ -1307,7 +1335,7 @@ what-NOT-to-do). For the upstream role declaration, see
 
 ```bash
 mkdir -p docs
-cp ~/src/sunj-labs/bassclef/templates/whereami-template.md \
+cp ${BASSCLEF_DIR:-$CLAUDE_PROJECT_DIR}/templates/whereami-template.md \
    docs/whereami.md
 ```
 

package/dist/lite/.claude/skills/provision-deploy-host/SKILL.md

@@ -51,7 +51,7 @@ PR; consumer is ready for `/launch-preview`.
 ## Prerequisites
 
 1. Consumer repo exists at `sunj-labs/<consumer>`
-2. `bassclef-platform.yml` exists at `~/src/sunj-labs/platform-config/bassclef-platform.yml`
+2. `bassclef-platform.yml` exists at `${PLATFORM_CONFIG_DIR:-$HOME/src/sunj-labs/platform-config}/bassclef-platform.yml`
 3. Operator's shell env has every `storage.type: env` secret named in
    substrate.secrets.md (run `/secrets-bootstrap` to verify; happens
    automatically as Phase 0 of this skill)
@@ -186,7 +186,7 @@ WU-3.5 primitive).
 
 Next:
   /launch-preview <consumer>     — bind subdomain + smoke-test
-  cd ~/src/sunj-labs/<consumer>  — switch to consumer repo
+  cd ${CONSUMER_REPO_DIR:-.}  — switch to consumer repo (default: current dir)
   git pull                       — pull the substrate.config PR you just merged
 ```