msd-core/docs/adr/1213-capability-state-writer.md

ADR-1213: Capability write side — the Capability State Writer [Proposed]

• Status: Proposed
• Date: 2026-06-14
• Issue: #1213
• Completes: Capability system (ADR-857) — the write half of the phase-4 "Wire" step
• Builds on: Capability declaration format (ADR-894), Capability command contribution (ADR-959), Skill Surface Budget Module (ADR-0011)

Context

ADR-857 promised: "one resolved capability state replaces three contradicting toggle systems; 'off' means off." The read side delivers it. The Capability State Resolver (src/capability-state.cts) collapses three substrates into one resolved state:

• install profile — .gsd-profile (is the capability's skill set installed?)
• runtime surface — .gsd-surface.json (is it surfaced into the runtime skills dir?)
• config gates — config.json workflow.* (is each hook configured on?)

with enabled = installed && surfaced and active = enabled && configured.

There is no write side. Three independent writers each mutate one substrate — writeSurface (src/surface.cts), setConfigValue (src/config.cts), writeActiveProfile (src/install-profiles.cts) — and every caller (gsd:surface, gsd:settings/gsd:config, install.js, and the future ADR-959 capability command) coordinates them by hand. So off means off holds only as a read-time computation the write side can violate: the worst case is a capability left surfaced while every hook is config-gated off — "present but dead", still materialized and still costing context, but doing nothing.

The three substrates are not three ways to say one "off". They are orthogonal axes at different lifecycles: install is files-on-disk (uninstall removes them), surface is reversible-without-reinstall runtime state, and config gates are per-workstream and version-controlled in .planning/.

Decision

Introduce the Capability State Writer (src/capability-writer.cts), the inverse of the resolver:

setCapabilityState(cwd, runtimeConfigDir, desired: DesiredCapability[])
  -> { capabilities: CapabilityStateEntry[]; warnings: string[] }

DesiredCapability = { id: string; enabled?: boolean; gates?: Record<string, boolean> }

It accepts a desired capability state in the resolver's own vocabulary and projects it onto the substrates:

1. Two orthogonal axes, one interface. Per-capability enabled drives the runtime surface (the canonical capability on/off switch); per-hook gates drive the federated config keys (hook-level granularity within an enabled capability). The install profile is a read-only floor the writer never writes.
2. Surface is the canonical "off". Disabling unsurfaces — reversible, restart-and-go, and it reclaims the surface budget. It does not uninstall and does not clear config gates, so re-enabling restores prior gates; because enabled = false forces every hook active = false in the resolver, stale gates are harmless while off.
3. One write per substrate. A batch computes the full new surface state (one writeSurface) and the config deltas (one setConfigValue batch under withPlanningLock) — atomic per substrate, so no cross-substrate transaction is required.
4. Assert-and-report. After writing, re-run resolveCapabilityState and diff against desired; divergence (an uninstallable skill, a present-but-dead capability) is returned as warnings, not silently swallowed. The resolver is the writer's test surface: resolve(write(s, d)) == d.
5. Callers. gsd:settings and the ADR-959 capability command route capability mutations through it, and gsd-tools capability set is the direct CLI. gsd:surface is a broader skill-surface tool operating on the cluster superset — capability clusters plus hand-authored clusters such as utility/audit_review — so it keeps its own surface mechanism rather than routing through the capability-scoped writer; the resolver honours any surface write, so off means off holds regardless of which path wrote. install.js keeps the profile-floor write (install lifecycle).

A gsd-tools capability set subcommand (sibling to capability state) exposes it.

New domain term recorded in CONTEXT.md: Capability State Writer.

Alternatives considered

Decision	Rejected alternative	Why rejected
Substrate model	Collapse the three substrates into one capability-intent store	They encode genuinely different lifecycles (install = files on disk; surface = reversible runtime; config = per-workstream, version-controlled). Orthogonal axes, not redundant toggles; one store cannot hold the per-workstream config dimension without reinventing it. The resolver + writer win the invariant without merging the lifecycles.
Canonical "off"	Uninstall (drop from profile + delete files)	Heavy; needs a reinstall to undo; frees disk, not the context budget surface already reclaims. Keep uninstall as a separate explicit install-lifecycle operation.
Canonical "off"	Config-gate every hook	Leaves the skill surfaced-but-dead ("present but dead") and is per-workstream — contradicts off-means-off at capability granularity.
Interface scope	Capability-level enable only; hook gates stay in config-set	Splits the off-means-off invariant across two interfaces; the surfaced-but-all-gated check then has no single home.
Verification	Hard rollback (snapshot + restore)	Earns its keep only with cross-substrate transactions, which the one-write-per-substrate split avoids; assert-and-report suffices.

Consequences

Positive

• Off means off becomes a write-time invariant, not caller discipline.
• Locality: the projection and the invariants (including the present-but-dead check) live in one module.
• Leverage: one capability-mutation interface used by gsd:settings, the ADR-959 capability command, and the capability set CLI.
• Symmetric with the resolver seam; the surface and config writers become its internal adapters.

Negative / costs

• A new always-on module to build and keep correct (and a generated .cjs to ship via build:lib).
• The desired-state vocabulary becomes a depended-on interface (Hyrum's Law) — name it and keep it compatible.
• The present-but-dead signal is advisory: the writer warns rather than auto-mutating, respecting explicit intent.

Open questions

• Whether enabled: true for a capability below the install floor should auto-add it to surface explicitAdds (transitive closure) or warn-and-refuse.
• Whether the round-trip resolve ∘ write == identity warrants a deterministic CI conformance test alongside ADR-894's registry gates.