Skip to content

docs: 1.7.0 release#5

Open
stevensacks wants to merge 25 commits into
mainfrom
docs/1.7.0-release
Open

docs: 1.7.0 release#5
stevensacks wants to merge 25 commits into
mainfrom
docs/1.7.0-release

Conversation

@stevensacks

@stevensacks stevensacks commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

Documentation updates for the GAIA 1.7.0 release, including a full top-down accuracy pass over every page verified against the GAIA source at gaia commit 0a4af7b.

Top-down accuracy pass (7 commits)

Every docs page was audited claim-by-claim against the GAIA source (commands, skills, hooks, rules, agents, CLI, CI), fixed in place, then re-verified with the docs-audit agent, pnpm build, and an em-dash/voice grep. Committed one group at a time:

  • Getting started — setup-gaia-ci (stale-branches deletes branches with no PR, pnpm-audit issue+PR, wave A/B split, wiki diff-size holdout); setup-cloned (removed false audit-mode re-run, added GitHub-CLI pre-check); Quick Start verified clean.
  • Commands — plan (removed fabricated clipboard step, fixed SPEC path); spec (inline plan-dispatch model); update-gaia (gaia update merge -> merge-workspace/merge-audit-ci); handoff-pickup (labeled as skills, dropped invented context-% thresholds); forensics, update-deps.
  • Maintenance — fitness (check categories + grade boundaries); audit (statusline strings, shrink/replace naming); harden (redirect action); wiki (Cross-SPEC consolidate logic, removed unverified wiki/meta/ claim).
  • Skills — added the a11y-fixes full axe-rule set and react-code React-19 gate; fixed a route-path bug and added --json in scaffolders. New page: skills/react-performance documenting the gaia-react-perf measure-only diagnostic.
  • Reference — hooks (added post-audit-status, fixed block-rm-rf and 5 others, telemetry-task-postuse kept out); rules (added react-router-docs/dep-audit, restored exact path globs, omitted new maintainer-only blocks); agents.
  • Contributors — cli (added setup-ci/automation/react-perf/ci-revert/ci-stale-check namespaces); health-audit (rewritten to the five-bucket Orchestrator/Adjudicator model); release; ci; wiki internals. release/mentorship/telemetry/_internal kept out of contributor docs too.

Audience + leak handling

Adopter pages cite no contributor-only paths; telemetry/mentorship/forensics-triage.yml muted per do-not-document.yml; contributor pages observe the same do-not-document rules. source-state.json snapshot refreshed to the verified gaia commit.

Verification

pnpm build passes (31 pages); zero em dashes site-wide.

Note for product (out of docs scope)

gaia wiki lint/consolidate write reports into wiki/meta/ with no mkdir -p, and wiki/meta is release-excluded, so a first lint/consolidate on a fresh adopter clone may fail. Worth a mkdir -p wiki/meta/ upstream.

🤖 Generated with Claude Code

stevensacks and others added 25 commits June 25, 2026 21:58
@stevensacks @claude
docs: 1.7.0 release updates
9005336 
Document the 1.7.0 surface and reconcile drift:

- spec: adversarial SPEC-audit step + silent merged-spec archiving
- plan: decomposition audit (three lenses)
- audit: clean zero-finding audits auto-apply, no gate
- harden: efficacy lens; drop mentorship-naming guardrail line
- agents: local-vs-CI audit mode + new worthiness-evaluator agent
- hooks: wiki-cache recompaction pair + worthiness-presence merge gate;
  correct red-verify-commit-check for the emergent-test exemption
- code skills: TDD determinism/worthiness + react-code platform-first ladder
- scaffolders/cli: scaffold route --dry-run, complex --props
- setup: audit-mode policy/choice steps; mute mentorship per docs voice
- fix typos (create-gaia, "is keeps"); setup-cloned step renumbering

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: address pre-1.7.0 doc gaps
6008823 
- spec.mdx: fix spec-close manual invocation (/speckit-gaia-spec-close
  [SPEC-NNN], optional arg); /gaia-spec close never routed (spec.md parses
  only `auto`).
- setup-cloned-gaia-project.mdx: surface the three automatic steps
  (spec-kit init, statusline permissions, env bootstrap).
