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>

.changeset/feat-1416-resolution-convention.md

@@ -0,0 +1,5 @@
+---
+type: Added
+pr: 1425
+---
+**`agent-skills --json` IR gains an additive `value: { block, skills_count }` field** formalizing the `Resolution<T>` convention for config-interpreting read verbs; no breaking change. The new `src/resolution.cts` module exports `Resolution<T> { value, configured, reason, warnings }` (the canonical envelope) and `makeResolution<T>()` (the builder); `AgentSkillsValue { block, skills_count }` is the first adopter. All existing flat fields (`agent_type`, `block`, `skills_count`, `warnings`, `configured`, `reason`, `source`, `degraded`) are retained for back-compat. Capability-state and capability-writer keep their existing JSON shapes unchanged; only doc comments are added naming them the canonical read-verb and mutation-verb envelopes respectively. The shared seam across all shapes is `warnings: string[]`; a single generic across read+write verbs was rejected by the deletion test (ADR-1411 P3 amendment). (Part of #1411, P3 / #1416.)

.gitignore

@@ -68,6 +68,7 @@ build/
 # Published via prepublishOnly; built before test via pretest. Grows as modules migrate.
 /tsconfig.build.tsbuildinfo
 /gsd-core/bin/lib/markdown-sectionizer.cjs
+/gsd-core/bin/lib/resolution.cjs
 /gsd-core/bin/lib/research-store.cjs
 /gsd-core/bin/lib/research-provider.cjs
 /gsd-core/bin/lib/package-legitimacy.cjs

CONTEXT.md

@@ -97,6 +97,9 @@ Module owning projection from project/workstream context to concrete `.planning`
 ### Resolution Provenance
 Cross-seam principle (ADR-1411, epic #1411): context resolution — config loading, project-root anchoring, workstream resolution — must report its provenance, not fall open silently to defaults. A resolver anchors deterministically to the project root (one walk-up module, no dependence on an arbitrary descendant cwd), returns *what* it resolved **and** *where it came from* (`source`/`degraded`), and surfaces a diagnostic when a *configured* input resolves empty (`not configured` and `configured-but-empty` are distinguishable). The resolution-side analog of ADR-227 (input-validation shape). Target seams: Config Loader Module (`loadConfig` → `ConfigResolution { config, source, degraded }`), Project-Root Resolution Module (single nearest-`.planning/` walk-up, retiring ad-hoc resolvers like `resolvePlanningCwd`), I/O Module (`Resolution<T> { value, configured, reason, warnings }` output envelope). A configured input resolving empty without a reason is a CI-guarded regression. **P1 (nearest-.planning/ heuristic) shipped in #1413; P2 (loadConfigResolved + agent-skills diagnostic) shipped in #1415 / closes #1366**: `loadConfigResolved` now implements the Config Loader seam target; `cmdAgentSkills` uses `findProjectRoot` + `loadConfigResolved` and emits `configured`/`reason`/`source`/`degraded` in its `--json` IR.
 
+### Resolution Convention
+Diagnostic-output convention for the Resolution Provenance principle (ADR-1411 P3, #1416). Config-interpreting read verbs expose `Resolution<T> { value, configured, reason, warnings }` (`src/resolution.cts`); agent-skills is the first adopter, where `value = { block, skills_count }` and `source`/`degraded` remain config-provenance extras outside the envelope. Other read verbs expose at least `warnings[]` (e.g. capability-state `{ runtimeConfigDir, capabilities, warnings? }`) without `configured`/`reason`, which are meaningful only for config-interpreting verbs. Mutation verbs expose `warnings[]` (advisory) PLUS `errors[]` (operation-not-applied), e.g. capability-writer `{ capabilities, warnings, errors }`. The shared seam across all shapes is `warnings: string[]`; a single generic `Resolution<T>` across read+write verbs was rejected by the deletion test (`configured`/`reason` are meaningless for capability verbs; `errors[]` cannot fold into `warnings[]`) — ADR-1411 P3 amendment. Recurrence prevention is delivered by P4's CI guard (a configured input resolving empty must carry a `reason`), not by a shared envelope.
+
 ### Worktree Safety Policy Module
 CJS Module owning worktree lifecycle safety policy for the GSD orchestration layer. Interface: `resolveWorktreeContext(cwd, deps) → WorktreeContext` (linked-worktree root mapping), `parseWorktreePorcelain(output) → WorktreeEntry[]` (porcelain parser, skips detached HEAD), `planWorktreePrune(repoRoot, opts, deps) → PrunePlan` (metadata-prune plan, never destructive by default), `executeWorktreePrunePlan(plan, deps) → PruneResult` (executes prune; degrades gracefully on git timeout), `listLinkedWorktreePaths(repoRoot, deps) → LinkedPathsResult`, `inspectWorktreeHealth(repoRoot, opts, deps) → HealthResult` (orphan + stale detection), `snapshotWorktreeInventory(repoRoot, opts, deps) → InventoryResult`, `planWorktreeWaveCleanup(repoRoot, manifest) → CleanupPlan` (manifest-scoped, fail-closed), `executeWorktreeWaveCleanupPlan(plan, deps) → CleanupResult`. Source of truth: `gsd-core/bin/lib/worktree-safety.cjs`. Timeout path: all git subprocess calls are bounded; callers receive `ok:false, reason:'git_timed_out'` rather than a thrown exception. Test anchor: `tests/worktree-safety.test.cjs`. The `core.cjs` re-export spine was retired in epic #1267: this module absorbed the two thin compositional wrappers that squatted in Core — `resolveWorktreeRoot(cwd, deps)` (a projection over `resolveWorktreeContext`) and `pruneOrphanedWorktrees(...)` (sequences `planWorktreePrune` + `executeWorktreePrunePlan` with a timeout warning) — so callers reach this single worktree-lifecycle seam directly. `gitWorktreeInfoInternal` did NOT move here — worktree-info detection belongs to the Git Query Module.
 

docs/INVENTORY-MANIFEST.json

@@ -350,6 +350,7 @@
       "prompt-budget.cjs",
       "research-provider.cjs",
       "research-store.cjs",
+      "resolution.cjs",
       "review-reviewer-selection.cjs",
       "roadmap-command-router.cjs",
       "roadmap-parser.cjs",

docs/adr/1411-resolution-provenance.md

@@ -75,3 +75,15 @@ Rejected. Fixing cwd/workstream drift removes the most common trigger but leaves
 - **Supersedes** the tactical fix in PR #1408 (closed) — its `resolvePlanningCwd` and local `AgentSkillsReason`/`AgentSkillsDiagnostics` are redelivered through the seams above in P1–P3.
 - **Builds on:** ADR-227 (input validation shape), ADR-0004 (Planning Workspace Module), ADR-0006 (Planning Path Projection Module).
 - **Prior recurrences of this class:** #1374/#1376, #1683, #991, #2714, #2638, #3523, #2652, #2791, #2555, #2623, #3196.
+
+## Amendment — 2026-06-18: P3 narrowed (the shared envelope is not a real seam)
+
+The original P3 plan was a single `Resolution<T> { value, configured, reason, warnings }` envelope adopted by `agent-skills`, `capability-state`, and `capability-writer`. An adversarial fit-analysis showed this fails the deletion test: `configured`/`reason` are meaningless for the capability read/mutation verbs, and `capability-writer`'s `errors[]` (operation-not-applied) is load-bearing and cannot fold into `warnings[]` (advisory). The only genuinely shared seam across the three is `warnings: string[]`.
+
+P3 is therefore narrowed to an honest convention rather than a forced generic:
+
+- `Resolution<T> { value, configured, reason, warnings }` (`src/resolution.cts`) is the canonical shape for **config-interpreting read verbs**. `agent-skills` is the first adopter — the `value` field is added additively to its `--json` IR with the flat fields retained for back-compat; `source`/`degraded` remain config-provenance extras.
+- Capability verbs keep their existing shapes, named explicitly: read = `{ runtimeConfigDir, capabilities, warnings? }`; mutation = `{ capabilities, warnings, errors }`.
+- The shared contract is documented, not forced: read verbs expose `warnings[]`; mutation verbs expose `warnings[]` + `errors[]`; `configured`/`reason` appear only on config-interpreting read verbs.
+
+Recurrence prevention does not depend on a shared envelope — it is delivered by P4's CI guard (a configured input resolving empty must carry a `reason`). (#1416)

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,
+  };
+}

tests/agent-skills.test.cjs

@@ -1570,4 +1570,53 @@ describe('agent-skills — Resolution Provenance (#1415)', () => {
       `Should emit WARNING for empty-string configured_empty, got stderr: ${r.stderr}`,
     );
   });
