@opengsd/gsd-core 1.5.0-rc.2 → 1.5.0-rc.4

package/gsd-core/bin/lib/capability-state.cjs

@@ -4,8 +4,8 @@
  *
  * Unified capability-state resolver that composes the three toggle systems
  * (install profile, runtime surface, config activation) into one per-capability
- * view. ADDITIVE — install/surface/workflows are untouched; this resolver is
- * consumed by nothing yet (phase-6 wiring is out of scope).
+ * view. The loop resolver consumes this state so workflow dispatch and the
+ * `gsd-tools capability state` diagnostic share the same enablement answer.
  *
  * Exports (three things, mirroring loop-resolver):
  *   resolveCapabilityState({ registry, installedSkills, surfacedSkills, config, cwd })
@@ -19,9 +19,9 @@
  * cmdCapabilityState is the I/O handler.
  *
  * Dependencies (leaf modules only — no core.cjs circular risk):
- *   - node:path (used by _resolveActivationValue via loop-resolver)
+ *   - node:path
  *   - ./core.cjs               (output, error)
- *   - ./loop-resolver.cjs      (_resolveActivationValue — reuse the export)
+ *   - ./capability-activation.cjs (_resolveActivationValue)
  *   - ./install-profiles.cjs   (readActiveProfile, loadSkillsManifest, resolveProfile)
  *   - ./surface.cjs            (resolveSurface)
  *   - ./config-loader.cjs      (loadConfig)
@@ -32,18 +32,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const core = require("./core.cjs");
 const { output: coreOutput, error: coreError } = core;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const loopResolverMod = require("./loop-resolver.cjs");
-const { _resolveActivationValue } = loopResolverMod;
+const activationMod = require("./capability-activation.cjs");
+const { _resolveActivationValue } = activationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfilesMod = require("./install-profiles.cjs");
-const { readActiveProfile, loadSkillsManifest, resolveProfile } = installProfilesMod;
+const { readActiveProfile, loadSkillsManifest, resolveProfile, parseRequires } = installProfilesMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const surfaceMod = require("./surface.cjs");
 const { resolveSurface } = surfaceMod;
@@ -133,6 +134,7 @@ function resolveCapabilityState(input) {
         else {
             surfaced = skills.every((s) => surfacedSkills.has(s));
         }
+        const enabled = installed && surfaced;
         // ── hooks ──────────────────────────────────────────────────────────────────
         // Collect from steps, gates, contributions. Each may have a `when` key.
         // Activation semantics (mirrors loop-resolver.isActive exactly):
@@ -149,21 +151,21 @@ function resolveCapabilityState(input) {
                 const point = typeof h['point'] === 'string' ? h['point'] : '';
                 // Carry the raw `when` value through for visibility
                 const whenRaw = h['when'];
-                let active;
+                let configured;
                 if (whenRaw === undefined || whenRaw === null) {
                     // No `when` field → unconditional, always active
-                    active = true;
+                    configured = true;
                 }
                 else if (typeof whenRaw === 'string' && whenRaw.length > 0) {
                     // Non-empty string `when` → resolve via _resolveActivationValue
-                    active = _resolveActivationValue(whenRaw, config, cwd, registry);
+                    configured = _resolveActivationValue(whenRaw, config, cwd, registry);
                 }
                 else {
                     // Present-but-empty-string or non-string `when` → malformed, inactive
                     // (mirrors loop-resolver.isActive: `typeof when !== 'string' || when.length === 0` → false)
-                    active = false;
+                    configured = false;
                 }
-                hooks.push({ point, kind, when: whenRaw, active });
+                hooks.push({ point, kind, when: whenRaw, configured, active: enabled && configured });
             }
         }
         const stepsRaw = capObj['steps'];
@@ -172,7 +174,7 @@ function resolveCapabilityState(input) {
         processHooks(Array.isArray(stepsRaw) ? stepsRaw : [], 'step');
         processHooks(Array.isArray(gatesRaw) ? gatesRaw : [], 'gate');
         processHooks(Array.isArray(contributionsRaw) ? contributionsRaw : [], 'contribution');
-        results.push({ id: capId, tier, skills, installed, surfaced, hooks });
+        results.push({ id: capId, tier, skills, installed, surfaced, enabled, hooks });
     }
     // Deterministic sort by id for stable output across calls
     results.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
