16e59d0db5
* fix(#2691): repair five dangling references in the ADR corpus and contributor docs
Found by the 2026-07-24 ADR corpus audit; each mechanism re-reproduced live
against next @ 3eb1cede before filing.
1. docs/adr/1239-gsd-embeddable-orchestration-engine.md linked the
host-integration capability matrix as `reference/...` from inside
docs/adr/, which resolves to the nonexistent docs/adr/reference/.
Three occurrences (the #2584 amendment added two after the audit).
All now `../reference/...`.
2. src/plan-drift-guard.cts cited docs/adr/0022-source-grounding-drift-guard.md,
a path that has never existed (git log --all --diff-filter=A returns
nothing). Corrected to docs/adr/22-plan-drift-guard.md. Comments survive
tsc and ADR-457 builds at publish, so the bad citation shipped to users --
verified by grepping the compiled gsd-core/bin/lib/plan-drift-guard.cjs.
3. CONTRIBUTING.md and docs/contributor-standards.md illustrated the ADR
naming convention with issue #3485 -- a pre-rename number from the
predecessor repo (get-shit-done-redux) that does not resolve in
open-gsd/gsd-core. It is dangling, not invented: ADR filenames 3524 and
3660 show pre-rename numbering reached the 3000s. The worked example now
uses #2264, which resolves; the one genuinely historical mention is
annotated rather than rewritten.
4. docs/adr/857-capability-system.md's H1 carried a stale [Proposed] bracket
contradicting its "Accepted -- ratified 2026-07-17" Status field.
gen-adr-index.cjs:213 strips the bracket rather than comparing it, so the
contradiction was invisible to the gate; it is also the only in-repo
consumer, so removal leaves the rendered index byte-identical.
5. gen-adr-index.cjs's back-link comment still described ADR-857 as Proposed
and its claim over ADR-0011/ADR-58 as a supersession. Both were restated
at ratification (the claim became Subsumes; the reciprocals were added).
Regression coverage folds into tests/adr-index-gate.test.cjs rather than a
new bug-* file (lint-regression-test-names): four cases covering link
resolution, H1-bracket-vs-Status agreement, the plan-drift-guard citation,
and the naming worked example. All four fail at the pre-fix tree.
No behavior change. lint:ci exit 0; adr-index-gate 35/35; index regenerates
unchanged (67 ADRs).
* chore(#2691): add the required pr: field to the changeset fragment
docs-lint rejected the fragment with fail_malformed_fragment / missing_pr: the
frontmatter needs both `type:` and `pr:`. The fragment was hand-authored before
the PR existed, so it carried only `type:`.
Note for future work: neither lint:docs nor lint:changeset is part of the
lint:ci chain, so a green lint:ci does not cover these two CI checks. Both were
run directly before this push:
ok docs-lint: ok_no_triggering_fragments
ok changeset-lint: ok_fragment_present
* fix(#2691): drop the false branch clause and repair two more matrix links
Review round 2 on #2692, both blocking findings.
F1: the worked example at CONTRIBUTING.md:101 asserted
'on branch docs/2264-golden-parity-redesign'. That branch never existed --
the ADR file carries the epic number (#2264) while the branch and commit
carry the Phase-0 sub-issue number (#2265, PR #2270, branch
docs/2265-golden-parity-adr). #2264 is therefore the one ADR in the corpus
where filename and branch numbers deliberately disagree, making it the worst
available illustration of 'the issue number becomes your prefix and your
branch'. The branch clause is dropped; the surviving claim is verified
(#2264 is open-and-approved with approved-enhancement, and the file is
2264-golden-parity-redesign.md).
F3: docs/how-to/install-on-your-runtime.md:460 and :476 linked the
host-integration capability matrix as a bare filename from inside
docs/how-to/, which resolves to the nonexistent
docs/how-to/host-integration-capability-matrix.md. Same defect class as
repair #1 in this PR. Both now use ../reference/..., matching the form
already used by the sibling add-or-update-a-host-integration.md:167.
* fix(#2691): take the review minors -- anchors, bracket, ADR path, token order
Review round 2 on #2692, non-blocking findings.
F4: ADR-1239:198,206 read '[capability matrix §codex](...matrix.md)' -- the
link text promised a section, the target carried no fragment. '## codex'
exists at docs/reference/host-integration-capability-matrix.md:85, and the
repo already uses that form (#zcode, #pi in the how-to).
F5: docs/adr/857-capability-system.md:1 had its stale [Proposed] bracket
dropped rather than corrected, making 857 the only ratified ADR with no H1
bracket while four other Accepted ADRs carry one. Restored as [Accepted],
which satisfies the H1-vs-Status invariant and preserves consistency. No
recorded rule mandates the bracket, so this is style, not contract.
F7: docs/CONFIGURATION.md:808 cited adr/1244-runtime-capability-registry-
overlay.md; the actual file is adr/1244-capability-ecosystem.md. Same defect
class as repair #2, one directory over.
F8: test 33 resolved the Status token with STATUS_TOKENS.find(), which
matches by array order rather than by position in the line. Since
STATUS_TOKENS[0] === 'Accepted', a future '- **Status:** Superseded by ADR-X
(was Accepted ...)' paired with an H1 [Superseded] would have reported a
false mismatch. Now resolved by earliest index in the line. No ADR has that
shape today, so this is latent; ADR-857's two-token Status line resolves to
'Accepted' under both the old and new rule.
Changeset updated: five repairs -> seven, adding the two how-to matrix links
and the CONFIGURATION.md ADR path, plus the (#2691) issue backlink that 46
of the other 47 fragments carry.
Not addressed here: F2 (widening the guard to resolve anchors and walk docs/
recursively) is filed separately as #2704, approved-enhancement.
---------
Co-authored-by: CI Rebase Check <ci@gsd-redux>
GSD Core documentation
Documentation is organised into four quadrants: tutorials help you learn by doing, how-to guides solve specific tasks, reference states authoritative facts, and explanation explores concepts and design decisions.
Language versions: English · Português (pt-BR) · 日本語 · 简体中文
Tutorials
- Your first project — install to first shipped phase, one guaranteed path
- Onboarding an existing codebase — bring GSD Core to a brownfield repo
- Build your first capability — author a tiny declarative capability and watch it act in the loop
- Install your first capability — install a third-party capability end-to-end: consent, verify, check for updates, remove
How-to guides
- Install on your runtime — runtime-specific install steps for all 16 supported runtimes
- Install a minimal GSD and add skills later — install only the core skills, then grow the surface with profiles and
/gsd:surface - Attach a plugin-provided skill to a GSD agent — use the
global:plugin:skillentry form to load Claude Code plugin skills into agent prompts - Discuss a phase — capture implementation decisions before planning begins
- Resolve edge-coverage findings — turn the spec phase's surfaced domain-boundary edges into covered, dismissed, or backstopped spec decisions
- Resolve prohibition findings — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
- Plan a phase — run research, decompose work, and verify plan quality
- Execute a phase — run plans in parallel waves with fresh-context subagents
- Verify and ship — walk through completed work, diagnose failures, and create the PR
- Run phases autonomously — use autonomous mode for unattended phase execution
- Handle quick and fast tasks — use
/gsd-quickand/gsd-fastfor ad-hoc work outside the phase loop - Configure model profiles — switch between quality, balanced, and budget model tiers
- Set up cross-AI review — configure a second AI to review code produced by the primary agent
- Work in parallel with workstreams — run independent lines of work simultaneously using workstreams
- Isolate work with workspaces — use workspaces to sandbox experimental or risky changes
- Debug a failed execution — diagnose and recover from broken or incomplete phase execution
- Spike and sketch — use
/gsd-spikeand/gsd-sketchfor exploratory work before committing to a plan - Design a UI phase — use the UI phase loop for frontend and visual work
- Develop a Capability for GSD 1.5+ — add feature Capabilities, hook fragments, and registry entries
- Add or update a host's integration — set a host's documentation-sourced
runtime.hostIntegrationaxes (ADR-1239 Phase A), with theundocumentedsentinel rule - Turn a capability off (and keep it off) — disable a capability via the surface, or gate individual hooks off without removing the capability
- Drive GSD from a tracker issue — start a phase from a GitHub, Linear, or Jira issue
- Migrate from GSD 2 — upgrade an existing GSD 2 project to GSD Core
- Update GSD — re-run the installer to pick up the latest release
- Clean up get-shit-done-cc — remove leftover old-package artifacts that cause a spurious
⬆ /gsd:updateindicator after migrating to@opengsd/gsd-core - Fix the worktree base-mismatch (exit 42) error — resolve the branch-divergence condition that halts parallel phase execution
- Recover and troubleshoot — fix common problems, rebuild context, and uninstall
Reference
- Commands — every command with flags and examples
- Configuration — full config schema, model profiles, git branching strategies
- CLI tools —
gsd-tools.cjsprogrammatic API for workflows and agents - Features — complete feature index
- Inventory — installed skills and surface map
- STATE.md schema — field-by-field reference for
.planning/STATE.md - CONTEXT.md schema — field-by-field reference for
.planning/phases/<N>/CONTEXT.md - PLAN.md schema — field-by-field reference for
.planning/phases/<N>/PLAN.md - Planning artifacts — all
.planning/files and their roles - Review and verification capabilities — code review, security, and Nyquist capability ownership and hook contracts
- Capability matrix — generated catalogue of every capability's role, tier, extension points, hook kinds, and
engines.gsd - Capability manifest — the full
capability.jsonschema and validation rules gsd capabilitycommand — install / update / remove / list reference for third-party capabilities
Explanation
- Context engineering — how context rot forms and how GSD Core prevents it
- The phase loop — design rationale for the Discuss → Plan → Execute → Verify → Ship cycle
- Multi-agent orchestration — how subagents are spawned, scoped, and coordinated
- Security model — trust boundaries, permissions, and safe automation
- The capability trust model — why third-party capabilities are gated by consent + integrity + reversibility, not a sandbox
- How overlay capabilities compose — why first-party always wins and how the loader resolves precedence, conflicts, and fail-open load-failure warnings
- Architecture — system architecture, agent model, and data flow
- The Embeddable Orchestration System — one public, versioned contract for embedding GSD across many hosts
- Discuss modes — assumptions mode vs interview mode for
/gsd-discuss-phase - Context monitoring — context window monitoring hook architecture
- Issue-driven orchestration — recipe for driving GSD from a tracker issue using existing primitives
Related
- What's new in 1.7.0 — curated highlights of the 1.7.0 release
- Root README — landing page, quickstart, and documentation overview
- Changelog — release history