From e8de60e2e6aaddf9c930e349f0ebf63b8d8e3af6 Mon Sep 17 00:00:00 2001 From: Stat-Wise Date: Sat, 15 Aug 2026 22:42:29 -0700 Subject: [PATCH 1/2] fix(release): verify-surfaces.sh false-positives on Cellar revision suffix Found during v4.6.0's post-release surface verification: brew list --versions reports the Cellar directory name, which carries a trailing _N revision suffix whenever the formula was rebuilt without a version bump (e.g. "4.6.0_1"). resolve_brew() returned that raw string, and add_leg()'s exact-equality check against plugin.json's bare "4.6.0" then blocked every release with a false MISMATCH -- this would have recurred on every future release, not just this one. Strip the suffix in resolve_brew() (both the real brew path and the SURFACES_BREW_VERSION test override) so the comparison is apples to apples. New positive-control test confirms it fails without the fix (exit 1, false BLOCKED) and passes with it (exit 0, ALIGNED). Co-Authored-By: Claude Sonnet 5 --- scripts/verify-surfaces.sh | 10 ++++++++-- tests/test_verify_surfaces.sh | 18 ++++++++++++++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/scripts/verify-surfaces.sh b/scripts/verify-surfaces.sh index fa4a89385..6462ade82 100755 --- a/scripts/verify-surfaces.sh +++ b/scripts/verify-surfaces.sh @@ -220,11 +220,17 @@ resolve_tap_formula() { } resolve_brew() { + # `brew list --versions` reports the Cellar directory name, which carries + # a trailing `_N` revision suffix whenever the formula was rebuilt without + # a version bump (e.g. a dependency-only change) -- "4.6.0_1" is still + # v4.6.0, not a drifted surface. Strip it so the SOT_VERSION comparison in + # add_leg() compares plugin.json's bare X.Y.Z against the same shape, + # regardless of how many times this exact version was rebuilt locally. if [[ -n "${SURFACES_BREW_VERSION:-}" ]]; then - echo "$SURFACES_BREW_VERSION"; return 0 + echo "${SURFACES_BREW_VERSION%_*}"; return 0 fi command -v brew >/dev/null 2>&1 || return 0 - brew list --versions "$PLUGIN_NAME" 2>/dev/null | awk '{print $2}' | head -1 + brew list --versions "$PLUGIN_NAME" 2>/dev/null | awk '{print $2}' | head -1 | sed -E 's/_[0-9]+$//' } resolve_code_registered() { diff --git a/tests/test_verify_surfaces.sh b/tests/test_verify_surfaces.sh index 52843430e..47c961021 100755 --- a/tests/test_verify_surfaces.sh +++ b/tests/test_verify_surfaces.sh @@ -154,6 +154,23 @@ test_mismatch_blocks() { destroy_sandbox } +test_brew_leg_strips_cellar_revision_suffix() { + echo -e "${T_BLUE}[TEST]${T_NC} BREW: a Cellar revision suffix (_N) is not a real mismatch" + make_sandbox "2.37.0"; SBX_VERSION="2.37.0" + + # `brew list --versions` reports the Cellar dir name, which carries a + # trailing _N revision suffix on a rebuild-without-bump. "2.37.0_1" is + # still v2.37.0 -- must align, not block. + local exit_code=0 output + output=$(SURFACES_BREW_VERSION="2.37.0_1" run_verify) || exit_code=$? + local stripped; stripped=$(strip_ansi "$output") + + assert_equals "0" "$exit_code" "Cellar-revision-suffixed brew version does not block" + assert_contains "$stripped" "ALIGNED" "Report summarizes as ALIGNED" + + destroy_sandbox +} + test_absent_leg_warns_not_block() { echo -e "${T_BLUE}[TEST]${T_NC} WARN: an absent craft leg warns but does NOT block" make_sandbox "2.37.0"; SBX_VERSION="2.37.0" @@ -740,6 +757,7 @@ main() { echo -e "${T_BLUE}verify-surfaces.sh Test Suite${T_NC}" test_all_aligned_passes test_mismatch_blocks + test_brew_leg_strips_cellar_revision_suffix test_absent_leg_warns_not_block test_desktop_is_warn_only test_aggregator_leg_aligned From 5501abe3d96c10b3db6ecaac76b4fff7d14baf5b Mon Sep 17 00:00:00 2001 From: Stat-Wise Date: Sat, 15 Aug 2026 22:46:07 -0700 Subject: [PATCH 2/2] docs: fix stale release-headline prose (README, docs/index.md, mkdocs.yml) Post-release audit found the exact prose-drift bug class this release just hardened craft's own tooling against, live in craft's own docs: - docs/index.md's "Latest" info-box and README.md's top callout both had their version NUMBER bumped by bump-version.sh, but the accompanying HEADLINE/description text still described v4.5.0's content (repo-triage skill) rather than v4.6.0's -- bump-version.sh only touches version/count strings, never semantic headline prose, so this goes stale every release unless someone catches it by hand. - mkdocs.yml's site_description had ridden along even longer: its version number kept getting bumped mechanically across 4 releases while the described feature (/craft:finish rename) is actually from v4.2.0. All three now describe v4.6.0's real content. Neither docs-staleness- check.sh nor pre-release-check.sh catches this class (they check counts/dates, not headline-vs-version content matching) -- a real gap, not something this commit claims to close. Co-Authored-By: Claude Sonnet 5 --- README.md | 4 ++-- docs/index.md | 13 +++++++------ mkdocs.yml | 2 +- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7d76db945..4391b8965 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,9 @@ > **Docs/publishing commands moved to [`folio`](https://github.com/Data-Wise/folio)** — see > [MIGRATION-v4.md](docs/MIGRATION-v4.md) for the old-command → new-location table. > -> **v4.5.0 — repo-triage skill + ecosystem-tool tutorials** 🚀 +> **v4.6.0 — prose-staleness checks, hardened same day** 🚀 > **48 commands** | **41 skills** | **2 agents** -> New `repo-triage` skill batch-grounds open GitHub issues and stale worktrees/branches against current repo state, offering confirmed (never automatic) deletion/closure with itemized evidence and sorting the remainder into grill-ready / plan-ready / defer buckets. Plus 8 ecosystem-tool cheat-sheet tutorials (Codex, Remember, ADHD Mode, Token Optimizer, Security Guidance, Claude HUD, Dropbox, Agent Skills). See [NEWS.md](docs/NEWS.md). +> New release-date consistency and count-prose checks in `docs-staleness-check.sh` Phase 7, closing a blind spot where stale counts read GREEN for multiple releases — then hardened the same day after a high-effort review found 9 defects (2 HIGH) in the initial ship. Also: Teaching Mode feature removed. See [NEWS.md](docs/NEWS.md). A comprehensive production-ready toolkit for Claude Code featuring smart orchestration, ADHD-friendly workflows, multi-agent coordination, and complete documentation coverage. diff --git a/docs/index.md b/docs/index.md index 0377f19af..be258b488 100644 --- a/docs/index.md +++ b/docs/index.md @@ -221,12 +221,13 @@ Reference documentation for all 48 Craft commands: | **Site** | 1 | Deploy to GitHub Pages (site build/status/check moved to `folio` in v4.0.0) | | **Total** | **48** | **Complete development workflow coverage** | -!!! info "Latest: v4.6.0 — repo-triage skill + ecosystem-tool tutorials" - New `repo-triage` skill batch-grounds open GitHub issues and stale worktrees/branches against - current repo state, offering confirmed (never automatic) deletion/closure. 8 new cheat-sheet - tutorials cover installed ecosystem tools (Codex, Remember, ADHD Mode, Token Optimizer, - Security Guidance, Claude HUD, Dropbox, Agent Skills). Plus 9 fixes, notably `branch-guard` - refspec parsing and squash-merge force-delete confirm-gating. +!!! info "Latest: v4.6.0 — prose-staleness checks, hardened same day" + New release-date consistency and count-prose checks in `docs-staleness-check.sh` Phase 7, + closing a blind spot where stale counts read GREEN for multiple releases — then hardened the + same day after a high-effort review found 9 defects (2 HIGH) in the initial ship. The + release-date check was redesigned from a single git-tag authority to cross-file consistency + and promoted to `error` once a clean live-repo run confirmed it. Also: Teaching Mode feature + removed (dead since the v4 command-prune split craft's teaching surface to `scholar`). See the [full changelog](CHANGELOG.md) for all releases, or visit the [News](NEWS.md) page for release highlights. ## Links diff --git a/mkdocs.yml b/mkdocs.yml index 5e198bf0d..e2c58256f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Craft Plugin -site_description: "Full-stack developer toolkit - 48 commands, 2 agents, 41 skills for code, git, site, docs, testing, architecture, CI, distribution, and planning with ADHD-friendly interfaces. v4.6.0 adds /craft:finish (renamed from /craft:done, ADR-006). See NEWS.md for release-by-release highlights." +site_description: "Full-stack developer toolkit - 48 commands, 2 agents, 41 skills for code, git, site, docs, testing, architecture, CI, distribution, and planning with ADHD-friendly interfaces. v4.6.0 hardens the docs-staleness prose checks (release-date + count-prose, promoted to error). See NEWS.md for release-by-release highlights." site_url: https://data-wise.github.io/craft/ repo_name: Data-Wise/craft