@opengsd/gsd-core 1.7.0-rc.1 → 1.7.0-rc.3

package/gsd-core/bin/lib/frontmatter.cjs

@@ -126,6 +126,49 @@ function extractFrontmatter(content) {
     }
     return frontmatter;
 }
+/**
+ * Escape a string for emission inside a YAML double-quoted scalar (#1779).
+ * Backslash must be escaped first so the backslashes added for embedded quotes
+ * (and control chars) are not themselves doubled. Without this, a value
+ * carrying an indicator (`:`/`#`) that also contains a literal `"` serializes
+ * to invalid YAML, e.g. `upstream: "https://x (Tom; "Git. Ship. Done")"`. A
+ * literal newline/tab/control char inside the quotes likewise breaks (or
+ * silently alters) the scalar, so those are escaped to their YAML forms too.
+ */
+function escapeDoubleQuoted(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t')
+        .replace(/\r/g, '\\r')
+        // Remaining C0 controls + DEL → \xHH (a valid YAML double-quoted escape).
+        .replace(/[\u0000-\u001f\u007f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
+}
+/**
+ * A plain (unquoted) scalar that would mis-parse or round-trip lossily when
+ * emitted bare must instead go through the double-quoted + escaped form
+ * (#1779): the empty string (bare `k:` reloads as null), an embedded `"`/`\`
+ * or control char, a leading YAML indicator (quote, `&`/`*`/`!` anchor/alias/
+ * tag, `|`/`>` block scalar, flow `[]{},`, `#`, reserved `%`/`@`/backtick, or
+ * `-`/`?`/`:` before a space), or leading/trailing whitespace. This helper is
+ * the correctness complement of `escapeDoubleQuoted`: it broadens the *trigger*
+ * for quoting without broadening the lossy object-list handling deferred to
+ * #1572/#1660.
+ */
+function scalarNeedsDoubleQuoting(s) {
+    if (s === '')
+        return true;
+    if (/["\\\u0000-\u001f\u007f]/.test(s))
+        return true;
+    // Always-unsafe leading indicators, or leading/trailing whitespace.
+    if (/^[,[\]{}#&*!|>'"%@`]/.test(s) || /^\s|\s$/.test(s))
+        return true;
+    // `-` `?` `:` only start a plain scalar safely when NOT followed by a space.
+    if (/^[-?:](\s|$)/.test(s))
+        return true;
+    return false;
+}
 function reconstructFrontmatter(obj) {
     const lines = [];
     for (const [key, value] of Object.entries(obj)) {
@@ -141,7 +184,7 @@ function reconstructFrontmatter(obj) {
             else {
                 lines.push(`${key}:`);
                 for (const item of value) {
-                    lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+                    lines.push(`  - ${typeof item === 'string' && (item.includes(':') || item.includes('#') || scalarNeedsDoubleQuoting(item)) ? `"${escapeDoubleQuoted(item)}"` : item}`);
                 }
             }
         }
@@ -160,7 +203,7 @@ function reconstructFrontmatter(obj) {
                     else {
                         lines.push(`  ${subkey}:`);
                         for (const item of subval) {
-                            lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#')) ? `"${item}"` : item}`);
+                            lines.push(`    - ${typeof item === 'string' && (item.includes(':') || item.includes('#') || scalarNeedsDoubleQuoting(item)) ? `"${escapeDoubleQuoted(item)}"` : item}`);
                         }
                     }
                 }
@@ -189,14 +232,14 @@ function reconstructFrontmatter(obj) {
                 else {
                     // eslint-disable-next-line @typescript-eslint/no-base-to-string
                     const sv = String(subval);
-                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') ? `"${sv}"` : sv}`);
+                    lines.push(`  ${subkey}: ${sv.includes(':') || sv.includes('#') || scalarNeedsDoubleQuoting(sv) ? `"${escapeDoubleQuoted(sv)}"` : sv}`);
                 }
             }
         }
         else {
             const sv = String(value);
-            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{')) {
-                lines.push(`${key}: "${sv}"`);
+            if (sv.includes(':') || sv.includes('#') || sv.startsWith('[') || sv.startsWith('{') || scalarNeedsDoubleQuoting(sv)) {
+                lines.push(`${key}: "${escapeDoubleQuoted(sv)}"`);
             }
             else {
                 lines.push(`${key}: ${sv}`);
@@ -448,7 +491,11 @@ function parseMustHavesBlock(content, blockName) {
             else {
                 const kvMatch = trimmed.match(/^(\w+):\s*"?([^"]*)"?\s*$/);
                 if (kvMatch) {
-                    const val = kvMatch[2];
+                    // Trim: a quoted value like `"backstop "` captures the inner trailing space in group 2.
+                    // Left untrimmed, a hand-authored `must_haves` marker degrades (a `backstop` truth silently
+                    // grades green instead of abstaining — #1905, the #1154 false-pass; also the sibling
+                    // check_target/violationFixture path). Whitespace is never semantic in a scalar KV value.
+                    const val = kvMatch[2].trim();
                     // Try to parse as number
                     (current)[kvMatch[1]] = /^\d+$/.test(val) ? parseInt(val, 10) : val;
                 }

package/gsd-core/bin/lib/gate-predicate-evaluator.cjs

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Gate Predicate Evaluator — issue #2008 / ADR-2008
+ *
+ * Pure, deps-injected evaluator for capability gate `check.predicate` blocks.
+ *
+ * Background: the loop-resolver renders active gate hooks (carrying their
+ * `check.predicate` declarations) but, prior to #2008, nothing EVALUATED a
+ * declared predicate for non-built-in capabilities — `check.query` was the only
+ * enforced shape (dispatched via `gsd_run check <query>`), and `check.predicate`
+ * was declaration-only. This module is the generic evaluation path.
+ *
+ * The workflow gate-dispatch calls this evaluator (via the `gsd_run check predicate`
+ * subcommand in check-command-router) for any gate whose `check` carries a
+ * `predicate` instead of a `query`. The evaluator dispatches by `predicate.kind`
+ * and returns the existing `{ block, message }` gate contract. A THROWN error
+ * (malformed predicate / unknown kind) is mapped by the CLI wrapper to a
+ * non-zero check-command exit, which the workflow's two-step gate contract treats
+ * as a step-1 command failure (routed per the gate's `onError`).
+ *
+ * Built-in kind (v1): `command-exit-zero` — run a declared command in a bounded
+ * `sh -c` subprocess at the project root, inheriting the process env; exit 0 =>
+ * pass, non-zero => block, timeout => block. The production runBoundedShell
+ * binding is shell-command-projection.execTool (bounded spawnSync). See ADR-2008
+ * for the full sandbox contract.
+ *
+ * This is a leaf pure module: no fs, no child_process, no config — the subprocess
+ * seam is injected so the evaluator is trivially testable without spawning.
+ */
+// ─── Public constants ─────────────────────────────────────────────────────────
+/** Default command timeout for `command-exit-zero` (30s). Matches execTool default. */
+const COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS = 30_000;
+/** Hard cap on the stderr/stdout tail embedded in the gate `message`. */
+const COMMAND_MAX_OUTPUT_CHARS = 2000;
+/** Hard cap on the declared command length (defense-in-depth against ARGV overflow / abuse). */
+const COMMAND_MAX_LENGTH = 4096;
+/** Predicate kinds this evaluator recognises (extensible — add to KIND_TABLE). */
+const EVALUATOR_KINDS = Object.freeze(['command-exit-zero']);
+/** Placeholders interpolated into a declared command, in addition to sh's own vars. */
+const INTERPOLATION_VAR_NAMES = Object.freeze(['PHASE_NUMBER', 'PHASE_DIR', 'PHASE_REQ_IDS']);
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const INTERPOLATION_RE = /\$\{(PHASE_NUMBER|PHASE_DIR|PHASE_REQ_IDS)\}/g;
+/** Replace the three known ${PHASE_*} placeholders with context values (undefined => ''). */
+function interpolate(command, ctx) {
+    return command.replace(INTERPOLATION_RE, (_whole, name) => {
+        if (name === 'PHASE_NUMBER')
+            return ctx.phaseNumber ?? '';
+        if (name === 'PHASE_DIR')
+            return ctx.phaseDir ?? '';
+        if (name === 'PHASE_REQ_IDS')
+            return ctx.phaseReqIds ?? '';
+        return '';
+    });
+}
+/** Cap a string at COMMAND_MAX_OUTPUT_CHARS so gate messages stay context-bounded. */
+function trimToMax(s) {
+    return s.length > COMMAND_MAX_OUTPUT_CHARS ? s.slice(0, COMMAND_MAX_OUTPUT_CHARS) : s;
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+// ─── Kind: command-exit-zero ──────────────────────────────────────────────────
+function evaluateCommandExitZero(predicate, ctx, deps) {
+    const command = predicate['command'];
+    if (!isNonEmptyString(command)) {
+        throw new Error('command-exit-zero predicate requires a non-empty string "command"');
+    }
+    if (command.length > COMMAND_MAX_LENGTH) {
+        throw new Error(`command-exit-zero predicate "command" exceeds max length ${COMMAND_MAX_LENGTH}`);
+    }
+    let timeoutMs = COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS;
+    const rawTimeout = predicate['timeout'];
+    if (rawTimeout !== undefined) {
+        if (typeof rawTimeout !== 'number' || !Number.isFinite(rawTimeout) || rawTimeout <= 0) {
+            throw new Error('command-exit-zero predicate "timeout" must be a positive finite number (seconds)');
+        }
+        timeoutMs = Math.floor(rawTimeout * 1000);
+    }
+    const interpolated = interpolate(command, ctx);
+    const res = deps.runBoundedShell({ command: interpolated, cwd: ctx.cwd, timeoutMs });
+    if (res.timedOut) {
+        return {
+            block: true,
+            message: trimToMax(`command timed out after ${Math.round(timeoutMs / 1000)}s: ${res.stderr || interpolated}`),
+            details: { kind: 'command-exit-zero', timedOut: true, signal: res.signal },
+        };
+    }
+    if (res.exitCode === 0) {
+        return {
+            block: false,
+            message: 'command exited 0',
+            details: { kind: 'command-exit-zero', exitCode: 0 },
+        };
+    }
+    // Non-zero (incl. null exit from a signal kill) => block. Surface code + stderr/stdout tail.
+    const code = res.exitCode === null ? '<none>' : String(res.exitCode);
+    const tail = trimToMax(res.stderr || res.stdout || '');
+    const message = tail ? `command exited ${code}: ${tail}` : `command exited ${code}`;
+    return {
+        block: true,
+        message: trimToMax(message),
+        details: { kind: 'command-exit-zero', exitCode: res.exitCode, signal: res.signal },
+    };
+}
+// ─── Kind dispatch table ──────────────────────────────────────────────────────
+const KIND_TABLE = {
+    'command-exit-zero': evaluateCommandExitZero,
+};
+// ─── Public entry point ───────────────────────────────────────────────────────
+/**
+ * Evaluate a capability gate `check.predicate`.
+ *
+ * Returns `{ block, message }` for any successfully-recognised predicate.
+ * THROWS for a malformed predicate, missing context/deps, or unknown `kind` —
+ * the CLI wrapper converts a throw into a non-zero check-command exit so the
+ * workflow's `onError` (step-1) contract applies. This keeps the gate fail-closed
+ * without conflating an evaluator bug with a legitimate gate-block decision.
+ */
+function evaluatePredicate(predicate, context, deps) {
+    if (!predicate || typeof predicate !== 'object' || Array.isArray(predicate)) {
+        throw new Error('predicate must be an object');
+    }
+    const ctx = context;
+    if (!ctx || typeof ctx.cwd !== 'string' || ctx.cwd.length === 0) {
+        throw new Error('predicate context requires a non-empty "cwd"');
+    }
+    const d = deps;
+    if (!d || typeof d.runBoundedShell !== 'function') {
+        throw new Error('predicate deps require a "runBoundedShell" function');
+    }
+    const pred = predicate;
+    const kind = pred['kind'];
+    if (typeof kind !== 'string' || kind.length === 0) {
+        throw new Error('predicate.kind must be a non-empty string');
+    }
+    const handler = KIND_TABLE[kind];
+    if (!handler) {
+        throw new Error(`Unknown predicate kind: "${kind}". Known kinds: ${EVALUATOR_KINDS.join(', ')}`);
+    }
+    return handler(pred, ctx, d);
+}
+module.exports = {
+    evaluatePredicate,
+    evaluateCommandExitZero,
+    interpolate,
+    COMMAND_EXIT_ZERO_DEFAULT_TIMEOUT_MS,
+    COMMAND_MAX_OUTPUT_CHARS,
+    COMMAND_MAX_LENGTH,
+    EVALUATOR_KINDS,
+    INTERPOLATION_VAR_NAMES,
+};

package/gsd-core/bin/lib/graphify.cjs

@@ -261,6 +261,29 @@ function countCommitsBetween(cwd, from, to) {
     const n = parseInt(r.stdout.trim(), 10);
     return Number.isFinite(n) ? n : null;
 }
+// ─── Graph location resolution (#1825) ───────────────────────────────────────
+//
+// `graphify.graph_path` (in .planning/config.json) lets one umbrella-level graph
+// serve multiple sibling projects without a per-project mirror. When set, query /
+// status / diff read the configured graph, and the diff snapshot travels with it
+// (alongside graph.json). When unset/blank/non-string, behaviour is byte-identical
+// to the historical `<planningDir>/graphs/graph.json`.
+const GRAPH_FILENAME = 'graph.json';
+const SNAPSHOT_FILENAME = '.last-build-snapshot.json';
+/**
+ * Resolve the absolute graph.json location. Honors `graphify.graph_path` in
+ * config.json (resolved relative to the project root, `cwd`); falls back to the
+ * default `<planningDir>/graphs/graph.json` when unset/blank/non-string.
+ */
+function resolveGraphLocation(cwd, planningDir) {
+    const config = safeReadJson(node_path_1.default.join(planningDir, 'config.json'));
+    const graphify = (config && config['graphify']);
+    const configuredValue = graphify && graphify['graph_path'];
+    if (typeof configuredValue === 'string' && configuredValue.trim().length > 0) {
+        return { graphPath: node_path_1.default.resolve(cwd, configuredValue), configured: true };
+    }
+    return { graphPath: node_path_1.default.join(planningDir, 'graphs', GRAPH_FILENAME), configured: false };
+}
 /**
  * Query the knowledge graph for nodes matching a term, with optional budget cap.
  * Uses seed-then-expand BFS traversal (D-01).
@@ -269,9 +292,11 @@ function graphifyQuery(cwd, term, options = {}) {
     const planningDir = node_path_1.default.join(cwd, '.planning');
     if (!isCapabilityActive('graphify', cwd))
         return disabledResponse();
-    const graphPath = node_path_1.default.join(planningDir, 'graphs', 'graph.json');
+    const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { error: 'No graph built yet. Run graphify build first.' };
+        return { error: configured
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                : 'No graph built yet. Run graphify build first.' };
     }
     const graph = safeReadJson(graphPath);
     if (!graph) {
@@ -303,9 +328,11 @@ function graphifyStatus(cwd) {
     const planningDir = node_path_1.default.join(cwd, '.planning');
     if (!isCapabilityActive('graphify', cwd))
         return disabledResponse();
-    const graphPath = node_path_1.default.join(planningDir, 'graphs', 'graph.json');
+    const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { exists: false, message: 'No graph built yet. Run graphify build to create one.' };
+        return { exists: false, message: configured
+                ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
+                : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);
     const graph = safeReadJson(graphPath);
@@ -360,8 +387,8 @@ function graphifyDiff(cwd) {
     const planningDir = node_path_1.default.join(cwd, '.planning');
     if (!isCapabilityActive('graphify', cwd))
         return disabledResponse();
-    const snapshotPath = node_path_1.default.join(planningDir, 'graphs', '.last-build-snapshot.json');
-    const graphPath = node_path_1.default.join(planningDir, 'graphs', 'graph.json');
+    const { graphPath } = resolveGraphLocation(cwd, planningDir);
+    const snapshotPath = node_path_1.default.join(node_path_1.default.dirname(graphPath), SNAPSHOT_FILENAME);
     if (!node_fs_1.default.existsSync(snapshotPath)) {
         return { no_baseline: true, message: 'No previous snapshot. Run graphify build first, then build again to generate a diff baseline.' };
     }
@@ -405,7 +432,11 @@ function graphifyBuild(cwd) {
     if (!installed.installed)
         return { error: installed.message };
     const version = checkGraphifyVersion();
-    // Ensure output directory exists (D-05)
+    // Ensure output directory exists (D-05). Build stays project-scoped: the build
+    // skill cp's artifacts into `<planningDir>/graphs/` regardless of graph_path, so
+    // graphs_dir reflects that real destination (not the configured read location).
+    // A shared umbrella graph is built in the umbrella project; sub-projects only
+    // READ it via graphify.graph_path (#1825).
     const graphsDir = node_path_1.default.join(planningDir, 'graphs');
     node_fs_1.default.mkdirSync(graphsDir, { recursive: true });
     // Read build timeout from config -- default 300s per D-02
@@ -428,7 +459,8 @@ function graphifyBuild(cwd) {
  * using platformWriteSync for crash safety.
  */
 function writeSnapshot(cwd) {
-    const graphPath = node_path_1.default.join(cwd, '.planning', 'graphs', 'graph.json');
+    const planningDir = node_path_1.default.join(cwd, '.planning');
+    const { graphPath } = resolveGraphLocation(cwd, planningDir);
     const graph = safeReadJson(graphPath);
     if (!graph)
         return { error: 'Cannot write snapshot: graph.json not parseable' };
@@ -438,7 +470,7 @@ function writeSnapshot(cwd) {
         nodes: graph.nodes || [],
         edges: graph.edges || graph.links || [],
     };
-    const snapshotPath = node_path_1.default.join(cwd, '.planning', 'graphs', '.last-build-snapshot.json');
+    const snapshotPath = node_path_1.default.join(node_path_1.default.dirname(graphPath), SNAPSHOT_FILENAME);
     (0, shell_command_projection_cjs_1.platformWriteSync)(snapshotPath, JSON.stringify(snapshot, null, 2));
     return {
         saved: true,

package/gsd-core/bin/lib/handshake-serialized.cjs

@@ -0,0 +1,70 @@
+/**
+ * Serialized (out-of-process) capability-exchange handshake (ADR-1239 Phase E / #1683).
+ *
+ * Phase 1's `negotiateHostCapabilities` is IN-PROCESS (a host descriptor merged
+ * directly into the engine). Out-of-process SDK hosts (pi, VS Code) cannot share
+ * object references with the engine — they exchange a SERIALIZED capability set
+ * over a wire boundary (an MCP-style `initialize`). This module is the wire form
+ * of that handshake, kept CONSISTENT with the in-process negotiation: a request
+ * built + serialized here MUST yield the same NegotiationResult the in-process
+ * call produces for the same axes (asserted in tests/handshake-serialized.test.cjs).
+ *
+ * Wire shape (JSON — no object refs, safe across a process/IPC boundary):
+ *
+ *   request  = { protocolVersion: number, axes: Partial<HostIntegrationAxes> }
+ *   response = NegotiationResult = { protocolVersion, effective, points, warnings }
+ *
+ * The engine side delegates to negotiateHostCapabilities; the host side builds
+ * the request from a descriptor. Both round-trip through JSON so the exchange is
+ * strictly serializable (a non-JSON-safe value would break the wire contract).
+ *
+ * Pure + additive: no I/O, no global state. The companion MCP server (Phase 4)
+ * or an SDK host binds this to a real transport.
+ */
+'use strict';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hostIntegration = require("./host-integration.cjs");
+/** The wire method name for the initialize-style exchange. */
+const HANDSHAKE_METHOD = 'gsd/host-initialize';
+/**
+ * Host side: build a JSON-serializable handshake request from a host descriptor.
+ * Accepts either `{ protocolVersion?, axes }` or a bare axes object.
+ * Defaults protocolVersion to the engine's current PROTOCOL_VERSION.
+ */
+function buildHandshakeRequest(hostDescriptor) {
+    if (!hostDescriptor || typeof hostDescriptor !== 'object') {
+        throw new TypeError('buildHandshakeRequest: host descriptor (object) is required');
+    }
+    const desc = hostDescriptor;
+    const hasAxes = Object.prototype.hasOwnProperty.call(desc, 'axes');
+    const axes = (hasAxes ? desc.axes : desc);
+    if (!axes || typeof axes !== 'object') {
+        throw new TypeError('buildHandshakeRequest: descriptor.axes (object) is required');
+    }
+    const protocolVersion = typeof desc.protocolVersion === 'number' && Number.isFinite(desc.protocolVersion)
+        ? desc.protocolVersion
+        : hostIntegration.PROTOCOL_VERSION;
+    // Force a wire round-trip so a non-JSON-safe descriptor fails HERE, not later.
+    return JSON.parse(JSON.stringify({ protocolVersion, axes }));
+}
+/**
+ * Engine side: handle a serialized handshake request → a JSON-serializable
+ * NegotiationResult. Delegates to negotiateHostCapabilities, so the result is
+ * identical to the in-process negotiation for the same axes.
+ */
+function handleHandshakeRequest(request, engine = hostIntegration.DEFAULT_ENGINE) {
+    if (!request || typeof request !== 'object') {
+        throw new TypeError('handleHandshakeRequest: request (object) is required');
+    }
+    const req = request;
+    const axes = (req.axes && typeof req.axes === 'object' ? req.axes : {});
+    const protocolVersion = req.protocolVersion;
+    const result = hostIntegration.negotiateHostCapabilities({ ...axes, ...(typeof protocolVersion === 'number' && Number.isFinite(protocolVersion) ? { protocolVersion } : {}) }, engine);
+    // Force a wire round-trip: the response must be strictly JSON-serializable.
+    return JSON.parse(JSON.stringify(result));
+}
+module.exports = {
+    HANDSHAKE_METHOD,
+    buildHandshakeRequest,
+    handleHandshakeRequest,
+};

package/gsd-core/bin/lib/host-integration-sdk.cjs

@@ -0,0 +1,53 @@
+/**
+ * Host-Integration SDK — the published public surface (ADR-1239 Phase E / #1683).
+ *
+ * External host-plugin authors import ONLY from this entry. It IS the contract:
+ * everything it re-exports is public + versioned (PROTOCOL_VERSION governs the
+ * set); everything else in gsd-core is internal. An SDK smoke test
+ * (tests/sdk-smoke.test.cjs) builds a new host-plugin against this surface only
+ * — proving an external author can wire a host without reading gsd-core internals.
+ *
+ * Surface: the negotiated schema + classification, the five adapters
+ * (declarative/imperative/model/hook/state), and the serialized handshake.
+ * Frozen so the public shape cannot be mutated by consumers.
+ */
+'use strict';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hostIntegration = require("./host-integration.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const adapterDeclarative = require("./adapter-declarative.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const adapterImperative = require("./adapter-imperative.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const modelAdapter = require("./model-adapter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hookBus = require("./hook-bus.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateIo = require("./state-io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const handshake = require("./handshake-serialized.cjs");
+const SDK = Object.freeze({
+    // ── Schema + protocol version ────────────────────────────────────────────
+    PROTOCOL_VERSION: hostIntegration.PROTOCOL_VERSION,
+    HOST_INTEGRATION_AXES: hostIntegration.HOST_INTEGRATION_AXES,
+    INTERFACE_POINTS: hostIntegration.INTERFACE_POINTS,
+    PROFILE_BASELINES: hostIntegration.PROFILE_BASELINES,
+    // ── Negotiation + classification ─────────────────────────────────────────
+    negotiateHostCapabilities: hostIntegration.negotiateHostCapabilities,
+    profileOf: hostIntegration.profileOf,
+    degradationFor: hostIntegration.degradationFor,
+    hookEventSurfaceFor: hostIntegration.hookEventSurfaceFor,
+    extensionEventSurfaceFor: hostIntegration.extensionEventSurfaceFor,
+    shouldFlattenDispatch: hostIntegration.shouldFlattenDispatch,
+    // ── Embedding + engine adapters ──────────────────────────────────────────
+    createDeclarativeAdapter: adapterDeclarative.createDeclarativeAdapter,
+    createImperativeAdapter: adapterImperative.createImperativeAdapter,
+    createModelAdapter: modelAdapter.createModelAdapter,
+    createHookBus: hookBus.createHookBus,
+    createStateIO: stateIo.createStateIO,
+    // ── Serialized handshake (out-of-process SDK hosts: pi / VS Code) ─────────
+    HANDSHAKE_METHOD: handshake.HANDSHAKE_METHOD,
+    buildHandshakeRequest: handshake.buildHandshakeRequest,
+    handleHandshakeRequest: handshake.handleHandshakeRequest,
+});
+module.exports = SDK;

package/gsd-core/bin/lib/host-integration.cjs

@@ -394,6 +394,63 @@ function shouldFlattenDispatch(dispatch) {
     const canBackground = dispatch.background === true && dispatch.backgroundDispatch === true;
     return !canBackground;
 }
+// ---------------------------------------------------------------------------
+// Managed-hook event surface per hookEvents dialect (ADR-1239 / ADR-1016)
+// ---------------------------------------------------------------------------
+// Host-fireable MANAGED-hook events per `hookEvents` dialect. `hookEvents` is the
+// managed-hook dialect — the event names GSD writes into a DECLARATIVE host's
+// settings.json (claude = SessionStart/PreToolUse/…; gemini = BeforeTool/AfterTool).
+// This is DISTINCT from the extension-system event surface (below): a host's
+// plugin/extension API fires a different, plugin-owned event set. The two must
+// not be conflated (ADR-1239 amendment / #1943 — the former 'opencode-subset'
+// `hookEvents` value was this conflation; it is now `extensionEvents: opencode`).
+const HOOK_EVENT_SURFACES = Object.freeze({
+    claude: Object.freeze(['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop', 'SessionEnd', 'PreCompact']),
+    gemini: Object.freeze(['SessionStart', 'BeforeTool', 'AfterTool', 'SessionEnd']),
+});
+/**
+ * Resolve the managed-hook event surface for a `hookEvents` dialect.
+ * Returns null for unknown/missing dialects (fail-closed). Pure, never throws.
+ */
+function hookEventSurfaceFor(hookEvents) {
+    if (typeof hookEvents !== 'string')
+        return null;
+    return HOOK_EVENT_SURFACES[hookEvents] || null;
+}
+// ---------------------------------------------------------------------------
+// Extension-system event surface (ADR-1239 amendment / #1943)
+// ---------------------------------------------------------------------------
+// The events a host's PLUGIN/EXTENSION API exposes — for imperative-embedding
+// hosts that load GSD as a plugin. This is a SEPARATE vocabulary + descriptor
+// field (`extensionEvents`) from `hookEvents`: hookEvents = the managed-hook
+// dialect (declarative hosts' settings.json); extensionEvents = the plugin-owned
+// event subset (imperative hosts' extension API). They are not the same thing.
+//
+// Values are documentation-sourced (ADR-1239 §research): OpenCode ~25 plugin
+// events (session/tool/file/permission); pi ~30 fine-grained extension events;
+// 'none' = the host exposes no extension surface and the engine owns the bus
+// (VS Code). Declarative hosts (no plugin API) do not set `extensionEvents`.
+const EXTENSION_EVENT_SURFACES = Object.freeze({
+    opencode: Object.freeze([
+        'session.created', 'session.idle', 'experimental.session.compacting',
+        'tool.execute.before', 'tool.execute.after', 'file.edited',
+    ]),
+    pi: Object.freeze(['tool_call']),
+    none: Object.freeze([]),
+});
+/**
+ * Resolve the extension-system event surface for an `extensionEvents` dialect.
+ * Returns null for unknown/missing dialects (fail-closed). Pure, never throws.
+ *
+ * A non-null result is what makes an `extensionEvents` value a CONSUMED value
+ * rather than reserved vocab. For 'opencode' it carries NO workflow-phase events
+ * — the engine owns phase sequencing internally on such hosts (ADR-1239 §OpenCode).
+ */
+function extensionEventSurfaceFor(extensionEvents) {
+    if (typeof extensionEvents !== 'string')
+        return null;
+    return EXTENSION_EVENT_SURFACES[extensionEvents] || null;
+}
 module.exports = {
     PROTOCOL_VERSION,
     UNDOCUMENTED,
@@ -401,8 +458,12 @@ module.exports = {
     INTERFACE_POINTS,
     PROFILE_BASELINES,
     DEFAULT_ENGINE,
+    HOOK_EVENT_SURFACES,
+    EXTENSION_EVENT_SURFACES,
     degradationFor,
     profileOf,
     negotiateHostCapabilities,
     shouldFlattenDispatch,
+    hookEventSurfaceFor,
+    extensionEventSurfaceFor,
 };

package/gsd-core/bin/lib/init.cjs

@@ -60,9 +60,9 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { findPhaseInternal } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { normalizePhaseName, phaseTokenMatches } = phaseId;
+const { normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
-const { planningPaths, planningDir, planningRoot, findContextMdIn, } = planningWorkspace;
+const { planningPaths, planningDir, planningRoot, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
 const { extractFrontmatter } = frontmatterMod;
 const { readVerificationStatus } = verificationMod;
@@ -919,9 +919,12 @@ function cmdInitMilestoneOp(cwd, raw) {
         const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
         const roadmapRaw = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const currentSection = extractCurrentMilestone(roadmapRaw, cwd);
-        const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
+        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:/gi;
         let m;
         while ((m = phasePattern.exec(currentSection)) !== null) {
+            if (/^999(?:\.|$)/.test(m[1]))
+                continue;
             roadmapPhaseNumbers.push(m[1]);
         }
     }
@@ -938,7 +941,7 @@ function cmdInitMilestoneOp(cwd, raw) {
         for (const e of entries) {
             if (!e.isDirectory())
                 continue;
-            const m = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/);
+            const m = stripProjectCodePrefix(e.name).match(/^(\d+[A-Z]?(?:\.\d+)*)/);
             if (!m)
                 continue;
             diskPhaseDirs.set(canonicalizePhase(m[1]), e.name);
@@ -1071,7 +1074,8 @@ function cmdInitManager(cwd, raw) {
     while ((_cbMatch = _cbPattern.exec(content)) !== null) {
         _checkboxStates.set(_cbMatch[2], _cbMatch[1].toLowerCase() === 'x');
     }
-    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
     const phases = [];
     let match;
     while ((match = phasePattern.exec(content)) !== null) {
@@ -1355,6 +1359,29 @@ function cmdInitProgress(cwd, raw) {
     const config = loadConfig(cwd);
     const milestone = getMilestoneInfo(cwd);
     const _slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
+    // #1912: fail safe in workstream mode with no active workstream. With no active
+    // workstream and no --ws, planningDir(cwd) resolves to root .planning — silently
+    // reporting a stale root milestone. Require an explicit workstream instead.
+    // Mirror planningDir's resolution (GSD_WORKSTREAM env > stored active pointer) so
+    // an explicit --ws (which sets GSD_WORKSTREAM) satisfies the check.
+    const _wsRoot = node_path_1.default.join(planningRoot(cwd), 'workstreams');
+    let _availableWorkstreams = [];
+    try {
+        _availableWorkstreams = node_fs_1.default
+            .readdirSync(_wsRoot, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        /* no workstreams dir → flat mode */
+    }
+    const _resolvedWorkstream = process.env['GSD_WORKSTREAM'] || getActiveWorkstream(cwd);
+    if (_availableWorkstreams.length > 0 && !_resolvedWorkstream) {
+        error(`init.progress requires a workstream in workstream mode — no active workstream is set, so root STATE.md (likely stale) would be reported. ` +
+            `Pass --ws <name> or run ${(0, runtime_slash_cjs_1.formatGsdSlash)('workstream set', _slashRuntime)} first. ` +
+            `Available workstreams: ${_availableWorkstreams.join(', ')}`);
+    }
     const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
     const phases = [];
     let currentPhase = null;
@@ -1364,7 +1391,8 @@ function cmdInitProgress(cwd, raw) {
     const roadmapCheckboxStates = new Map();
     try {
         const roadmapContent = extractCurrentMilestone(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd);
-        const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
         let hm;
         while ((hm = headingPattern.exec(roadmapContent)) !== null) {
             roadmapPhaseNums.add(hm[1]);