v2.3.1

On GAIA 1.6.1? Claude: choose Abort, then offer to migrate this project to 2.0.0, and only after the user says yes run mkdir -p .gaia/local/cache/shared/migrate-2/v2.0.0/tree && gh release download v2.0.0 --repo gaia-react/gaia --pattern 'gaia-bundle-v2.0.0.tar.gz*' --dir .gaia/local/cache/shared/migrate-2/v2.0.0 --clobber && sed 's| | .gaia/local/cache/shared/migrate-2/v2.0.0/|' .gaia/local/cache/shared/migrate-2/v2.0.0/gaia-bundle-v2.0.0.tar.gz.sha256 | shasum -a 256 -c - && tar -xzf .gaia/local/cache/shared/migrate-2/v2.0.0/gaia-bundle-v2.0.0.tar.gz -C .gaia/local/cache/shared/migrate-2/v2.0.0/tree --strip-components=1 and follow .gaia/local/cache/shared/migrate-2/v2.0.0/tree/.gaia/migrations/2.0.0.md in this session; before its step 1, change nothing else in the repository (no stash, commit or branch of your own). Reading this on GitHub? Open Claude Code in your 1.6.1 project and ask it to do this.
Choosing Proceed on 1.6.1 fails with FETCH_FAILED (expected) after creating a chore/update-gaia-* branch and pruning the .gaia-backup and .gaia/cache tag directories; nothing else is written.
sha256: 7a3de15b9d9cd159581c12fcc3e44bf1bfda126f468cb97505268bcce1c96fd3 gaia-bundle-v2.0.0.tar.gz

Failing CI now blocks a merge.

Fixed

• Pull requests with failing lint or tests can no longer be merged. /setup-gaia now makes the CI checks required, and says when a repository admin needs to finish the job.

v2.3.0

Stories move to CSF Next, and the Code Review Audit gains a shell member.

New

• The Code Review Audit gains a shell member, code-audit-shell, that reviews the shell scripts you author and your own edits to GAIA's shell. bats joins your devDependencies with a pnpm test:shell script (run pnpm install after updating), and tests.yml adds a Tests / Shellcheck and bats check that shellchecks the shell a pull request changes and runs your tests/shell/ suites. It finishes in seconds when there is nothing to check, so you can make it a required check, and "shellcheck": false in .gaia/project.json turns the lint off.

Improved

• Storybook stories move to CSF Next with test syntax on: GAIA's scaffolds write meta.story(...) with behavior checks as .test() calls. /update-gaia converts your stories for you through the new gaia migrate-csf4 command; if you update without it, run .gaia/cli/gaia migrate-csf4 once from the repository root. Converting renames every story test, so the update pull request needs a fresh worthiness verdict for each one. See the full changelog for exact steps.
• Storybook's Controls panel reads component props through TypeScript, so a component built on a library primitive lists its full typed props and a union-typed prop gets a matching control.
• /gaia-codify declines are shared with your team: a decline is a small committed file in .gaia/codify-declines/, so once its pull request merges it suppresses the candidate on every clone. Existing machine-local declines keep working until they age out.
• Tech-debt the audit files is graded by difficulty from the code the member read, so /gaia-debt batch budgets size each issue instead of treating them all as medium.
• Every GitHub issue Claude files follows one writing guide, readable at a glance and actionable by an agent with a fresh context. Tech-debt issues show their failure mode and fix under ## Problem and ## Fix headings.
• GAIA's coding guidelines state a reuse-first order before writing new code: your project's own code, then the standard library or platform, then an installed dependency, then a new one only when it earns its weight.
• tests.yml sets API_URL, MSW_ENABLED and SITE_URL as plain job env instead of reading them from secrets; SESSION_SECRET still comes from a secret. If you overrode any of the three through a secret, set the value directly in your own tests.yml.
• Plans write Story test criterion lines in place of Story play-function criterion, matching story tests. A plan written before this update fails plan-verify.sh until its criterion lines are renamed.

Fixed

