* docs(#2674): amend adr-1411 with the corrupt-is-not-absent house pattern
ADR-1411 reasons only about a resolution miss. It is silent on input that
is present but not usable, which is how five engine read paths (#1879) could
fold an unusable input into the value meaning 'genuinely absent' without
contradicting an Accepted ADR.
Read together, ADR-1411 and ADR-227 converge and do not license throwing as
the cluster's answer: ADR-227 requires malformed input to be coerced rather
than propagated and carves out only genuinely-fatal fields, while ADR-1411
already permits a fallback provided it is 'a visible value, not a silent
substitution'. The defect in these five sites is therefore not that they fall
back but that they fall back invisibly.
Records the pattern that follows: every current return value is preserved, and
the cause is made visible in-band where the result already carries a
provenance envelope, or out-of-band via a deduplicated stderr diagnostic where
it returns a bare value it cannot extend. Throwing stays confined to ADR-227's
genuinely-fatal carve-out, decided per call. Also names the per-applier caller
audit and the lint-resolution-provenance registry gap.
Refs #1879
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* test(#2674): prove the warning-state reset misses the unknown-key dedup set
The two existing cases in this suite only pass because each picks a key
name no other case reuses, so neither can observe whether the reset the
beforeEach calls actually runs.
Failing-first: asserts the exported _warnedUnknownConfigKeys is empty after
_resetRuntimeWarningCacheForTests(). It is not - the helper clears only
_warnedConfigKeys despite documenting itself as resetting per-process
warning state.
Refs #1879
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#2674): reset the unknown-key dedup set with the runtime warning cache
_resetRuntimeWarningCacheForTests documents itself as resetting per-process
warning state but cleared only _warnedConfigKeys, leaving
_warnedUnknownConfigKeys populated across cases. The suite that exists to
test that set - 'loadConfig - unknown-key warning dedup' - calls the helper
in beforeEach expecting exactly this, so the reset was a silent no-op for
it; both cases passed only because each picked a key name the other never
reused. Any later case reusing a key would have had its warning suppressed
by leaked state.
Found while amending ADR-1411, which names this dedup guard as the pattern
five downstream PRs (#1880-#1884) will adopt - shipping the ADR without the
fix would have propagated the footgun to each of them. Folded in here per
CLAUDE.md's no-defer rule rather than filed.
RED verified on 3c4895841 (test only, no fix): linux-node22 reported
'FAIL tests/config-loader.test.cjs - the documented per-process
warning-state reset must clear the unknown-key dedup set too'.
Refs #1879
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs(#2674): document src/ in the changeset-lint trigger list
CONTRIBUTING.md presented the Changeset Required trigger list as bin/,
gsd-core/, agents/, commands/, hooks/, sdk/src/ - omitting src/, which
scripts/changeset/lint.cjs has in USER_FACING_PREFIXES. src/ is the
TypeScript source of truth compiled into gsd-core/bin/lib/*.cjs, so it is
the most-edited user-facing path in the repo and the omission sends any
contributor who touches it into a CI failure the doc says cannot happen.
Also documents that the lint reads GITHUB_BASE_REF, which only CI sets, so
running it bare locally reports success without evaluating the branch. This
PR hit exactly that: a local run said ok_fragment_present and CI failed
fail_missing_fragment on the same diff.
Found while opening this PR; folded in per the no-defer rule.
Refs #1879
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs(#2674): add Fixed changeset for the src/ trigger-list and reset fixes
Refs #1879
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs(#2674): restore the round-2 review corrections to the amendment
These edits were made in response to the second isolated review pass but
never staged: later commits used targeted `git add <file>` for the test and
the source fix, so the two markdown files stayed dirty and shipped nothing.
The branch carried the round-1 text, including the ADR-227 misquote the
reviewer raised as a blocker.
Restores: the unconditional-diagnostic clause (ADR-227's GSD_DEBUG opt-in
was never implemented, so citing it as the precedent was wrong), the dedup
key, #1882 folded into the out-of-band mechanism instead of a fourth
mechanism-less category, the narrowed caller-audit rationale, and the
test-methodology clause.
Refs #1879
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Narrows P3 of ADR-1411 (Resolution Provenance, epic #1411) based on an
adversarial fit-analysis that showed a single Resolution<T> envelope adopted
by agent-skills, capability-state, and capability-writer fails the deletion
test: configured/reason are meaningless for capability verbs, and
capability-writer's errors[] (operation-not-applied) cannot fold into
warnings[]. The only genuinely shared seam is warnings: string[].
Changes:
- src/resolution.cts: new pure types+builder leaf — exports Resolution<T>
{value, configured, reason, warnings}, makeResolution<T>() builder, and
AgentSkillsValue {block, skills_count}. No other src/ imports.
- src/init.cts: cmdAgentSkills --json IR gains additive value:{block,
skills_count} field (built via makeResolution). All existing flat fields
(agent_type, block, skills_count, warnings, configured, reason, source,
degraded) are retained unchanged for back-compat.
- src/capability-state.cts: doc comment on ResolveCapabilityRuntimeStateResult
naming it the canonical read-verb envelope. No JSON change.
- src/capability-writer.cts: doc comment on SetCapabilityStateResult naming it
the canonical mutation-verb result (warnings=advisory, errors=operation-
not-applied). No JSON change.
- CONTEXT.md: new ### Resolution Convention glossary entry after
### Resolution Provenance.
- docs/adr/1411-resolution-provenance.md: P3 narrowing amendment appended.
- tests/resolution.test.cjs: 9 unit tests for makeResolution (new).
- tests/agent-skills.test.cjs: 2 P3 tests for value.block/value.skills_count
and back-compat of all flat fields.
All 277 tests pass (5 suites). npm run lint clean. All lint checks pass.
Part of #1411
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Decision record for the Resolution Provenance epic (#1411, P0). Establishes that
context resolution (config loading, project-root anchoring, workstream resolution)
must report its provenance rather than fall open silently to defaults — the
resolution-side analog of ADR-227. Binds the Config Loader Module, Project-Root
Resolution Module, and I/O Module. Adds the ADR, the index/seam-map entry, and the
CONTEXT.md glossary term.
Part of #1411Closes#1412
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