@@ -192,6 +194,93 @@ function _resolveCommandsGsdDir() {
     const repoRoot = node_path_1.default.resolve(__dirname, '..', '..', '..');
     return node_path_1.default.join(repoRoot, 'commands', 'gsd');
 }
+/**
+ * Build a skill dependency manifest from an INSTALLED runtime's skills directory.
+ *
+ * In an installed runtime (e.g. Codex at ~/.codex), gsd skills live as
+ * configDir/skills/gsd-STEM/SKILL.md. There is no commands/gsd source tree.
+ * This function scans that installed layout and builds the same
+ * Map shape that loadSkillsManifest produces from sources.
+ *
+ * Stem extraction: a directory named gsd-secure-phase maps to stem secure-phase.
+ * Only directories whose names start with gsd- are included so user-created
+ * skills (without the gsd- prefix) are not accidentally pulled in.
+ *
+ * The requires: field is parsed via the shared parseRequires helper (the same
+ * parser loadSkillsManifest uses), so the two paths cannot drift.
+ *
+ * Returns an empty Map when the skills dir does not exist.
+ */
+function _loadInstalledSkillsManifest(configDir) {
+    const manifest = new Map();
+    const skillsDir = node_path_1.default.join(configDir, 'skills');
+    if (!node_fs_1.default.existsSync(skillsDir))
+        return manifest;
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return manifest;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!entry.name.startsWith('gsd-'))
+            continue;
+        // Strip the 'gsd-' prefix to get the skill stem
+        const stem = entry.name.slice(4); // 'gsd-'.length === 4
+        if (!stem)
+            continue;
+        const skillMdPath = node_path_1.default.join(skillsDir, entry.name, 'SKILL.md');
+        // Parity with loadSkillsManifest: a stem exists only when its artifact
+        // file is present. loadSkillsManifest registers a stem per .md FILE (and
+        // tolerates an unreadable file as []), but never invents a stem for which
+        // no file exists. Mirror that here: a stale gsd-<stem>/ directory with no
+        // SKILL.md must NOT register the stem — otherwise the capability would be
+        // wrongly reported surfaced/enabled and a verify:post hook would render
+        // for a skill that cannot run.
+        if (!node_fs_1.default.existsSync(skillMdPath))
+            continue;
+        let content = '';
+        try {
+            content = node_fs_1.default.readFileSync(skillMdPath, 'utf8');
+        }
+        catch {
+            // SKILL.md present but unreadable — register with no deps (parity with
+            // loadSkillsManifest's readFileSync catch branch).
+        }
+        // Parse requires: via the SAME shared parser loadSkillsManifest uses, so
+        // installed-runtime dependency resolution can never silently diverge from
+        // the source-tree path (single source of truth — no duplicated regex).
+        manifest.set(stem, content ? parseRequires(content) : []);
+        // Mirror loadSkillsManifest's Map shape: it always sets a companion
+        // `_calls_agents_<stem>` key. Installed SKILL.md bodies carry no
+        // recoverable agent-call refs, so [] (the no-agents case) keeps the two
+        // manifest shapes identical and prevents undefined-vs-[] drift for any
+        // consumer that reads the agent-refs companion key.
+        manifest.set(`_calls_agents_${stem}`, []);
+    }
+    return manifest;
+}
+/**
+ * Resolve the skill dependency manifest for capability-state resolution.
+ *
+ * Resolution order (fixes #1160 — installed-runtime capability surface):
+ *   1. If commandsGsdDir exists, load from source (repo-checkout behavior).
+ *   2. Otherwise, fall back to installed skills at configDir/skills/gsd-[stem]/SKILL.md.
+ *
+ * In an installed runtime the commands/gsd source tree is absent; only the
+ * skills/ layout exists. Returning an empty manifest caused resolveSurface to
+ * materialise the full-sentinel to an empty Set, making every capability appear
+ * unsurfaced even when the skill was physically installed.
+ */
+function _resolveManifest(commandsGsdDir, configDir) {
+    if (node_fs_1.default.existsSync(commandsGsdDir)) {
+        return loadSkillsManifest(commandsGsdDir);
+    }
+    return _loadInstalledSkillsManifest(configDir);
+}
 /**
  * Command entry point: resolve install profile, surface, and config; compute
  * capability state; emit the envelope via core.output.
@@ -222,7 +311,7 @@ function _resolveCommandsGsdDir() {
  * @param raw              Whether to emit raw JSON (core.output raw mode)
  * @param _options         Reserved for future use
  */