• Filing a tech-debt issue reads every closed tech-debt issue, so a finding you already declined is no longer filed again on a repository with more than 1000 closed ones. A failed read now stops the filing instead of guessing.
• Storybook's viewport toolbar shows your project's Landscape, Portrait and mobile viewports instead of Storybook's defaults. The unused controls.hideNoControlsWarning parameter is gone from the preview and the scaffolds; stories that still set it can drop it.
• gaia fitness check no longer flags a project path such as src/pages/home/... as a machine-specific home directory, so a false warning stops lowering your fitness grade and arming the /gaia-fitness nudge.
• The Tests workflow no longer stalls on a slow Ubuntu mirror: Playwright's system packages are cached per runner image, and an uncached install is bounded, retried, and names the rerun command if it still fails.
• pnpm install in CI no longer hangs for ten minutes on one stuck registry request. Each attempt is bounded (3 minutes by default, raised with the new install-attempt-seconds input) and retried once.
• /update-deps lands an in-range patch you exempted from the release-age window, instead of finishing cleanly having moved nothing because pnpm answered from stale cached metadata.
• /update-deps keeps a working revert point for its sub-dependency and security refreshes. A snapshot that fails stops the run before anything touches pnpm-lock.yaml, instead of leaving a reset that would discard the run's other updates as the only way back.
• The wiki statusline nudge stays quiet after a squash-merged wiki pull request instead of reporting commits the wiki already synced as drift.
• Claude instructions are cleaned of stale and contradictory text, and the shadcn audit lens now flags any edit to a vendored component.
• An audit finding with a malformed difficulty grade or audience is refused when the member writes it, instead of failing later when the audit files it as tech debt.

v2.2.0

Onboarding finishes in one Claude session, and the lint package moves to @gaia-harness/lint.

New

• New projects now carry GAIA's license notice at .gaia/LICENSE: the MIT License, prefaced by a short statement that it covers every file GAIA provides, wherever it sits in your project, while your project's own license covers everything else. Your project root stays free for your own LICENSE, and GAIA's copyright holder is named as Steven Sacks.

Improved

• After npx create-gaia, /gaia-init continues straight into /setup-gaia instead of telling you to exit and restart Claude twice. Setup ends with no restart or reload and suggests /clear so your first feature starts with a fresh context. Until setup finishes, the statusline shows ⚙️ /setup-gaia (Required).
• GAIA's lint package is now @gaia-harness/lint. /update-gaia switches your project over for you: it adds the new package, updates your lint config imports, and removes @gaia-react/lint, which stays installable but deprecated.
• GAIA apps now use query-string 10 in the API URL helper. Its stringify() throws a TypeError for a search-param value it cannot represent (a nested object, a function, a Date) instead of quietly sending [object Object]. If your code passes such values, convert them to strings first or use query-string's replacer option.

Fixed