+
+  // ─── Resolution Convention P3 (#1416) ────────────────────────────────────────
+  // The --json IR gains an additive `value: { block, skills_count }` field
+  // (Resolution<AgentSkillsValue> envelope). All existing flat fields are retained
+  // for back-compat. RED: value field absent before build; GREEN: after build:lib.
+
+  test('P3 (#1416): --json IR includes value.block and value.skills_count matching flat fields (back-compat)', () => {
+    const skillDir = path.join(tmpDir, 'skills', 'p3-skill');
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), '# P3 Skill\n');
+    writeConfig(tmpDir, {
+      agent_skills: { 'gsd-executor': ['skills/p3-skill'] },
+    });
+    const r = runAgentSkillsJson(['agent-skills', 'gsd-executor'], tmpDir);
+    assert.ok(r.success, `Command failed: ${r.error}`);
+
+    // value field must exist and be an object
+    assert.ok(r.ir.value !== undefined && r.ir.value !== null, 'ir.value must be present (Resolution<AgentSkillsValue>)');
+    assert.strictEqual(typeof r.ir.value, 'object', 'ir.value must be an object');
+
+    // value.block must match flat block
+    assert.strictEqual(r.ir.value.block, r.ir.block, 'value.block must match flat block field');
+    assert.ok(r.ir.value.block.includes('<agent_skills>'), 'value.block must contain <agent_skills>');
+
+    // value.skills_count must match flat skills_count
+    assert.strictEqual(r.ir.value.skills_count, r.ir.skills_count, 'value.skills_count must match flat skills_count field');
+    assert.strictEqual(r.ir.value.skills_count, 1, 'value.skills_count must be 1 for one configured path');
+
+    // All existing flat fields must still be present (back-compat)
+    assert.strictEqual(typeof r.ir.agent_type, 'string', 'flat agent_type must still be present');
+    assert.strictEqual(typeof r.ir.block, 'string', 'flat block must still be present');
+    assert.strictEqual(typeof r.ir.skills_count, 'number', 'flat skills_count must still be present');
+    assert.ok(Array.isArray(r.ir.warnings), 'flat warnings must still be present');
+    assert.strictEqual(typeof r.ir.configured, 'boolean', 'flat configured must still be present');
+    assert.strictEqual(typeof r.ir.reason, 'string', 'flat reason must still be present');
+    assert.ok('source' in r.ir, 'flat source must still be present');
+    assert.ok('degraded' in r.ir, 'flat degraded must still be present');
+  });
+
+  test('P3 (#1416): value.block and value.skills_count are consistent when unconfigured', () => {
+    // No config → not_configured; value must still be present with empty block and 0 count
+    const r = runAgentSkillsJson(['agent-skills', 'gsd-executor'], tmpDir);
+    assert.ok(r.success, `Command failed: ${r.error}`);
+    assert.ok(r.ir.value !== undefined, 'ir.value must be present even when unconfigured');
+    assert.strictEqual(r.ir.value.block, r.ir.block, 'value.block must match flat block (empty)');
+    assert.strictEqual(r.ir.value.skills_count, r.ir.skills_count, 'value.skills_count must match flat skills_count (0)');
+    assert.strictEqual(r.ir.value.block, '', 'value.block must be empty when unconfigured');
+    assert.strictEqual(r.ir.value.skills_count, 0, 'value.skills_count must be 0 when unconfigured');
+  });
 });