-function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
+function resolveCapabilityRuntimeState(cwd, runtimeConfigDir) {
     const warnings = [];
     // Resolve runtimeConfigDir using the canonical runtime-homes resolver.
     // When not provided, getGlobalConfigDir(runtime) is called with 'claude'
@@ -264,7 +353,9 @@ function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
     let installedSkills;
     try {
         const commandsGsdDir = _resolveCommandsGsdDir();
-        const manifest = loadSkillsManifest(commandsGsdDir);
+        // Fix #1160: use _resolveManifest so installed-runtime layouts (where
+        // commands/gsd is absent) fall back to <configDir>/skills/gsd-*/SKILL.md.
+        const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
         const profileName = readActiveProfile(resolvedConfigDir) ?? 'full';
         const resolvedInstall = resolveProfile({
             modes: profileName.split(',').map((s) => s.trim()),
@@ -277,7 +368,6 @@ function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
         // Genuine resolution failure — surface it so the caller is not misled.
         const msg = err instanceof Error ? err.message : String(err);
         warnings.push(`profile-resolution failed: ${msg}`);
-        coreError(`capability state: profile resolution failed: ${msg}`);
         // Degrade to empty set (not '*') so installed=false is reported accurately.
         installedSkills = new Set();
     }
@@ -285,7 +375,9 @@ function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
     let surfacedSkills;
     try {
         const commandsGsdDir = _resolveCommandsGsdDir();
-        const manifest = loadSkillsManifest(commandsGsdDir);
+        // Fix #1160: use _resolveManifest so installed-runtime layouts (where
+        // commands/gsd is absent) fall back to <configDir>/skills/gsd-*/SKILL.md.
+        const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
         const surfaceResult = resolveSurface(resolvedConfigDir, manifest, undefined, registry);
         // resolveSurface returns { name, skills: Set<string>, agents: Set<string> }
         // (always a concrete Set — full profile is materialized)
@@ -297,7 +389,6 @@ function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
         // Genuine surface resolution failure — surface it so the caller is not misled.
         const msg = err instanceof Error ? err.message : String(err);
         warnings.push(`surface-resolution failed: ${msg}`);
-        coreError(`capability state: surface resolution failed: ${msg}`);
         surfacedSkills = new Set();
     }
     // ── Load config ───────────────────────────────────────────────────────────────
@@ -316,21 +407,37 @@ function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
         config,
         cwd,
     });
+    return {
+        runtimeConfigDir: resolvedConfigDir,
+        warnings,
+        registry,
+        config,
+        capabilities: result.capabilities,
+    };
+}
+function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
+    const result = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
+    for (const warning of result.warnings) {
+        coreError(`capability state: ${warning}`);
+    }
     // Build envelope — include warnings array only when non-empty so the nominal
     // path keeps the output clean and callers can check `warnings` for degraded state.
     const envelope = {
-        runtimeConfigDir: resolvedConfigDir,
+        runtimeConfigDir: result.runtimeConfigDir,
         capabilities: result.capabilities,
     };
-    if (warnings.length > 0) {
-        envelope.warnings = warnings;
+    if (result.warnings.length > 0) {
+        envelope.warnings = result.warnings;
     }
     coreOutput(envelope, raw);
 }
 module.exports = {
     resolveCapabilityState,
+    resolveCapabilityRuntimeState,
     cmdCapabilityState,
     // Exported for tests
     _resolveCommandsGsdDir,
+    _loadInstalledSkillsManifest,
+    _resolveManifest,
     _isSafePropKey,
 };