- hooks.mdx: add WorktreeCreate section (.gaia/scripts/create-worktree.sh).
- gaia-init.mdx: add CI integration step (enable/skip; skip sets team audit
  default to local in .gaia/audit-ci.yml), cross-link /setup-gaia-ci and the
  agents reference; renumber subsequent steps.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: frame spec-close as automatic, manual as backstop (gaia#438)
6011ccc 
Lead with the automatic disposition path (wiki-promote chain on immediate
merge + step-3 housekeeping sweep) and name the two manual backstop cases
concretely: drain a deferred wiki-promote, or pick delete/keep over the
default archive. Confirms the /speckit-gaia-spec-close [SPEC-NNN] form
resolved in gaia PR #438; no stray /gaia-spec close references remain.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: sync gaia-init/setup-gaia-ci CI flow with gaia#439
c8dc8e3 
gaia-init's init CI step is now local-only: it records CI intent and writes
default_mode: local to .gaia/audit-ci.yml regardless of the answer, never
prints a token/required-check recipe, never creates a gaia-forensics label,
and never names or moves a workflow file.

- gaia-init.mdx: rewrite step 5 to the new option labels ("Yes, I'll enable
  CI after pushing" / "No, local only"), defer token + GAIA-Audit required
  check + workflow install to /setup-gaia-ci.
- setup-gaia-ci.mdx: document that step 7 registers GAIA-Audit as the required
  status check (admin + branch-protection needed; falls back to ci mode until
  registered), completing the deferred-install handoff.

Verified clean, no change needed: forensics.mdx (files to upstream
gaia-react/gaia, no local label), contributors/ci.mdx (forensics-triage.yml
documented as contributor-only), setup-cloned-gaia-project.mdx (no forensics).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
chore: bump astro 6.3.0 -> 7.0.2, starlight 0.39.1 -> 0.41.1
6eeda32 
Re-applies the upgrade that was rolled back in #3. The earlier break was
version skew: Starlight bundled @astrojs/mdx 5.0.6 (pre-6.4 markdown API),
so astro 6.4 silently dropped GFM and every table rendered as raw pipe
text (0 <table> in the build).

Starlight 0.41.1 now bundles @astrojs/mdx 7.0.0, which peer-depends on
astro ^7.0.0, so the mdx version tracks astro again and GFM survives.
Build is clean and produces the same 28 <table> elements across 13 pages
as the known-good baseline; no raw pipe-table leakage.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
chore: bump sharp 0.34.5 -> 0.35.2
a6b4592 
Image-optimization dep used by astro. Build is clean and table rendering
is unaffected (28 <table> across 13 pages).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: add Working in GAIA workflow walkthrough
307d2df 
New narrative page tying the /gaia-* commands into one day-to-day loop:
mostly-just-prompt, a when-to-reach-for-each table, a feature start to
finish (spec -> plan -> kickoff -> audit gate; handoff/pickup), and a
permissions section explaining the first-run --dangerously-skip-permissions
flag and the guardrail hooks that hold regardless.

Wired into the Getting started sidebar (after Quick Start) and forward-linked
from Quick Start.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: add Working in GAIA walkthrough page
9955a51 
New narrative page for the day-to-day GAIA loop: mostly-just-prompt plus test-first behavior, a two-group when-to-reach-for-each table (main commands vs statusline-nudged), a feature start to finish, and the first-run permissions and flag explanation. Adds it to the Getting started sidebar after Quick Start, forward-links from Quick Start, and reorders the Commands sidebar so /gaia-spec precedes /gaia-plan.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: document running concurrent /gaia-spec and /gaia-plan
721ad5b 
Add a Running more than one at once section to each page: two specs draw distinct SPEC ids from a locked ledger with no coordination; parallel plans get isolated directories, and a second plan on a live branch triggers the worktree, continue, or defer prompt.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: rewrite /gaia-init page for accuracy
ff01109 
The prior page misdescribed the prompts (invented a statusline-mode question, wrong title default, missing the GitHub-username question), carried a stale React Doctor command and a truncated exit message, and omitted several real steps. Rewritten against the command source: corrected questions, build check, CODEOWNERS, .env bootstrap, spec-kit registration, maintenance-tool modes, finalize, and the verbatim exit message with the cd and setup-gaia-ci reminder. The adaptation opt-in stays muted.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
style: theme callouts to the GAIA palette
dc6759a 
Re-theme Starlight asides off the stock purple and blue: tip becomes slate teal, note neutral warm gray, caution brand amber. danger keeps red until a GAIA danger color exists.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
chore: refresh source-state snapshot for docs accuracy pass
e5e3a2b 
Captured against gaia commit 0a4af7b via source-survey. Baseline for the
top-down 1.7.0 docs accuracy pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: accuracy pass on getting-started pages
8517d0a 
setup-gaia-ci: correct the four-workflow auto-merge claim (stale-branches
deletes branches directly, no PR), full "already configured" output string,
pnpm-audit issue+PR behavior, update-deps wave A/B PR split, wiki diff-size
auto-merge holdout, and the "already configured" reconfigure note.

setup-cloned-gaia-project: fix step-5 tooling cross-link, add finalize/
restart + worktree self-heal + GitHub CLI pre-check steps, remove the false
audit-mode re-run promise, and correct the commit/PR wording (the command
never auto-commits). Mentorship stays muted; forensics-triage.yml not leaked.

index (Quick Start): verified against create-gaia + package.json, no changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: accuracy pass on commands pages
c84fba1 
index: correct /gaia-audit, /gaia-fitness, /gaia-harden, /gaia-wiki, and
/gaia-forensics descriptions against source frontmatter; fix the autocomplete
prefix claim.

spec: fix inline plan-dispatch model (no general-purpose wrapper), self-review
timing (before gate 2), drop the wrong .specify/extensions.yml path, tighten
spec-close SPEC-id optionality, add the audit-finding-apply draft-cache trigger.

plan: correct the SPEC reference path (.gaia/local/specs/SPEC-NNN/SPEC.md),
remove the fabricated clipboard auto-copy step, and note the non-main
concurrent-orchestrator scan.

handoff-pickup: label these as skills (not commands); replace invented context
percentages with the sourced run-when guidance.

forensics: drop the false single-write-dir claim, fix GH issue body scope
(full body incl. frontmatter), reword the prune statement.

update-deps: correct branch behavior (any non-main branch runs in place, no PR).

update-gaia: add the merge-audit-ci / .gaia/audit-ci.yml field-aware merge
surface.

Telemetry and forensics-triage.yml stay unleaked; mentorship muted.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: accuracy pass on maintenance pages
0871bff 
maintenance overview: add the /gaia-harden row, fix /gaia-audit scope
(memory, wiki, and auto-loaded files, not "rules"), quote the description
to fix YAML frontmatter.

fitness: correct the "what gets checked" categories against the integration
fitness rubric, fix card header/sizing, ground the A-grade meaning, add grade
count boundaries, fix default-branch detection wording.

audit: fix statusline nudge reason strings, note the replace/shrink output
label and ordering, complete the audited-stores table, add the gaia-harden
provenance-rule exclusion.

harden: add the redirect action to the intro action set.

wiki: fix Cross-SPEC consolidate scope, the full-chain line-absent path, the
sync state bootstrap, and remove the unverified wiki/meta auto-creation claim.

Wiki framing preserved; mentorship/telemetry muted; no contributor leaks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: accuracy pass on skills pages
f06f592 
overview: split the catalog into four categories (workflow, code,
scaffolders, maintenance) and add the missing workflow + maintenance skills.

code: add the a11y-fixes full axe-rule set and the react-code React 19 gate;
add a gaia-react-perf catalog entry that cross-links to the new page.

scaffolders: fix the route output path (group values already include +), add
the --json flag to the component and hook invocations.

new page: skills/react-performance documents the gaia-react-perf measure-only
diagnostic (capture, gaia react-perf reduce, diagnose, verify), registered in
the Skills sidebar. react-doctor is correctly described as a third-party
scanner, not a GAIA skill; no contributor paths leaked.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: accuracy pass on reference pages
9f6816c 
hooks: add post-audit-status; fix block-rm-rf (relative paths fall through),
pr-merge-audit-check (multi-signal + /update-gaia self-mod exemption),
block-main-destructive-git (plain push from main), block-no-verify (HUSKY=,
hooksPath), audit-stamp-trailer (self-heal amend), check-story-exists (fires
on edit too); mute the mentorship clause in wiki-session-start. telemetry hook
stays undocumented.

rules: add react-router-docs and dep-audit; fix coding-guidelines, knip,
wiki-style entries; restore exact path globs on the path-scoped rules; correct
the thin-routes description. pr-merge and wiki-style maintainer-only blocks
stay omitted.

agents: fix the Suggestions tier label (Must Fix or Escalate) and the audit
marker conditions; worthiness-evaluator verified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: accuracy pass on contributors pages
7f3fc71 
index: name the maintainer generically (not by first name), add
audit-ci-tests.yml to the contributor CI list.

ci: fix cli-tests path filter, audit-ci-tests two-suite scope, and the
pnpm-audit schedule (daily, not weekly).

cli: add the setup-ci, automation, react-perf, ci-revert, and ci-stale-check
namespaces plus new init/update/wiki subcommands; fix the scaffold route
(--group required) and component (--no-story/--parent/--json) signatures.
release/mentorship/telemetry/_internal stay absent per do-not-document.

health-audit: rewrite to the five-bucket Orchestrator/Adjudicator model with
correct clean-exit gates, circuit breakers, honest grading, escalation enum,
and the /gaia-fitness distinction; archive is one-time init, not per cycle.

release: correct the manifest-class claim, add the /gaia-release behavioral
flow and the two-binary split, add the wiki-baseline reset step; no gaia
release subcommands named.

wiki: add the wiki/.state.json model, the gaia wiki CLI primitive table
(incl. chain), and the report-path patterns.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: promote React Code heading, fix spec concurrency wording
b35e659 
React Code now a top-level skill heading instead of nested under
TypeScript. Spec page no longer implies a two-session cap on concurrent
specs; the locked ledger is collision-safe for any number of sessions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: restructure command pages into Workflow and Maintenance groups
5b0d05e 
- Split commands/ into workflow/ and maintenance/ with grouped URLs
- Fold Working in GAIA into the Workflow overview page
- Split handoff-pickup into separate /gaia-handoff and /gaia-pickup pages, cross-linked
- Generalize the handoff/pickup example to a saved-search filters feature
- Add Changelog link to the header to match gaiareact.com
- Collapse the Contributors sidebar group by default and put the create-gaia notice in a callout

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: clarify react-performance intro and workflow command lead-in
6c52e15 
- Lead the react-performance page with feature and benefit, credit bippy and react-scan, plain-language the second sentence
- Reword the Workflow command table lead-in to a direct imperative

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: cut over-technical detail from adopter pages
25feff0 
Rewrite 53 passages and remove one internal CLI section across the
adopter docs so pages explain what and why, not under-the-hood
mechanism. Drops internal pipeline narration, jargon, and internal
variable/path/signal references; retitles the update-deps CLI section
after cutting the skill-internal decline flags. Contributor pages and
the hooks reference table left as-is.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: update handoff/pickup to delete-on-done lifecycle
7d22713 
Match GAIA #448: handoffs are transient with a single-handoff
invariant, replacing the archive-on-pickup model. Add a Lifecycle
section to handoff (one at a time, self-deletes when work lands,
stays if interrupted) and retitle pickup's Archive step to Resolve.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: add palette callouts for key warnings and gotchas
74fe4ee 
Lift irreversible-action warnings and easy-to-miss gotchas into themed
Asides: i18n strip and cd-relaunch (gaia-init), SPEC lock-on-save
(spec), silent push off main (update-deps), approve-drafts-a-scaffold
(harden), dev-build-required (react-performance), and a safe-by-default
tip (audit). Convert the hand-rolled Note blockquote on the landing
page to a real Aside, and trim a redundant line from the maintenance
tip.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@stevensacks @claude
docs: add Maintenance > GAIA CI explainer page
f287602 
New adopter page explaining what GAIA CI is, the four scheduled
maintenance jobs, and the ci/local/off run modes, so users can answer
the /gaia-init "how should the maintenance tools run?" question. Adds a
tip recommending the local code-review-audit experience. Registers the
sidebar entry and links it from the Maintenance Overview.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@stevensacks