feat(#1416): formalize Resolution convention + agent-skills value envelope (Resolution Provenance P3) (#1425)
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>
This commit is contained in:
@@ -88,6 +88,21 @@ interface SetCapabilityStateOptions {
|
||||
materialize?: { runtime: string; scope: string };
|
||||
}
|
||||
|
||||
/**
|
||||
* Canonical **mutation-verb result** for the capability-writer seam (ADR-1411 P3 / #1416).
|
||||
*
|
||||
* Shape: `{ capabilities, warnings, errors }`
|
||||
*
|
||||
* - `warnings` — advisory messages (the verb still succeeded)
|
||||
* - `errors` — operation-not-applied messages; the write was not performed
|
||||
*
|
||||
* The shared contract with read-verb shapes is `warnings: string[]`.
|
||||
* Mutation verbs also carry `errors[]` (operation-not-applied), which is
|
||||
* load-bearing and distinct from `warnings[]` (advisory). This is why a single
|
||||
* generic `Resolution<T>` across read+write verbs was rejected by the deletion
|
||||
* test (ADR-1411 P3 amendment). Do NOT change the emitted JSON shape; this
|
||||
* comment names the convention, it does not alter the contract.
|
||||
*/
|
||||
interface SetCapabilityStateResult {
|
||||
capabilities: CapabilityStateEntry[];
|
||||
warnings: string[];
|
||||
|
||||
Reference in New Issue
Block a user