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>

src/capability-state.cts

@@ -125,6 +125,18 @@ interface ResolveCapabilityStateResult {
   capabilities: CapabilityStateEntry[];
 }
 
+/**
+ * Canonical **read-verb envelope** for the capability-state seam (ADR-1411 P3 / #1416).
+ *
+ * This is the shape emitted by the capability-state read verb:
+ *   `{ runtimeConfigDir, capabilities, warnings? }`
+ *
+ * The shared contract with other diagnostic shapes is `warnings: string[]`.
+ * Unlike `Resolution<T>` (src/resolution.cts, for config-interpreting read verbs),
+ * this read verb does not carry `configured`/`reason` — those fields are meaningful
+ * only for config-interpreting verbs such as agent-skills. Do NOT change the emitted
+ * JSON shape; this comment names the convention, it does not alter the contract.
+ */
 interface ResolveCapabilityRuntimeStateResult {
   runtimeConfigDir: string;
   warnings: string[];

src/capability-writer.cts

@@ -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[];

src/init.cts

@@ -46,6 +46,7 @@ const { checkAgentsInstalled } = agentInstallCheck;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- git-base-branch.cjs is an export= CommonJS module
 import gitBaseBranch = require('./git-base-branch.cjs');
 const { gitWorktreeInfoInternal } = gitBaseBranch;
+import { makeResolution } from './resolution.cjs';
 
 const { output, error } = io;
 const { loadConfig, loadConfigResolved } = configLoader;
@@ -2081,6 +2082,14 @@ function cmdAgentSkills(
   const normalizedPaths = Array.isArray(skillPaths) ? skillPaths : [];
 
   if (jsonMode) {
+    // Build the Resolution<AgentSkillsValue> envelope and embed .value additively.
+    // Flat fields are retained unchanged for back-compat; value formalises the
+    // Resolution convention (ADR-1411 P3, #1416). source/degraded remain
+    // config-provenance extras, outside the Resolution<T> envelope.
+    const resolution = makeResolution(
+      { block: block || '', skills_count: normalizedPaths.length },
+      { configured, reason, warnings: diagnostics.warnings },
+    );
     output({
       agent_type: agentType,
       block: block || '',
@@ -2090,6 +2099,7 @@ function cmdAgentSkills(
       reason,
       source,
       degraded,
+      value: resolution.value,
     }, raw);
     return;
   }

src/resolution.cts

@@ -0,0 +1,64 @@
+/**
+ * Resolution Convention — canonical shape for config-interpreting read verbs.
+ *
+ * Extracted as the anchor for ADR-1411 P3 (Resolution Provenance, #1416).
+ * Exports the `Resolution<T>` envelope used when a verb reads and interprets
+ * configuration (e.g. agent-skills). Not used by mutation verbs (see
+ * capability-writer's `SetCapabilityStateResult` for the mutation shape) or
+ * plain read verbs (see capability-state's `ResolveCapabilityRuntimeStateResult`).
+ *
+ * This is a pure types+builder leaf — no other src/ imports.
+ */
+
+// ─── Resolution envelope ──────────────────────────────────────────────────────
+
+/**
+ * Canonical output envelope for **config-interpreting read verbs**.
+ *
+ * - `value`      — the resolved domain value (T)
+ * - `configured` — true when the caller's agent/key was found in config
+ * - `reason`     — machine-readable resolution outcome (e.g. 'resolved',
+ *                  'not_configured', 'configured_empty', 'configured_unresolved')
+ * - `warnings`   — diagnostic messages (empty on nominal path)
+ *
+ * The shared contract across all diagnostic shapes is `warnings: string[]`.
+ * `configured`/`reason` appear only on config-interpreting read verbs;
+ * mutation verbs add `errors[]` (operation-not-applied) instead.
+ */
+export interface Resolution<T> {
+  value: T;
+  configured: boolean;
+  reason: string;
+  warnings: string[];
+}
+
+// ─── agent-skills value type ──────────────────────────────────────────────────
+
+/**
+ * The domain value for the agent-skills config-interpreting read verb.
+ * Used as the `T` in `Resolution<AgentSkillsValue>`.
+ *
+ * - `block`        — the formatted XML skills block (empty string when no skills)
+ * - `skills_count` — number of resolved skill paths (0 when not configured or empty)
+ */
+export interface AgentSkillsValue {
+  block: string;
+  skills_count: number;
+}
+
+// ─── Builder ──────────────────────────────────────────────────────────────────
+
+/**
+ * Construct a `Resolution<T>` envelope from a value and its provenance fields.
+ */
+export function makeResolution<T>(
+  value: T,
+  opts: { configured: boolean; reason: string; warnings: string[] },
+): Resolution<T> {
+  return {
+    value,
+    configured: opts.configured,
+    reason: opts.reason,
+    warnings: opts.warnings,
+  };
+}