package/gsd-core/bin/lib/capability-writer.cjs

@@ -0,0 +1,354 @@
+"use strict";
+/**
+ * Capability Writer — ADR-1213 write-side inverse of capability-state resolver.
+ *
+ * Exports:
+ *   setCapabilityState(cwd, runtimeConfigDir, desired, opts?)
+ *     → { capabilities: CapabilityStateEntry[], warnings: string[] }
+ *   cmdCapabilitySet(cwd, runtimeConfigDir, capId, options, raw)
+ *
+ * Projection rules (three axes: install, surface, config):
+ *   - enabled axis: mutates .gsd-surface.json via readSurface/writeSurface
+ *   - gates axis: mutates .planning/config.json via setConfigValues (batched)
+ *   - materialize: optionally calls applySurface to write skill files
+ *   - re-resolve: always calls resolveCapabilityRuntimeState for the return value
+ *
+ * Dependencies (leaf modules only — no circular risk):
+ *   - ./core.cjs               (output, error)
+ *   - ./capability-state.cjs   (resolveCapabilityRuntimeState, _resolveManifest, _resolveCommandsGsdDir)
+ *   - ./surface.cjs            (readSurface, writeSurface, applySurface)
+ *   - ./install-profiles.cjs   (readActiveProfile)
+ *   - ./config.cjs             (setConfigValues)
+ *   - ./runtime-artifact-layout.cjs (resolveRuntimeArtifactLayout)
+ *   - capability-registry.cjs  (loaded at call time)
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output: coreOutput, error: coreError } = core;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityStateMod = require("./capability-state.cjs");
+const { resolveCapabilityRuntimeState, _resolveManifest, _resolveCommandsGsdDir } = capabilityStateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const surfaceMod = require("./surface.cjs");
+const { readSurface, writeSurface, applySurface } = surfaceMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installProfilesMod = require("./install-profiles.cjs");
+const { readActiveProfile } = installProfilesMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configMod = require("./config.cjs");
+const { setConfigValues } = configMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspaceMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const nodefs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const nodepath = require("path");
+// ─── Implementation ───────────────────────────────────────────────────────────
+/**
+ * Write-side capability state mutator.
+ *
+ * Applies desired capability state changes (enabled axis via surface, gates
+ * axis via config) then re-resolves and returns the full capability state.
+ *
+ * Control flow:
+ *   1. RESOLVE BEFORE STATE: call resolveCapabilityRuntimeState once to get the
+ *      canonical runtimeConfigDir and current capability state.
+ *   2. VALIDATION PASS (no writes): validate each desired entry against the
+ *      registry and `before` state; collect errors and warnings.
+ *   3. If errors → return early with before.capabilities (no writes performed).
+ *   4. APPLY PASS: compute new surface state, writeSurface once if changed,
+ *      setConfigValues once for gate writes; materialize if opts provided.
+ *   5. RE-RESOLVE: call resolveCapabilityRuntimeState again to get final state.
+ *   6. POST CHECKS: enabled=true but not-surfaced (not-in-profile) error;
+ *      present-but-dead warning; append resolver warnings.
+ *   7. Return { capabilities: after.capabilities, warnings, errors }.
+ */
+function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
+    const warnings = [];
+    const errors = [];
+    // ── Step 1: Resolve BEFORE state once ────────────────────────────────────
+    const before = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
+    const resolvedConfigDir = before.runtimeConfigDir;
+    // ── Load registry ─────────────────────────────────────────────────────────
+    const registry = before.registry;
+    const capabilitiesMap = (registry['capabilities'] && typeof registry['capabilities'] === 'object' && !Array.isArray(registry['capabilities'])
+        ? registry['capabilities']
+        : {});
+    // ── Step 2: VALIDATION PASS (no writes) ──────────────────────────────────
+    // Accumulate all valid gate writes and surface deltas.
+    // If ANY error is found, we will return early without writing anything.
+    const pendingGateWrites = [];
+    // surface-delta accumulators: ids to add to / remove from disabledClusters
+    const idsToDisable = [];
+    const idsToEnable = [];
+    // Track which ids need surface loading (have skills + explicit enabled flag)
+    let needsSurface = false;
+    for (const entry of desired) {
+        const { id, enabled, gates } = entry;
+        // Validate capability id
+        if (!Object.prototype.hasOwnProperty.call(capabilitiesMap, id)) {
+            errors.push(`unknown capability: "${id}"`);
+            continue;
+        }
+        const capObj = capabilitiesMap[id];
+        const skillsRaw = capObj['skills'];
+        const skills = Array.isArray(skillsRaw)
+            ? skillsRaw.filter((s) => typeof s === 'string')
+            : [];
+        const configDef = (capObj['config'] && typeof capObj['config'] === 'object' && !Array.isArray(capObj['config'])
+            ? capObj['config']
+            : {});
+        // ── Validate gate keys / values ──────────────────────────────────────────
+        if (gates !== undefined) {
+            for (const [key, val] of Object.entries(gates)) {
+                if (!Object.prototype.hasOwnProperty.call(configDef, key)) {
+                    errors.push(`unknown gate key "${key}" for capability "${id}"`);
+                    continue;
+                }
+                if (typeof val !== 'boolean') {
+                    errors.push(`gate value for "${key}" must be boolean, got ${typeof val}`);
+                    continue;
+                }
+                pendingGateWrites.push({ keyPath: key, value: val });
+            }
+        }
+        // ── Validate enabled axis ────────────────────────────────────────────────
+        if (enabled !== undefined) {
+            if (skills.length === 0) {
+                // Advisory only — no surface effect possible
+                warnings.push(`capability "${id}" owns no skills; 'enabled' has no surface effect — use gates to toggle its hooks`);
+                continue;
+            }
+            // Install-floor check: cannot enable a capability whose skills are not installed
+            if (enabled === true) {
+                const beforeEntry = before.capabilities.find((c) => c.id === id);
+                if (beforeEntry && beforeEntry.installed === false) {
+                    errors.push(`cannot enable "${id}": its skills are not in the install profile`);
+                    continue;
+                }
+            }
+            needsSurface = true;
+            if (enabled === false) {
+                idsToDisable.push(id);
+            }
+            else {
+                idsToEnable.push(id);
+            }
+        }
+    }
+    // ── Fix D: Pre-validate config.json parseability before any write ────────
+    // If there are pending gate writes, attempt to read and parse the target
+    // config.json BEFORE writing anything. A malformed file would cause
+    // setConfigValues to error() mid-operation leaving a partial write.
+    if (pendingGateWrites.length > 0) {
+        try {
+            const configJsonPath = nodepath.join(planningDir(cwd), 'config.json');
+            if (nodefs.existsSync(configJsonPath)) {
+                const raw = nodefs.readFileSync(configJsonPath, 'utf-8');
+                try {
+                    JSON.parse(raw);
+                }
+                catch (parseErr) {
+                    const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
+                    errors.push(`config.json is malformed: ${msg}`);
+                }
+            }
+        }
+        catch {
+            // Cannot read the file path — not an error (e.g. planningDir env-var issue); let setConfigValues handle it
+        }
+    }
+    // ── Step 3: Early return on validation errors ────────────────────────────
+    if (errors.length > 0) {
+        return {
+            capabilities: before.capabilities,
+            warnings,
+            errors,
+        };
+    }
+    // ── Step 4: APPLY PASS ────────────────────────────────────────────────────
+    // ── Surface writes ────────────────────────────────────────────────────────
+    if (needsSurface && (idsToDisable.length > 0 || idsToEnable.length > 0)) {
+        const existing = readSurface(resolvedConfigDir);
+        let pendingSurface = existing ?? {
+            baseProfile: readActiveProfile(resolvedConfigDir) ?? 'full',
+            disabledClusters: [],
+            explicitAdds: [],
+            explicitRemoves: [],
+        };
+        let surfaceChanged = false;
+        for (const id of idsToDisable) {
+            // Add id to disabledClusters (dedupe)
+            if (!pendingSurface.disabledClusters.includes(id)) {
+                pendingSurface = {
+                    ...pendingSurface,
+                    disabledClusters: [...pendingSurface.disabledClusters, id],
+                };
+                surfaceChanged = true;
+            }
+            // Fix A: explicitAdds contains SKILL STEMS, not capability ids.
+            // Remove the capability's skill stems from explicitAdds so that
+            // resolveSurface does not re-add those skills after the cluster disable.
+            const capObjForDisable = capabilitiesMap[id];
+            const skillsRawForDisable = capObjForDisable?.['skills'];
+            const skillStemsForDisable = Array.isArray(skillsRawForDisable)
+                ? skillsRawForDisable.filter((s) => typeof s === 'string')
+                : [];
+            const newExplicitAdds = pendingSurface.explicitAdds.filter((x) => !skillStemsForDisable.includes(x));
+            if (newExplicitAdds.length !== pendingSurface.explicitAdds.length) {
+                pendingSurface = { ...pendingSurface, explicitAdds: newExplicitAdds };
+                surfaceChanged = true;
+            }
+        }
+        for (const id of idsToEnable) {
+            // Remove id from disabledClusters
+            if (pendingSurface.disabledClusters.includes(id)) {
+                pendingSurface = {
+                    ...pendingSurface,
+                    disabledClusters: pendingSurface.disabledClusters.filter((x) => x !== id),
+                };
+                surfaceChanged = true;
+            }
+            // Fix A (enable branch): also remove the capability's skill stems from
+            // explicitRemoves so that resolveSurface does not subtract those skills.
+            // Do NOT add anything to explicitAdds — a cap that was only in explicitAdds
+            // and was disabled is caught by the post-check below.
+            const capObjForEnable = capabilitiesMap[id];
+            const skillsRawForEnable = capObjForEnable?.['skills'];
+            const skillStemsForEnable = Array.isArray(skillsRawForEnable)
+                ? skillsRawForEnable.filter((s) => typeof s === 'string')
+                : [];
+            const newExplicitRemoves = pendingSurface.explicitRemoves.filter((x) => !skillStemsForEnable.includes(x));
+            if (newExplicitRemoves.length !== pendingSurface.explicitRemoves.length) {
+                pendingSurface = { ...pendingSurface, explicitRemoves: newExplicitRemoves };
+                surfaceChanged = true;
+            }
+        }
+        if (surfaceChanged) {
+            writeSurface(resolvedConfigDir, pendingSurface);
+        }
+    }
+    // ── Config writes (once, batched) ─────────────────────────────────────────
+    if (pendingGateWrites.length > 0) {
+        setConfigValues(cwd, pendingGateWrites);
+    }
+    // ── Materialize (optional) ────────────────────────────────────────────────
+    if (opts?.materialize) {
+        const { runtime, scope } = opts.materialize;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const runtimeArtifactLayout = require('./runtime-artifact-layout.cjs');
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope);
+            const commandsGsdDir = _resolveCommandsGsdDir();
+            const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            applySurface(resolvedConfigDir, layout, manifest, undefined, registry);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Fix C: materialise was explicitly requested — a failure is an error (non-zero exit),
+            // not merely advisory.
+            errors.push(`materialize failed: ${msg}`);
+        }
+    }
+    // ── Step 5: RE-RESOLVE ────────────────────────────────────────────────────
+    const after = resolveCapabilityRuntimeState(cwd, resolvedConfigDir);
+    // ── Step 6: POST CHECKS ───────────────────────────────────────────────────
+    // Check: desired enabled=true but not actually enabled after write
+    // (catches the not-in-profile / not-surfaced silent no-op case).
+    // The install-floor case (installed===false) was already caught in validation.
+    for (const entry of desired) {
+        if (entry.enabled === true) {
+            const afterCap = after.capabilities.find((c) => c.id === entry.id);
+            if (afterCap && afterCap.enabled !== true) {
+                errors.push(`cannot enable "${entry.id}": not in the active surface/profile (widen the profile or use /gsd:surface enable)`);
+            }
+        }
+        // Fix B: desired enabled=false — assert it is actually disabled after write.
+        // Prevents "off means off" silent failures (e.g. explicitAdds containing the
+        // cap's skill stems re-adds them after the cluster disable).
+        if (entry.enabled === false) {
+            const afterCap = after.capabilities.find((c) => c.id === entry.id);
+            if (afterCap && afterCap.enabled !== false) {
+                errors.push(`failed to disable "${entry.id}": still surfaced after write`);
+            }
+        }
+    }
+    // Check: present-but-dead — SCOPED to touched (desired) capabilities only.
+    const desiredIds = new Set(desired.map((d) => d.id));
+    for (const cap of after.capabilities) {
+        if (!desiredIds.has(cap.id))
+            continue;
+        if (cap.enabled === true &&
+            cap.hooks.length > 0 &&
+            cap.hooks.every((h) => !h.configured)) {
+            warnings.push(`capability "${cap.id}" is surfaced but every hook is gated off — did you mean enabled:false?`);
+        }
+    }
+    // Append resolver's own warnings
+    for (const w of after.warnings) {
+        warnings.push(w);
+    }
+    return {
+        capabilities: after.capabilities,
+        warnings,
+        errors,
+    };
+}
+/**
+ * CLI command entry point for `gsd-tools capability set`.
+ *
+ * Builds one DesiredCapability from the provided options, calls setCapabilityState,
+ * then prints the result. When raw=true emits JSON; else emits a human summary.
+ * Warnings are always printed to stderr.
+ */
+function cmdCapabilitySet(cwd, runtimeConfigDir, capId, options, raw) {
+    const desired = [
+        {
+            id: capId,
+            ...(options.enabled !== undefined ? { enabled: options.enabled } : {}),
+            ...(options.gates ? { gates: options.gates } : {}),
+        },
+    ];
+    const opts = options.runtime
+        ? { materialize: { runtime: options.runtime, scope: options.scope ?? 'global' } }
+        : undefined;
+    const result = setCapabilityState(cwd, runtimeConfigDir, desired, opts);
+    if (raw) {
+        // Raw mode: emit JSON to stdout including errors; exit non-zero if errors present.
+        // Do NOT print human stderr lines — raw consumers parse the JSON.
+        coreOutput({ capabilities: result.capabilities, warnings: result.warnings, errors: result.errors }, true);
+        if (result.errors.length > 0) {
+            process.exit(1);
+        }
+        return;
+    }
+    // Human mode: print warnings and errors to stderr (non-fatally for warnings).
+    for (const w of result.warnings) {
+        process.stderr.write(`capability set: warning: ${w}\n`);
+    }
+    for (const e of result.errors) {
+        process.stderr.write(`capability set: error: ${e}\n`);
+    }
+    // Exit non-zero if any errors (hard failures — requested action was not realized).
+    if (result.errors.length > 0) {
+        coreError(`capability set: ${String(result.errors.length)} error(s) — see above`);
+        return; // unreachable — coreError calls process.exit(1)
+    }
+    // Human-readable summary: focus on the target capability
+    const cap = result.capabilities.find((c) => c.id === capId);
+    if (!cap) {
+        const msg = `capability "${capId}" not found in registry`;
+        coreOutput(msg, false, msg);
+        return;
+    }
+    const activeHooks = cap.hooks.filter((h) => h.active).length;
+    const summary = `capability ${capId}: enabled=${String(cap.enabled)}, surfaced=${String(cap.surfaced)}, installed=${String(cap.installed)}, activeHooks=${String(activeHooks)}/${String(cap.hooks.length)}`;
+    coreOutput({ id: cap.id, enabled: cap.enabled, surfaced: cap.surfaced, installed: cap.installed, warnings: result.warnings.length > 0 ? result.warnings : undefined }, false, summary);
+}
+module.exports = {
+    setCapabilityState,
+    cmdCapabilitySet,
+};