* docs(#3240): record the codex passive/session-only model posture
ADR-2313 locks the install-time contract for epic #2313: omit the
per-agent model from generated ~/.codex/agents/<agent>.toml by default
so the agent inherits the always-available Codex session model, embed
one only for an explicit real-Codex model_overrides pin, and keep
model_reasoning_effort coupled to a pinned model (#838). Supersedes
#2517's per-tier embedding on the default path only.
Also records the reader/writer boundary the downstream phases need
(strict writer, liberal-but-visible readers, never partially rewrite an
unparseable .toml), the migration path for API-key Codex users, and the
Phase 5 the coverage gate found unowned.
Amends ADR-1239 with a dated section: its effortSurface amendment
described this ADR as "not yet written", and the install-time vs
invocation-time boundary is now stated from both sides.
Docs-only. The posture is not real until Phase 1 (#3241) merges.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3240): remove the ADR index count cells that race between PRs
The generated region of docs/adr/README.md carried three numeric cells —
a per-group `### <heading> (N)` and a `_N ADRs._` footer — that every
ADR-adding PR must rewrite. Two PRs adding different ADRs merge their
table rows cleanly, since those are distinct lines, but both rewrite the
same count lines, so whichever lands second gets a green local
`gen-adr-index.cjs --check` and a red CI one: CI evaluates the PR merged
with next, where the count reflects both ADRs.
That is not hypothetical. It reddened this PR: ADR-2313 regenerated the
index at 75 while #3249 landed ADR-3247 concurrently, making the merged
tree 76.
The counts carry no verification value — --check regenerates and diffs
the whole region regardless — and are derivable by reading the table, so
they are removed rather than tolerated. Loosening --check to ignore them
would have let genuine staleness through. This is the shared-mutable-cell
problem CHANGELOG.md and the drift acks already solved with per-PR
fragment files; here removing the cell is enough.
The regression test locks the invariant rather than the symptom: adding
an ADR only INSERTS lines, so render(N) is a line-subsequence of
render(N+1). That is the property that makes concurrent PRs merge, and
unlike asserting the absence of one count format it fails for a count
reintroduced in any shape. Covered at append, lowest-id, middle-id,
empty-corpus, new-status-group, and hazardous-title positions; each names
the pre-fix line that would have failed it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* 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>
ADR-1239 gains a ninth negotiated axis, effortSurface (argv | none), declaring how
a host accepts reasoning effort. ADR-443 is amended in the same change because its
recorded deferral is what the axis resolves: its Unblock condition offered paths
(a) and (b) and stated the choice was 'a maintainer call this file records but does
not make'. Path (a) is selected and satisfied here.
Before this, effort reached a runtime only through install-time channels
(EFFORT_RENDERING's frontmatter/api), so reviewer CLIs spawned as subprocesses
silently inherited whatever effort sat in the user's own global CLI config. The
review lane now resolves one universal effort through the ADR-443 cascade and
renders it per host through the negotiated descriptor.
Every per-host value is documentation-sourced, never inferred:
- claude argv -- verified via 'claude --help' (--effort <level>)
- opencode argv -- verified via 'opencode run --help' (--variant)
- codex argv -- codex-rs/exec/src/cli.rs: model_reasoning_effort is NOT a CLI
flag (config.toml key only), so the global -c override is the
only argv route
- 15 hosts undocumented -- their docs state no reasoning setting; the sentinel
fails closed rather than inheriting a profile baseline
No config-file vocabulary member: the only host that ever had one (Gemini CLI's
thinkingConfig) was removed as a sunset runtime by 8f2ebbe9b (#1928, PR #1996),
and neither Antigravity CLI nor ZCode documents a reasoning setting.
Closes#2481
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(#1684): add negotiated host-integration interface module
ADR-1239 Phase A: a pure, additive, no-I/O module exposing PROTOCOL_VERSION, the 8-axis HOST_INTEGRATION_AXES closed vocabulary, the UNDOCUMENTED fail-closed sentinel, negotiateHostCapabilities (effective subset of host-declared and engine-known), a typed degradation ladder, and host-capability profiles.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(#1684): validate and document host-integration axes (16 runtimes)
Extend validateRuntimeBody to validate the 8 hostIntegration axes (closed enums + undocumented sentinel + dispatch struct + reserved-key guards) and the widened runtime vocabulary; author a documentation-sourced hostIntegration block in all 16 runtime descriptors; regenerate the registry. Every per-CLI value is documented (cited) or the explicit undocumented sentinel.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs(#1684): add host-integration capability matrix and adr amendment
New per-CLI, per-axis citation reference (value/source/evidence for all 16 CLIs); ADR-1239 Phase-A-implemented amendment; CONTEXT.md glossary seam entry.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(#1684): harden dispatch negotiation edge cases
Code-review hardening: treat NaN/Infinity maxDepth as missing (fail-closed, +warning); reset nested/background when namedDispatch collapses to false (struct consistency); SAFE_DEFAULTS dispatch floor to read-only; warn on non-finite protocolVersion; symmetric undocumented warnings for dispatch fields. Pure module — no consumers; behaviour fail-closed throughout.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* chore(#1684): register host-integration.cjs in lint-ignore and inventory
New tsc-generated bin/lib artifact: add to the eslint ignore list (ADR-457 — lint the .cts source), regenerate docs/INVENTORY-MANIFEST.json, and add the docs/INVENTORY.md CLI-modules row. Fixes the 3 gsd-test failures (551-eslint-bin-lib-coverage x2 + inventory-manifest-sync).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs(#1684): add changeset fragment for host-integration interface
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs(#1684): add how-to for sourcing a host's integration axes
Diataxis how-to guide for adding/updating a host's runtime.hostIntegration axes from authoritative docs, the undocumented-sentinel rule, validation, and extending the closed vocabulary. Completes the Step-5 doc quadrants (reference + explanation + how-to). Indexed in docs/README.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs(#1239): ADR for GSD as an embeddable orchestration engine
Records the design to invert GSD from a standalone installer that projects
onto a host into an embeddable orchestration engine a host loads as a plugin,
driven through a negotiated host-integration interface. Unifies ADR-1016
projection (the declarative adapter) with imperative embedding behind one
contract; grounded in a 9-host capability survey.
Closes#1239
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(#1239): de-slash illustrative command placeholders (docs-parity gate)
Replace illustrative /gsd:x /gsd-x /gsd.x placeholders with namespace-prefix
wording so the docs-parity live-registry check does not parse them as
non-live commands.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