tests/resolution.test.cjs

@@ -0,0 +1,89 @@
+/**
+ * Unit tests for src/resolution.cts → gsd-core/bin/lib/resolution.cjs
+ *
+ * Tests the `makeResolution` builder and the `Resolution<T>` envelope shape
+ * introduced for ADR-1411 P3 (Resolution Provenance, #1416).
+ */
+
+'use strict';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('path');
+
+const RESOLUTION_PATH = path.join(__dirname, '../gsd-core/bin/lib/resolution.cjs');
+
+describe('resolution module — makeResolution builder', () => {
+  test('module loads and exports makeResolution', () => {
+    const mod = require(RESOLUTION_PATH);
+    assert.ok(mod, 'module must be truthy');
+    assert.strictEqual(typeof mod.makeResolution, 'function', 'makeResolution must be a function');
+  });
+
+  test('makeResolution builds the Resolution<T> shape', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const result = makeResolution(
+      { block: '<agent_skills />', skills_count: 1 },
+      { configured: true, reason: 'resolved', warnings: [] },
+    );
+    assert.ok(result, 'result must be truthy');
+    assert.ok('value' in result, 'result must have value field');
+    assert.ok('configured' in result, 'result must have configured field');
+    assert.ok('reason' in result, 'result must have reason field');
+    assert.ok('warnings' in result, 'result must have warnings field');
+  });
+
+  test('makeResolution preserves the value as-is', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const value = { block: '<agent_skills>test</agent_skills>', skills_count: 2 };
+    const result = makeResolution(value, { configured: true, reason: 'resolved', warnings: [] });
+    assert.deepStrictEqual(result.value, value, 'value must be preserved');
+    assert.strictEqual(result.value.block, '<agent_skills>test</agent_skills>');
+    assert.strictEqual(result.value.skills_count, 2);
+  });
+
+  test('makeResolution carries configured field', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const trueResult = makeResolution({ block: '', skills_count: 0 }, { configured: true, reason: 'configured_empty', warnings: [] });
+    const falseResult = makeResolution({ block: '', skills_count: 0 }, { configured: false, reason: 'not_configured', warnings: [] });
+    assert.strictEqual(trueResult.configured, true, 'configured:true must be preserved');
+    assert.strictEqual(falseResult.configured, false, 'configured:false must be preserved');
+  });
+
+  test('makeResolution carries reason field', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const reasons = ['resolved', 'not_configured', 'configured_empty', 'configured_unresolved'];
+    for (const reason of reasons) {
+      const result = makeResolution({ block: '', skills_count: 0 }, { configured: false, reason, warnings: [] });
+      assert.strictEqual(result.reason, reason, `reason '${reason}' must be preserved`);
+    }
+  });
+
+  test('makeResolution carries warnings array', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const warnings = ['path /foo/bar not found', 'path /baz not found'];
+    const result = makeResolution({ block: '', skills_count: 0 }, { configured: true, reason: 'configured_unresolved', warnings });
+    assert.deepStrictEqual(result.warnings, warnings, 'warnings must be preserved');
+    assert.strictEqual(result.warnings.length, 2);
+  });
+
+  test('makeResolution with empty warnings array', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const result = makeResolution({ block: '<agent_skills />', skills_count: 1 }, { configured: true, reason: 'resolved', warnings: [] });
+    assert.deepStrictEqual(result.warnings, [], 'empty warnings array must be preserved');
+  });
+
+  test('makeResolution works with non-AgentSkillsValue generics (string)', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const result = makeResolution('hello', { configured: true, reason: 'resolved', warnings: [] });
+    assert.strictEqual(result.value, 'hello', 'string value must be preserved');
+    assert.strictEqual(result.configured, true);
+  });
+
+  test('makeResolution result has exactly the four envelope fields plus value', () => {
+    const { makeResolution } = require(RESOLUTION_PATH);
+    const result = makeResolution(42, { configured: false, reason: 'not_configured', warnings: [] });
+    const keys = Object.keys(result).sort();
+    assert.deepStrictEqual(keys, ['configured', 'reason', 'value', 'warnings'], 'envelope must have exactly 4 fields');
+  });
+});