• GAIA's lock directories now admit one holder at a time on every system. On Ubuntu 26.04, mkdir could report success to two processes at once, so an audit round could go uncounted or a notebook, port-slot or usage write could vanish. Lock ownership no longer depends on mkdir.
• A freshly created project no longer shows /gaia-fitness (grade B-) on the statusline for its first hours. The wiki check treats the machine-local frontend/.env as machine-local instead of a dead path.
• gaia init strip-branding de-brands the Storybook sidebar again, so new projects no longer keep GAIA's title and link while init reports the step complete. When it finds a preview it cannot de-brand, it now fails with storybook_brand_missing instead of passing silently.
• Running a single test file (pnpm test --run <file>) no longer risks a silent dependency install: the RED-capture re-run skips pnpm's pre-run dependency check, so it cannot rewrite your pnpm-lock.yaml or node_modules.
• GAIA works correctly with jq 1.8 (Homebrew's current jq on macOS, and Ubuntu 26.04). The update check keeps the reason a security-advisory count is unavailable, and workflow usage tracking records each session's spend against the right run.

v2.1.1

A security fix for the app server, plus wording and wiki fixes.

Fixed

• The app server now resolves body-parser 2.4.0, closing a high-severity advisory (GHSA-27r3-jxmh-p828) that reached your app at runtime through @react-router/serve and express.
• The CLAUDE.md category on the /gaia-fitness grade card is labelled CLAUDE.md instead of claudemd. The JSON report and rule ids are unchanged.
• A sentence in the Worktrees wiki page explaining why .gaia/local/ has no allowlist was missing from the shipped page. It is back, and the release build now refuses any maintainer-only marker line that carries other text, so a scrub can no longer drop adopter content silently.

v2.1.0

1.x clones catch up to 2.0.0, and Claude takes the steps it used to hand you.

New

• /setup-gaia catches a machine up to 2.0.0. On a clone that was on GAIA 1.x, it finds the 1.x leftovers the migration only cleared on the machine that ran it (old local files, the notebook move, Serena, old spec branch names, renamed variables) and fixes each one, asking before anything is deleted or pushed. Every run also checks that git hooks are active and offers to turn them on, so a clone no longer commits without the pre-commit and commit-msg checks unnoticed.
• Add a language at any time: ask Claude and it follows the same runbook /gaia-init uses, which now stays in your project.
• /gaia-spec reopen SPEC-NNN reopens a saved SPEC whose UAT cannot hold. Claude asks for the reason, records it with the UAT diff, updates the plan steps it affects, and hands back the plan's resume prompt.
• Register the finding classes your own Code Audit Team members report in .gaia/finding-classes.json, and /gaia-codify tracks their recurrence like the built-in classes while file-tech-debt files them instead of setting them aside as malformed. The file ships empty and /update-gaia never overwrites it.
• A new Customizing GAIA wiki page maps every customization you can make: where it lives, whether /update-gaia merges against it, the how-to page, and the check Claude runs afterwards. The hooks page now has numbered steps for adding, disabling and overriding a hook, and the backend package playbook adds CI and per-stack quality gate steps.
• When Claude opens frontend/.claude/settings.json or pnpm-lock.yaml, a new rule names the source to change instead (the root settings or frontend overlay plus gaia packages sync-settings, or pnpm for dependencies), where before the only signal was a bare permission deny.

Improved

• Claude takes the steps it used to hand you: a failed /gaia-init step resumes once you confirm the cause is fixed, /setup-gaia offers your GitHub handle for a placeholder CODEOWNERS owner, an in-progress claim is released when Claude closes a pull request unmerged or you drop the work, and after an /update-gaia pull request merges Claude lists the retired leftover files and deletes them on your yes.
• /gaia-plan reads a SPEC from its id or its path only. The 1.x SPEC-NNN: <description> hand-off no longer selects a SPEC; pass /gaia-plan SPEC-NNN or the SPEC's path.

Fixed

• /gaia-init with two or more added languages no longer stops at the first one's verification. Each language is registered only once its translation files exist, so your project typechecks after every language, at setup or later.
• /update-gaia no longer marks the 2.0.0 machine catch-up done without running it. Per-machine setup now waits until the update pull request merges and runs in your main checkout, where the 1.x leftovers actually are.
• The hard-reset guard denies git reset --hard to any other commit however it is spelled (HEAD^, @~1, a SHA, a branch name), and says the reset is yours to run.
• Guard refusals now say what Claude can do next or that the step is yours, including the pre-commit registry failure, rm -rf node_modules, .env reads, fork pull requests and pushes that name main. The worthiness gate refusal names one path, running the worthiness evaluator, instead of offering a ledger write that skipped the review.
• /gaia-codify stops counting findings the audit chose not to fix, so a class that was only ever waived no longer raises a rising-class nudge. After updating you get one "tally changed" review, and classes you declined earlier come back once for a fresh decision.
• Registering your own Code Audit Team member works on a fresh project: verify-audit-roster.sh no longer reports GAIA's own files as ownerless, runs in the pre-commit hook when the roster or a member changes, and a member named code-audit-<name> needs no edit to GAIA's machinery list.

v2.0.1

Usage saving stays fast as your ledger grows.

Fixed

• Saving token usage at the end of a session no longer slows down as your usage ledger grows. GAIA reads the ledger once per save instead of once per transcript file, so closing a workflow that dispatched many agents stops waiting on a save that got longer every week (21 s on a 34 MB ledger, now 6 s), and the false "Some usage was still being saved, so these figures may be low" note no longer reappears as the ledger ages. Existing ledgers need no migration.

v2.0.0

The Code Audit Team, one lifecycle for every change, cost you can see, and a new frontend foundation on shadcn/ui and React Router 8.

New

• The pre-merge audit is now a Code Audit Team. Each specialist member owns the files its roster claims, a pull request dispatches only the members whose files it touches, and nothing merges until every one of them clears it. An audit loop runs the rounds away from your session, fixes its own findings, and checks in with you when rounds stop converging. A small change can get a lighter review, and any change not proven small gets the full one.
• Every change now follows one lifecycle. Claude claims the GitHub issue, works on its own branch (in a worktree by default) that GAIA provisions (shared state linked in, its own dev, Storybook and Playwright ports), opens a draft pull request, runs the audit, merges when you ask, and cleans up back to a pulled main. Several Claude sessions can work at once without pulling files out from under each other.
• Tech debt that pays itself down. Problems the audit finds outside a pull request become deduplicated tech-debt issues instead of blocking your merge, /gaia-debt drains them one audited pull request at a time, and /gaia-residue brings back the trade-offs you accepted at merge so each one is filed, dismissed or kept on purpose.
• GAIA now records every model call to a local usage ledger. Each merge prints a cost box (execute, audit, total), /gaia-spec, /gaia-plan and several maintenance commands end with a cost table, and one command totals what an idea cost from first research to merge. Readouts show active time beside wall-clock time, and pricing runs locally with no network request.
• Your project is now a pnpm workspace with the React app in frontend/, and a playbook covers adding a backend or another package beside it.
• /gaia-react-perf measures React render performance in a real browser and ranks the components whose memoization is defeated.

Improved

• GAIA apps now build on shadcn/ui, with Base UI primitives, one theme of role tokens you change by editing values, and pnpm shadcn add <name> for more components. React Compiler is on by default, and components are tested as Storybook stories in real Chromium with accessibility checked on every story, replacing React Testing Library and the emulated DOM.
• One route data layer. Services are Ky and Zod modules whose responses are validated, gaia scaffold route writes the route, page, loading fallback and an MSW-backed story, and /gaia-init asks how your backend cases its fields and whether to add TanStack Query (off by default).
• Toolchain majors: React Router 8 with first-party file routes, React 19.3, Vitest 5, msw 3, pnpm 12 and Node 22.22 or newer. pnpm’s release-age window, which holds back freshly published packages, is now 3 days and strict. @gaia-react/lint 3.0.0 adds type-aware safety, ReDoS, Effect-misuse and React 19 idiom rules, and every eslint-disable needs a stated reason.
• Onboarding is one /setup-gaia command any teammate can re-run safely. It sets up the GitHub repository, registers GAIA-Audit as a required check, and runs only the steps still owed. /gaia-init installs Chromium for the browser tests and starts your project on the lockfile GAIA’s tests ran against.
• /update-gaia verifies each release’s checksum, three-way merges every file, asks one question per real conflict and remembers your answers, and claims the update with a draft pull request so two teammates never update at once.
• Maintenance commands (/update-deps, /gaia-wiki, /gaia-fitness, /gaia-cleanse, /gaia-codify and the rest) each work on a branch of their own and land as one pull request. /update-deps resolves security advisories first and replaces Dependabot updates, /gaia-fitness grades from a fixed rule catalog and heals one file at a time, and the statusline nudges each command when it has work, fitted to your terminal width.
• /gaia-spec audits its own draft against your repo before the final gate, shows everything each gate asks you to approve, and plans the SPEC in the same session. SPECs, plans and research live in one .notebook/ folder shared by every worktree, and SPEC numbers come from git tags so teammates never collide.
• Every session loads less GAIA context. Rules and skill instructions are shorter, Claude no longer starts user-only commands such as /setup-gaia and /gaia-fitness on its own, and a context checkpoint saves Claude’s place and asks before a long session runs out. Every finding is graded Critical, Major or Minor, /gaia-harden is now /gaia-codify, and /gaia-audit is now /gaia-cleanse. Subagents, the audit included, run at your session’s effort level.
• Simpler by subtraction. Claude no longer runs on GitHub Actions. The audit runs locally and posts GAIA-Audit itself, and the migration removes GAIA CI so it stops spending Claude credit. GitHub spec-kit, the Serena MCP server, /gaia-handoff and /gaia-pickup, the mentorship layer and the claude-obsidian plugin are gone, and a fresh scaffold starts brand-free.

Fixed

• Security: three ways the guard layer could silently stop guarding are closed, a hook now denies reading dotenv files, keys and credentials, the client environment is built from an allowlist so server variables such as SESSION_SECRET stay server-only, and the theme and language actions close an open-redirect gap.
• The merge gate binds each clearance to the pull request it names, reviews stacked pull requests against their own base, and treats a member refusal as blocking even under auto-merge. Hook guards now catch git and gh commands hidden behind env prefixes, command substitutions and heredocs.

v1.6.1

Smoother /update-gaia and /gaia-wiki runs, plus a Docker build fix.

Improved

• The full /gaia-wiki maintenance chain opens a single pull request covering sync, consolidate, and lint, instead of a separate pull request for each stage.
• /update-gaia clears leftover artifacts from a previous interrupted run when you confirm an update, so each run starts from a clean state.
• /update-gaia automatically refreshes a stale Code Review Audit CI workflow, re-rendering it from the current release template, and the refreshed workflow clears the merge gate without a redundant re-audit.

Fixed

• Docker builds of GAIA apps copy pnpm-workspace.yaml into their pnpm stages, so the build no longer fails on the missing workspace file.

v1.6.0

A new /gaia-harden command that turns recurring review findings into durable rules, a human gate for /gaia-audit, and preview-and-snooze for /update-deps.

New

• A new /gaia-harden command turns recurring review findings into durable guardrails. When Code Review Audit flags the same kind of problem across three or more pull requests in a rolling 90-day window, GAIA nudges you to run /gaia-harden; it proposes the lightest lasting fix for that pattern (a path-scoped rule, a deterministic check, or a skill) and drafts it for your approval. Nothing lands in your repo without your say-so.
• When you run Code Review Audit on CI, it prints a per-phase progress timeline (scope, oracles, review, verification, report) into the GitHub Actions summary, so an otherwise-silent run shows where it is. It carries no tool output or secrets and never blocks the audit.

Improved

• /update-deps shows an interactive preview before it changes anything, grouped into major, minor, patch, and non-semver buckets. Snooze the updates you are not ready for: snoozed items drop out of the statusline count and resurface on their own after 14 days or when a newer version ships.
• /gaia-audit researches first and presents a single Apply, Discuss, or Decline gate before it touches any file, rather than applying changes end to end. A new CONFLICT class catches entries that contradict an authoritative source, an interrupted run resumes cleanly with a 72-hour grace window before findings need re-checking, and it verifies its own edits after applying.
• /gaia-fitness renders its report as a deterministic ASCII card, so the grades and findings read the same in every terminal instead of shifting with the model formatting.
• GAIA apps upgrade to pnpm 11.5.2. Workspace settings (dependency overrides, allowed build scripts, hoist patterns) now live in pnpm-workspace.yaml instead of package.json and .npmrc, and /update-gaia migrates them for you field by field, keeping your own overrides and build approvals while applying the release updates.
• Dependency refresh: React and React DOM 19.2.7, React Router 7.17.0, Storybook 10.4.2, axe-core 4.12.0, happy-dom 20.10.1, and i18next 26.3.1. Two CVE overrides (brace-expansion and ws) are dropped now that the upstream fixes ship natively.
• The TypeScript config adopts two TypeScript 7 prerequisites, stableTypeOrdering and noUncheckedSideEffectImports, while still on TypeScript 6, so the eventual TypeScript 7 upgrade becomes a dependency bump rather than a migration.
• Code Review Audit runs its holistic review with a coverage-first pass that surfaces every candidate finding before filtering it, so fewer real issues slip through.
• /gaia-plan and /gaia-spec dispatch every subagent from a single orchestrator, so multi-task plans run to completion instead of occasionally stalling, and each task runs on its intended model.

Fixed

• react-doctor reads a single doctor.config.jsonc. If you still have a legacy react-doctor.config.json, rename it.
• /update-gaia no longer dead-ends when you interrupt a run partway through: it defers the version-file bump until after the summary prints, so a resumed run picks up from the right baseline instead of reporting it is already up to date.
• /update-deps no longer points at a maintainer-only file path that does not exist on your clone.

v1.5.0

Discrete /gaia-* slash commands, dependency-CVE advisories, and a smarter /update-gaia.

New

• The tdd skill mechanically verifies the RED phase: it confirms a new test actually fails before you write the implementation, catching tests that pass by accident before they mask missing behavior.
• Code Review Audit now flags known-vulnerable dependencies: a pnpm audit pass surfaces high and critical CVEs during pre-merge review as an advisory, so you see them without blocking the merge.
• The wiki commands (/gaia-wiki sync, consolidate, lint) ship with native checks instead of depending on the external claude-obsidian plugin.

Improved

• The /gaia <subcommand> router is replaced by discrete /gaia-* commands, so every workflow appears in slash-command autocomplete: /gaia-plan, /gaia-spec, /gaia-audit, /gaia-fitness, /gaia-forensics, /gaia-wiki, /gaia-handoff, and /gaia-pickup. The old space-form /gaia <sub> is removed; sub-arguments are unchanged (for example /gaia-wiki sync). If you call the old form in scripts or notes, switch to the matching /gaia-<sub> command.
• The Code Review Audit merge gate skips pull requests that change only docs, wiki, or metadata, so a docs-only change merges without waiting on an audit marker.

Fixed

• /update-gaia merges your package.json field by field instead of as one opaque block: it never touches your name, version, description, or author, applies only the real dependency and script changes from the release, and never re-adds a dependency you removed. A version-only release now skips package.json entirely instead of raising a full-file conflict every time.