Skip to content

v1.5.0

Latest
Latest

Choose a tag to compare

View all tags
@va-worker va-worker released this 13 Jun 11:06
· 6 commits to main since this release
v1.5.0
b64a50c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's in this release

Headline pairing: /drain ships AND the upgrade pipeline can actually deliver it. This release lands the four-ticket drain port (T1–T4) plus the keystone self-healing-sync fix (#371) that closes the long-standing upgrade-pipeline gap. Downstream forks that /upgrade to v1.5.0 inherit a working autonomous-merge drain stack, the agent-merge gate, a bootstrap-time templating mechanism, the platform-shape /bootstrap-agents variant, doctor-script convergence, an upgraded /report-issue flag surface, a split-and-honest CI job shape, and — for the first time — a sync mechanism that can deliver future runtime-protected fixes cleanly.

This is the largest release since v1.2.0. 28 PRs ship between v1.4.0 (2026-06-01) and v1.5.0 (2026-06-13).

Added

  • /drain skill + supporting runtime — drain port T1–T4 (#464, #478, #479, #482) — autonomous overnight processing of the Ready column, with a safety-class taxonomy (safety:internal / :reversible / :hot / :flagged), an agent-merge.yml gate workflow, a drain-merge-bridge.yml workflow that closes the workflow_dispatch/workflow_call gap, a drain.md orchestrator skill spec, a 5-state summary renderer (emit-drain-summary.mjs with 36 unit tests), provider-specific deploy-status and observability-baseline scripts (render-deploy-status.mjs, sentry-baseline.mjs), and an institutional-knowledge layer covering 7 Patterns and 6 Lessons accumulated during empirical development. Two ADRs (docs/adr/0001-*.md, 0002-*.md) document the architectural decisions; docs/drain-customization.md is the Layer 4 contract; docs/drain-known-limitations.md is the v1 transparency surface.

  • Bootstrap-time templating mechanism (#478, part of T2) — scripts/substitute-config-placeholders.sh (idempotent sed pass; --check mode for CI smoke tests) reads .gembaflow-config.json and substitutes four canonical placeholders ({{org}}, {{board.id}}, {{bot.worker}}, {{bot.reviewer}}) into shipped skill specs at bootstrap. New step 7 in .claude/commands/bootstrap-workflow.md runs the substitution. docs/PLATFORM-GUIDE.md documents the convention. The four-placeholder set is deliberately narrow — fork deploy URLs use $PUBLIC_BASE_URL env var, runtime repo names resolve via gh repo view. Both consumers of the mechanism (work-ticket.md and drain.md) now ship parameterized.

  • /bootstrap-agents --variant platform (#481) — net-new flag that swaps the agent roster for platform-shape projects (frameworks, harnesses, distribution pipelines). Default --variant product is unchanged. The platform variant installs six templates derived from vibeacademy/gembaflow-meta's calibrated roster: framework-architect, github-ticket-worker, platform-backlog-prioritizer, pr-reviewer, release-engineer, swarm-planner. Memory references parameterized to generic language; docs/SDLC.md § 2 documents the decision criteria.

  • /report-issue flag surface improvements (#469, #475, #476, #477) — adds --dry-run (zero api.github.com calls) and --fixture-repo <slug> (retargets gh issue create --repo to a test fixture) for QE iteration without polluting the upstream tracker; both flags mutually exclusive. Adds sync to the component taxonomy. Renames --force-codespaces-token → --try-anyway (hidden alias preserved for backward compat). New .github/workflows/auto-close-test-fixtures.yml automatically closes va-worker-authored test-fixture downstream-report issues that match the title prefix — completes the QE-pollution loop closure.

  • /doctor clone-freshness convergence (#472, #484) — both .claude/commands/doctor.md (the skill spec) and scripts/doctor.sh (the underlying script) now run an early "Verify the clone is current with origin" check. Emits PASS (current), WARN with the commits-behind count and most-recent upstream commit subject (stale), or SKIP with a clear reason (offline, no upstream tracking, not a git repo, no git binary). State-free; never fails the doctor run.

  • /review-to-tickets slash command (#395) + worker→reviewer auto-handoff (#397) + swarm mode for github-ticket-worker (#392) — closes the loop between review and backlog, automates the green-CI handoff to the PR reviewer, and lets the worker operate in isolated worktrees for /swarm runs.

  • Selectable assistant modes for the main Claude session (#409) — .claude/modes/ registry with five framework modes (default, scaffolded, socratic, terse-expert, shipping-coach), each a third-person persona assertion plus behavioral heuristics. /mode is the convenience wrapper.

  • audit-local-customizations.sh + /upgrade integration (#468) — pre-/upgrade audit surfaces every framework-controlled file modified locally since the fork was bootstrapped but NOT in .gembaflow-overrides. Read-only; surfaces the silent-clobber risk before the sync runs.

  • Auto-update board status on PR merge (#466) — new .github/workflows/auto-board-status.yml fires on PR-merged events, reads closingIssuesReferences, and moves each closed-issue's board item to Done. Opt-in via three repo variables + one secret (PAT with project scope).

  • DEPRECATED_CHECK_ALIASES mechanism in scripts/verify-bot-permissions.sh (#402) — when a future release renames a CI check, the rename PR can add a one-line alias entry so forks have a graceful one-release window to update their .github/workflows/ci.yml.

  • scripts/doctor.sh clone-freshness check (#484) — see above; converges shell-driven and slash-command paths.

Changed

  • scripts/template-sync.sh self-heals runtime-protected files after the sync loop (#486, closes #371) — the keystone fix that makes this release adoptable. New post-sync-loop block re-copies scripts/template-sync.sh and scripts/lib/overrides.sh from the just-downloaded release tarball IF (a) they differ from upstream AND (b) the path is NOT in .gembaflow-overrides. The currently-running script process is in memory; only the on-disk file gets refreshed; the next /upgrade reads the refreshed code. Refreshed files ride the sync PR with a new > [!IMPORTANT] Runtime-protected files refreshed (post-run) callout. See "Propagation note" below — existing forks need a one-time manual refresh on first upgrade to v1.5.0.

  • version-parity CI job split into json-validate + version-parity (#471) — the former umbrella bundled two unrelated checks; failed-job names now match their purpose. Fork action required, see "Fork-maintained files you must update" below.

  • scripts/report-issue.sh flag rename --force-codespaces-token → --try-anyway (#476) — flag name now describes actual behavior; old name preserved as a hidden backward-compat alias.

  • validate-version-parity.sh is lenient by default — opt-in for strict mode (#467) — divergence now emits WARN and exits 0 unless the fork sets "enforceVersionParity": true in .gembaflow-version.

  • .github/workflows/auto-triage.yml no longer applies the P1 label (#470) — Priority is canonical on the project board, not a repo label. The ## Auto-Triage comment remains as both the operator-facing signal and the idempotency marker. Maintainers can now safely delete the P1/P2/P3 label definitions.

  • Root .gitignore covers framework-generated artifacts (#399) — .gembaflow-reports/, legacy .agile-flow-reports/, and legacy .agile-flow-version are now ignored. Removes the recurring /upgrade clean-tree precheck failure on every fork that has ever run /report-issue.

  • Release notes now require a "Fork-maintained files you must update" section (#401) — establishes the convention being followed in this very document.

Fixed

  • docs/UPGRADING.md adds a pre-rebrand fork section (#465) — documents the one-line sed patch v1.0.x forks must apply to escape the KeyError: 'tag_name' crash on first /upgrade (root cause: v1.0.x's template-sync.sh uses curl -sf without -L). Belt-and-braces alternative pins UPSTREAM_REPO=vibeacademy/gembaflow to eliminate the redirect at the source.

  • docs/TICKET-FORMAT.md example uses ### headers, not dash-banners (#400) — the Concrete Example's Power-Section markers were --- A. Environment Context --- style which renders as horizontal rules if copied out as a template. Switched to ### A. Environment Context.

  • docs/report-issue.md documents board-canonical priority convention (#403) — the severity field in the report's YAML front matter is informational; priority is canonical on the project board's Priority field.

Removed

  • scripts/test-report-issue.sh (455 lines) + docs/reports/report-issue-acceptance-template.html (362 lines) retired (#483) — the legacy test file tested a pre-rebrand .gembaflow-meta/upstream API that the current scripts/report-issue.sh no longer has. Canonical replacement is scripts/report-issue.test.sh (12 assertions via PATH-shimmed gh, shipped with #469). The HTML output template is removed alongside since it can no longer be regenerated.

Documentation

  • Drain stack documentation set (#482) — 5 new docs: docs/adr/0001-*.md, docs/adr/0002-*.md, docs/drain-customization.md, docs/drain-known-limitations.md, docs/drain-institutional-knowledge.md. docs/PLATFORM-GUIDE.md cross-references all 5 from the "Bootstrap-time templated values" section.

  • Nested-subagent limitation documented in auto-handoff invariants (#398) — both github-ticket-worker.md and pr-reviewer.md now carry a "Known limitation: nested subagent contexts" subsection.

Migration notes

Required action for every fork after /upgrade to v1.5.0:

  1. Manually refresh scripts/template-sync.sh and scripts/lib/overrides.sh ONCE. See "Propagation note" below for the exact commands.

  2. Branch-protected forks: add json-validate to the required-status-checks list on the main ruleset. The existing version-parity entry stays. Without the update, json-validate runs but does not gate. scripts/verify-bot-permissions.sh (shipped with #471) asserts the new expected list — running it after upgrade will report "Missing required status checks: json-validate" until you update the ruleset.

Optional:

  1. If your fork depended on the strict validate-version-parity.sh (CI failing on every fork-vs-framework version divergence), add "enforceVersionParity": true to .gembaflow-version to preserve the old behavior. Otherwise, divergence will now WARN rather than FAIL.

  2. If your fork hosts a project-board with auto-board-status enabled (#466), set the three repo variables + one secret per docs/CI-CD-GUIDE.md. Opt-in; framework default is disabled.

Fork-maintained files you must update

  • Required CI check added: json-validate (#471). Update your fork's branch protection ruleset to require json-validate in addition to version-parity. Existing version-parity entry stays — its scope has narrowed to .gembaflow-version vs package.json parity only; JSON validation moved to json-validate.

  • Removed legacy script: scripts/test-report-issue.sh (#483). If your fork's /upgrade post-flight or any operator script runs bash scripts/test-report-issue.sh, switch to bash scripts/report-issue.test.sh (the canonical replacement shipped in v1.4.x via #469's predecessor work — present in your fork already).

  • Removed legacy artifact: docs/reports/report-issue-acceptance-template.html (#483). If your fork's docs reference this URL, update or remove the reference.

Propagation note

This release modifies scripts/template-sync.sh and scripts/lib/overrides.sh (both are in RUNTIME_PROTECTED_PATHS).

Fresh forks (provisioned after v1.5.0): the self-heal mechanism shipped in #371 fires automatically on their first /upgrade. No action required.

Existing forks (bootstrapped on v1.4.0 or earlier): one-time manual refresh required on first /upgrade to v1.5.0. The OLD sync script in your fork lacks the post-loop self-heal (that's exactly what #371 adds), so the upgrade will pull every other v1.5.0 file but leave the two runtime-protected scripts at their pre-v1.5.0 versions. Run:

# After running /upgrade to v1.5.0, run this ONCE per fork:
curl -fsSL "https://raw.githubusercontent.com/vibeacademy/gembaflow/v1.5.0/scripts/template-sync.sh" -o scripts/template-sync.sh
curl -fsSL "https://raw.githubusercontent.com/vibeacademy/gembaflow/v1.5.0/scripts/lib/overrides.sh" -o scripts/lib/overrides.sh
chmod +x scripts/template-sync.sh
git add scripts/template-sync.sh scripts/lib/overrides.sh
git commit -m "chore(sync): manual refresh of runtime-protected scripts for v1.5.0 (per release notes)"

From v1.5.0 onward, the self-heal block runs automatically on every /upgrade — no future runtime-protected fix will need a manual refresh.

Verification: after the manual refresh, your scripts/template-sync.sh should contain the comment block beginning with # 7.5. Self-healing post-sync refresh of runtime-protected files (#371). grep -c "Self-healing post-sync refresh" scripts/template-sync.sh should return 1.

Assets 2
Loading