@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

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

@@ -0,0 +1,311 @@
+---
+name: release
+description: "Ship framework files from bassclef-upstream to public bassclef, filtered by tier. Dry-runs first, reports tier counts plus andon scan plus sibling smoke evidence. On operator confirm runs the live release and opens a PR. Per ADR-029."
+problem: "Framework files ship from upstream to public bassclef through many manual steps. Dry-run catches slip past."
+value: "Ships framework files from bassclef-upstream to public bassclef. Filtered by tier. Dry-runs first."
+inputs: [Optional tier filter, Dry-run or apply flag]
+outputs: [Files shipped, Dry-run diff, Public PR, Tag drop]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+modes: [default, --dry-run, --skip-dry-run]
+composes_with: [verify, state-a-problem, value-prop, kiss]
+---
+<!-- andon-allow: operator-private -->
+<!-- andon-allow: bassclef-upstream -->
+
+# /release
+
+## What you get
+
+A staged path to ship framework files from bassclef-upstream to public bassclef.
+
+`/release` runs a dry-run first. It reports the tier filter result. It reports the andon scan. It reports the sibling smoke evidence. It waits for your confirmation. Then it runs `/verify`. Then it executes the live release.
+
+The live step does five things. It tags the source SHA. It rsyncs the filtered set to the target. It commits on a release branch in public bassclef. It opens a PR. After you merge the PR, it cuts semver tags on both repos with matching names.
+
+Per ADR-040 Decision 5, a second target — `bassclef-lite` — ships alongside `bassclef` for solo adopters. Same pipeline. Different tier filter. Both targets share the andon scan and sibling smoke discipline.
+
+## When to use it
+
+- You shipped one or more framework changes locally and want them in public bassclef.
+- A session closed a goal whose acceptance includes "shipped to public."
+- You are preparing Doors Open and need to prove the pipeline works.
+
+Adopter sessions do not run `/release`. Adopters read the public bassclef release page and pull via `bassclef-sync`. Only bassclef-upstream sessions ship releases.
+
+## When NOT to use
+
+Do not use `/release` to file evolution tickets. That is `/promote`. Do not use it to sync docs. That is `/docs-sync`. Do not use it on a dirty source tree. Commit or stash first. Do not use it when a prior release PR is still open on public. The new one would stack cumulatively.
+
+## FAQ
+
+### What are the steps of a release?
+
+1. Dry-run — reports tier counts, andon scan, target dir, sibling smoke prompt.
+2. Sibling smoke evidence — you paste PASS / FAIL / DEFERRED per the sibling-smoke rule.
+3. Operator confirmation — you approve or decline the ship.
+4. `/verify` — post-build check against the changes.
+5. Live release — tag source, rsync filtered set, commit + push release branch, open PR.
+6. PR body amend — replace the template stub with the recap drafted before Step 1.
+7. Report — surface the PR URL.
+8. Semver tag on both repos after the PR merges.
+
+### Why dry-run first?
+
+The dry-run reports what the live release will do. It does not touch public bassclef. You see tier counts. You see andon scan hits. You see the target directory. You see the sibling smoke evidence prompt.
+
+If andon trips, the dry-run stops. It asks you to fix the offending file. Retag `tier: private`. Or scrub the leak. Or add `# andon-allow: <term>` header. Then retry.
+
+### What is the sibling smoke evidence step?
+
+Per the sibling-smoke rule, some releases need a real Claude Code session on a sibling repo before shipping. This applies to releases touching adopter-observable files — hooks, rules, skills, agents, lib, schemas, sync templates.
+
+You paste one of:
+
+```
+PASS: Sibling smoke: ran <sibling-repo> SessionStart at <ISO>; clean — <observation>
+FAIL: Sibling smoke: ran <sibling-repo> SessionStart at <ISO>; FAIL — <observation>
+DEFERRED: <rationale>; follow-on tracked at #<NNN>
+```
+
+Silence is not deferral. The default is "run the smoke before /release."
+
+- **PASS** — proceed to Step 3.
+- **FAIL** — STOP. The release holds until the fix ships and a follow-up smoke confirms PASS.
+- **DEFERRED** — proceed only when the rationale names a non-blocking case (pure no-behavior rename). Cite a follow-on ticket. Otherwise STOP.
+
+V1 is ADVISORY. Silence is logged as a discipline miss but does not block dispatch. V2 flips to BLOCK once one calibration cycle ships.
+
+### What does the live release step actually do?
+
+The script `scripts/release-to-bassclef.sh` does six things:
+
+1. Pre-flight — dirty-tree guard on source AND target.
+2. Tags source — `release-YYYY-MM-DD-<sha>`.
+3. Re-runs tier filter and andon scan. Defense in depth. Files may have changed since dry-run.
+4. rsyncs the filtered set to the target with a constrained `--delete`.
+5. Commits in the target on `release/YYYY-MM-DD-<sha>` branch.
+6. Pushes the branch and opens a PR against public bassclef `main`.
+
+For the bassclef-lite target (per ADR-040 D5), a sibling branch opens with `tier: lite | standard` filter. It uses a distinct release tag suffix.
+
+### What does the PR body amend step do?
+
+The script writes a template body with the stub "Operator amends with the substantive changes in this release window." Adopters reading the PR see this stub instead of the actual story.
+
+Step 4.5 replaces the stub with the recap drafted before Step 1. The recap carries Problem + Summary + Test plan sections. It composes `/state-a-problem brief` + `/value-prop tweet` + session log entries.
+
+The step reads the just-opened PR body. It scans for the stub. If the stub is present, it amends via `gh pr edit`. Step 5 does not fire until the amendment lands OR `SKIP_RELEASE_PR_AMEND=1` is set.
+
+### How do the semver tags work after the PR merges?
+
+Per ADR-039 and the release-tagging standard, after you merge the release PR:
+
+1. Draft the tag name. The skill reads the change set and proposes a bump per semver policy.
+   - **Major** — adopter-visible breaking change (rename, tier vocab, ADR-031 level).
+   - **Minor** — new substrate surface.
+   - **Patch** — cure only.
+2. Draft release notes. Group by rule / hook / skill / standard / luminary / agent / ADR / cure. One line per PR with links. Apply `/kiss --grade10` to the body BEFORE writing to file per bassclef-upstream#634. The `pre-gh-release-body-scrub.sh` hook fires on `gh release create`. Unscrubbed notes BLOCK the call.
+3. Cut the tag on both repos with the same name. `bassclef-upstream` is the source of truth. The tag on public `bassclef` (and `bassclef-lite`) is what adopters see. The GitHub Release page publishes on public bassclef only.
+
+First tag ever cut is `v0.1.0`. Confirm the tag name at Step 2 before the pipeline runs.
+
+### What does /release refuse to do?
+
+- Dirty source tree. Commit or stash first.
+- Dirty target tree. Commit or stash in `~/src/sunj-labs/bassclef/` first.
+- Andon scan hit per ADR-029. Andon is required, not advisory.
+- Invalid tier value on any file. Must be `private | basic | premium | public | lite | standard`.
+- Tag collision. A release tag already exists at this SHA. Release was already cut today.
+
+## Details below the fold
+
+### Procedure — full
+
+**Step 1 — Dry-run.**
+
+```bash
+bash scripts/release-to-bassclef.sh --dry-run
+```
+
+Output reports source SHA. Would-be release tag. Tier bucket counts. Andon result. Target dir. Sibling smoke evidence prompt.
+
+If andon trips, STOP. Cure per FAQ above.
+
+**Step 1.5 — Sibling smoke evidence.** Paste PASS / FAIL / DEFERRED per the FAQ.
+
+**Step 2 — Operator confirmation.** Surface the dry-run summary. Ask: "Ship $count_inc files (tier=basic|public) to public bassclef on branch release-YYYY-MM-DD-<sha>?" Decline stops. Approve proceeds.
+
+**Step 3 — /verify.** Run `/verify`. It runs the check against your changes (substrate-clarity-gate on edits, etc.). It catches anything the dry-run missed.
+
+**Step 4 — Live release.** `bash scripts/release-to-bassclef.sh`. See FAQ for what the script does.
+
+**Step 4.5 — Amend PR body.** Read the just-opened PR body. Scan for the template stub. If present, amend via `gh pr edit --body-file <recap-file>`. Re-read to confirm the stub is gone. Step 5 does not fire until this lands.
+
+**Step 5 — Report.** Surface the PR URL. You review and merge in public bassclef.
+
+**Step 6 — Cut semver tags.** After the PR merges, draft release notes. Run `/kiss` on the notes. Then run the automation script (per bassclef-upstream#1005).
+
+The script does the rest. It reads the notes. It infers the semver bump. It cuts tags on both repos. It creates the GitHub Release page.
+
+```bash
+# Dry-run first — always
+RELEASE_STEP6_DRY_RUN=1 bash scripts/release-step6.sh release-notes-<version>.md
+
+# Confirm the proposed tag, then live
+bash scripts/release-step6.sh release-notes-<version>.md
+```
+
+Override env vars:
+
+- `RELEASE_STEP6_OVERRIDE_VERSION=v0.23.0` — skip the auto-bump. Use for major bumps.
+- `RELEASE_STEP6_TITLE="Custom title"` — override the title.
+- `SOURCE_REPO=<path>` and `TARGET_REPO=<path>` — override repo paths.
+
+The script fails fast on three cases. Missing notes file. Empty delta since last tag. Tag collision on source. See `.claude/hooks/tests/release-step6.test.sh` for the 6 covered cases.
+
+**Manual fallback:** if the script is not available, run `git tag` on both repos and `gh release create --latest` manually. See `standards/release-tagging.md` for the exact commands.
+
+### Self-check step — before drafting the recap
+
+Before drafting the recap that feeds Step 4.5:
+
+1. Read your draft against `standards/bassclef-internal-jargon.md` BLOCK terms.
+2. Rewrite any BLOCK matches in plain English.
+3. Compose the Problem section via `/state-a-problem brief`. The draft carries `/kiss --grade10` inline by default.
+4. Compose the flash claim via `/value-prop tweet`.
+5. Write the recap file.
+
+The `pre-gh-release-body-scrub.sh` hook is the safety net at the GitHub Release page. This self-check catches misses at the PR body surface.
+
+### Modes
+
+- Default — dry-run then confirm then ship. Best for adopters and first runs.
+- `/release --skip-dry-run` — jump straight to live. Use only when you just ran a dry-run and want to skip the duplicate.
+- `/release --dry-run` — dry-run only. The live release does not fire under this flag.
+  INSTEAD of skipping the live step when you intend to ship: use the default mode.
+
+### Override paths
+
+- `BASSCLEF_PUBLIC_DIR=<path>` — override target dir. Falls back to a default path.
+- `SKIP_ANDON=1` — bypass andon scan.
+  INSTEAD of bypassing in production: cure the offending file. Re-run the dry-run.
+- `SKIP_SIBLING_SMOKE=1` — bypass Step 1.5 sibling-smoke prompt.
+  INSTEAD of bypassing routinely: run the smoke. Or defer with a follow-on ticket.
+- `SKIP_RELEASE_PR_AMEND=1` — allow Step 5 to fire with the stub still present.
+  INSTEAD of habitually skipping the amend: draft the recap before Step 1.
+- `SKIP_RELEASE_TAG=1` — skip Step 6 for infrastructure fixes that ship before the next planned release window.
+
+### Reads
+
+- `.claude/skills/*/SKILL.md`, `.claude/luminaries/*.md`, `.claude/rules/*.md`, `.claude/hooks/*.sh`, `architecture/decisions/*.md`, `standards/*.md` — files carrying `tier:` field
+- `standards/bassclef-internal-jargon.md` — andon scan term source (BLOCK tier)
+- `CLAUDE.md`, `substrate.config.md` — top-level docs shipped as-is
+
+### Writes
+
+- `~/src/sunj-labs/bassclef/` (or `BASSCLEF_PUBLIC_DIR`) — filtered framework via rsync
+- (Per ADR-040 D5) `~/src/sunj-labs/bassclef-lite/` — the lite tier subset, once the sibling repo ships
+- A new branch and PR in public bassclef (and in bassclef-lite, per D5)
+- A git tag `release-YYYY-MM-DD-<sha>` in bassclef-upstream
+
+### Grace window on old vocabulary
+
+Old vocabulary still works through 2026-10-31 per ADR-031 and the we-dont-break-adopters rule. Old terms — `bet`, `appetite`, `step`, `chronicle`. The `/chronicle` skill name still resolves alongside `/session-log`.
+
+## Examples
+
+<!-- FKGL-EXEMPT: sample dry-run output -->
+
+**Dry-run summary (clean):**
+
+```
+=== /release dry-run ===
+Source SHA: 2ceb53b7
+Would-be tag: release-2026-07-19-2ceb53b7
+Files by tier:
+  include (basic + public + untagged): 47
+  exclude (private + upstream):        23
+Andon scan: CLEAN
+Target dir: ~/src/sunj-labs/bassclef/
+```
+
+**Andon trip (STOP):**
+
+```
+=== /release dry-run ===
+Andon scan: 2 HITS
+  - standards/foo.md line 42: BLOCK term hit
+  - .claude/rules/bar.md line 8: BLOCK term hit
+STOP.
+```
+
+<!-- /FKGL-EXEMPT -->
+
+## Anti-patterns and INSTEAD
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Skip dry-run and go straight to live | Run dry-run first. The andon scan and tier counts protect against leaks |
+| Merge past an andon hit by setting SKIP_ANDON | Fix the file (retag or scrub or allowlist) and run dry-run again |
+| Silence a FAIL sibling-smoke and dispatch anyway | Hold the release. Ship the cure first. Confirm smoke PASS on the next run |
+| Skip Step 4.5 and let the release PR ship with the template stub | Amend the PR body with the drafted recap so adopters read the real story |
+| Fire /release when a prior release PR is open on public | Wait for the prior PR to merge. Otherwise the new PR would stack cumulatively |
+
+## Composes with
+
+- `/verify` — Step 3 runs verify against the changes before live release.
+- `/state-a-problem` — drafts the recap for Step 4.5 PR body amendment.
+- `/value-prop` — flash summary for the same recap.
+- `/kiss` — applied at Step 2b before release notes write.
+
+## Distinct from
+
+- `/promote` — files a `bassclef-evolution` ticket for framework change proposals. `/release` ships changes already decided. `/promote` proposes them.
+- `/docs-sync` — syncs adopter docs to GitHub Wiki. Separate channel. Not the release pipeline.
+
+## Rules
+
+- Do not write to public bassclef without a clean andon scan. INSTEAD, fix any hits before dispatch.
+- Do not dispatch live release with a dirty source or target tree. INSTEAD, commit or stash first.
+- Do not skip Step 1.5 without explicit operator deferral. INSTEAD, run the smoke or file a follow-on ticket.
+- Do not skip Step 4.5. Adopters read the PR body first. INSTEAD, amend the stub before Step 5.
+- Always cut semver tags on both repos with the same name at Step 6.
+
+## Test cases
+
+<!-- FKGL-EXEMPT: structured test spec -->
+| ID | Prompt | Expected behavior |
+|---|---|---|
+| T1 | `/release` on a clean tree with no adopter-observable changes | Dry-run reports counts + CLEAN andon; sibling-smoke prompt fires; operator confirmation gates live |
+| T2 | `/release` when standards/foo.md contains a BLOCK term | Andon trips; STOP; message names line + term |
+| T3 | `/release --dry-run` | Dry-run only; live release does not fire |
+| T4 | `/release --skip-dry-run` when just ran dry-run | Live release fires without repeating dry-run |
+| T5 | `/release` when a prior release PR is open on public | STOP with a stack warning |
+| T6 | Sibling smoke returns FAIL | Release held; PR does not open until cure ships |
+<!-- /FKGL-EXEMPT -->
+
+## Sources read
+
+- ADR-029 release pipeline
+- ADR-039 release tagging policy
+- ADR-040 planning-skill vocabulary and lite profile (Decision 5 — two-repo release)
+- `.claude/rules/sibling-smoke-after-substrate-change.md`
+- `.claude/rules/plain-english-discipline.md`
+- `.claude/rules/we-dont-break-adopters.md`
+- `standards/tier-tag-schema.md`
+- `standards/release-tagging.md`
+- `standards/bassclef-internal-jargon.md`
+- `scripts/release-to-bassclef.sh`
+- bassclef-upstream#634 — /kiss on release notes
+- bassclef-upstream#694 — PR body amend at Step 4.5
+- bassclef-upstream#545 V2 — sibling-smoke prompt at Step 1.5
+
+## Why this skill exists
+
+Cross-repo releases without discipline leak private content into public. They mismatch tags across repos. They ship template stubs that adopters read as the release story. `/release` enforces the pipeline. Leaks get caught before writes. Tags match on both repos. Adopters read the real recap. Without `/release`, cross-repo shipping is manual clickops or bypasses the andon gate.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/release-notes/SKILL.md

@@ -0,0 +1,202 @@
+---
+tier: lite
+name: release-notes
+description: "Draft a weekly changelog for two audiences \u2014 internal team (what shipped) and users (what's new for you). Pushes to Google Docs."
+problem: "Weekly releases ship without a written record. Users miss what changed. Team misses what shipped."
+value: "Drafts a weekly changelog for two audiences \u2014 internal team and users. Plain English."
+inputs: [Time range or release tag ref]
+outputs: [Internal changelog, User-facing changelog, Highlights section]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Release Notes — Weekly Changelog
+
+Two audiences, two documents, one cadence. Run weekly or at version tags.
+
+## Two audiences
+
+### Internal (project team)
+
+What shipped, what changed, what to watch out for. Technical, specific,
+complete. This is the changelog developers and operators read.
+
+**Tone**: direct, technical, links to commits and issues.
+
+### External (users)
+
+What's new and why you care. No jargon, no implementation details.
+This is what someone adopting the product reads.
+
+**Tone**: plain language, benefit-first, "you can now..." framing.
+
+## When to run
+
+- **Weekly**: Every Monday (or first session of the week), covering the
+  prior week's work. This is the primary cadence.
+- **At version tags**: When tagging a release (v0.7.0, v1.0.0), write
+  release notes for the tag covering everything since the last tag.
+- **Session-end**: The session-end skill triggers release notes as a MAY
+  tier item. For per-session notes, write the internal version only —
+  external notes aggregate weekly.
+
+## Procedure
+
+### 1. Gather changes
+
+```bash
+# Since last release notes
+LAST_NOTES=$(ls docs/release-notes/*.md 2>/dev/null | grep -v .gitkeep | sort | tail -1)
+LAST_DATE=$(basename "$LAST_NOTES" .md | cut -c1-10)
+
+# Commits since then
+git log --oneline --since="$LAST_DATE"
+
+# Tags since then
+git tag --sort=-creatordate | head -5
+
+# Chronicles since then (richer context than commits)
+ls chronicle/ | sort | tail -10   # bassclef
+ls docs/chronicle/ | sort | tail -10  # app repos
+```
+
+### 2. Write internal changelog
+
+For each meaningful change (skip auto-saves, checkpoint commits):
+
+```markdown
+# Changelog — Week of YYYY-MM-DD
+
+## New
+- **[Feature name]** — what it does, why it matters. ([commit](hash), closes #NNN)
+
+## Changed
+- **[What changed]** — what's different, what to watch out for. ([commit](hash))
+
+## Fixed
+- **[What was broken]** — what the symptom was, what fixed it. ([commit](hash))
+
+## Versioning
+- Tagged: vX.Y.Z — [milestone summary]
+
+## Stats
+- Commits: N
+- Issues closed: N (#NNN, #NNN)
+- New skills/standards: N
+- Chronicles: N
+```
+
+### 3. Write external release notes
+
+For each user-facing change:
+
+```markdown
+# What's New — Week of YYYY-MM-DD
+
+### [Feature name in plain language]
+
+**What you can do now**: [one sentence — what's new or different]
+
+**Why it matters**: [one sentence — what problem this solves]
+
+**How to try it**: [one sentence — where to go, what to do]
+```
+
+Rules for external notes:
+- No technical jargon. "Broadened bassclef evolution check" → "Settings changes are now automatically flagged for review across all repos"
+- No implementation details. Skip refactors, CI changes, internal tooling
+- No feature names that aren't visible to users
+- Test: could someone who's never seen the codebase understand this?
+
+### 4. Save locally
+
+```
+docs/release-notes/YYYY-MM-DD-internal.md
+docs/release-notes/YYYY-MM-DD-external.md
+```
+
+### 5. Push to Google Docs
+
+Read `changelog_doc_id` from `substrate.config.md`.
+If configured:
+
+```bash
+# Internal changelog
+cd ~/src/your-org/your-app && npx tsx scripts/push-to-gdoc.ts \
+  --file [internal changelog path] \
+  --doc-id [changelog_doc_id from substrate.config.md]
+```
+
+External release notes go to a GitHub Release (if tagging) or to the
+same doc with a clear section header. The Google Doc is the internal
+team's running record; GitHub Releases are the external-facing artifact.
+
+If `changelog_doc_id` is not set, changelogs stay local.
+
+### 5a. Defer push when capabilities missing
+
+If `changelog_doc_id` is configured but the current session cannot push
+(missing `gcloud-auth` / `google-docs-write` capability — typical in
+ephemeral-mobile, cloud-web, or a desktop session where the SA key is
+absent), DO NOT silently skip. Write a deferred-action entry so the
+next capable session picks up the push.
+
+```bash
+TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
+ID="${TS}-release-notes-gdoc-push"
+cp templates/deferred-action-template.md \
+   "docs/deferred-actions/${ID}.md"
+# Fill frontmatter:
+#   pending_action: push-release-notes-to-gdoc
+#   requires_capability: [gcloud-auth, google-docs-write]
+#   priority: medium
+#   origin_skill: /release-notes
+#   resolves_when: |
+#     Google Doc <changelog_doc_id> reflects docs/release-notes/<period>-internal.md
+# Fill body sections (Context, Command, On completion, Cross-refs).
+git add "docs/deferred-actions/${ID}.md"
+git commit -m "chore: defer release-notes gdoc-push (<period>)"
+```
+
+See `.claude/rules/deferred-actions.md` and
+`standards/deferred-actions-schema.md`. Silent skip is a rule violation
+(session-artifacts.md — silence is not deferral).
+
+### 6. GitHub Release (at version tags only)
+
+When a version tag exists for this period:
+
+```bash
+gh release create vX.Y.Z \
+  --title "vX.Y.Z — [milestone summary]" \
+  --notes-file docs/release-notes/YYYY-MM-DD-external.md
+```
+
+## Backfill
+
+If release notes haven't been written in more than a week:
+
+1. Check when the last release notes were written
+2. Group missing weeks by date range
+3. Write one internal + one external per missing week, oldest first
+4. Push in chronological order (oldest first — same rule as journal entries)
+
+## Config
+
+The `changelog_doc_id` field in `substrate.config.md` is requested when
+a new repo inherits bassclef. If not configured, changelogs stay local
+in `docs/release-notes/`.
+
+## Session-end integration
+
+The session-end skill lists release notes as a MAY tier item (step 10).
+At weekly boundaries or version tags, the agent should proactively run
+/release-notes rather than waiting for session-end to maybe trigger it.
+
+The session-start hook should check: "When were release notes last
+written? If >7 days, flag it." This is the real enforcement — session-end
+is too unreliable for weekly cadence.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.