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

package/gsd-core/bin/lib/edge-probe.cjs

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Spec-completeness edge-probe — the FIRST adapter of the probe-core resolution model
+ * (ADR-457 build model; ADR-550 Decision 7 seam).
+ *
+ * The generic resolution lifecycle, the status×verification re-cut, `validateResolution`,
+ * `validateRequirement`, the `analyzeCoverage` merge/rollup/orphan-reject engine, and the
+ * `runProbeCli` scaffold all live in `src/probe-core.cts`. This module keeps ONLY the
+ * edge-specific cluster: the five data/behavior shapes, the closed 8-category edge taxonomy,
+ * shape classification, edge proposal, and the `{ explicit, backstop }` verification validators.
+ *
+ * Authored as strict TypeScript (`src/edge-probe.cts`) and compiled by
+ * `tsc -p tsconfig.build.json` to the gitignored runtime artifact
+ * `gsd-core/bin/lib/edge-probe.cjs`. Do NOT hand-write the `.cjs`; it is emitted. Tests
+ * `require()` the built artifact; `pretest` runs `build:lib` first.
+ *
+ * Pure and dependency-free: it classifies each requirement's data/behavior shape, filters
+ * the closed 8-category edge taxonomy to applicable categories, proposes concrete candidate
+ * edges, and (via probe-core) merges author resolutions into a coverage report.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EDGE_VALIDATORS = exports.TAXONOMY = exports.VALID_SHAPES = exports.SHAPE_CUES = void 0;
+exports.classifyShape = classifyShape;
+exports.applicableCategories = applicableCategories;
+exports.validateRequirement = validateRequirement;
+exports.validateResolution = validateResolution;
+exports.proposeEdges = proposeEdges;
+exports.analyzeCoverage = analyzeCoverage;
+const probe_core_cjs_1 = require("./probe-core.cjs");
+/**
+ * Word-boundary cues mapping requirement prose -> data/behavior shape.
+ * Heuristic and intentionally lossy; an authored `shapes` array overrides it.
+ */
+exports.SHAPE_CUES = {
+    'numeric-range': /\b(round(ing|ed)?|threshold|max(imum)?|min(imum)?|limit|bound(ary)?|between|cap|percent|amount|price|count|number|score|rate|decimal)\b/i,
+    'collection': /\b(lists?|arrays?|sets?|items?|collections?|each|every|all|sort(ed|ing)?|merge|dedupe|group|ranges?|intervals?|overlap(ping)?)\b/i,
+    'text': /\b(string|text|names?|labels?|truncate|substring|char(acter)?s?|length|slug|message|unicode)\b/i,
+    'stateful': /\b(save|persist|store|update|toggle|create|delete|remove|submit|retry|apply|register|insert)\b/i,
+    'io': /\b(files?|requests?|fetch|upload|download|network|api|endpoints?|connections?|sockets?)\b/i,
+};
+/** The locked shape vocabulary — exactly the keys of SHAPE_CUES (single source of truth). */
+exports.VALID_SHAPES = new Set(Object.keys(exports.SHAPE_CUES));
+/** Detect which shapes a requirement's prose matches (heuristic). */
+function classifyShape(text) {
+    const shapes = [];
+    const subject = String(text == null ? '' : text);
+    for (const shape of Object.keys(exports.SHAPE_CUES)) {
+        if (exports.SHAPE_CUES[shape].test(subject))
+            shapes.push(shape);
+    }
+    return shapes;
+}
+/**
+ * Closed taxonomy of 8 domain-boundary edge categories (established QA names).
+ * `shapes` lists which requirement shapes make the category relevant.
+ */
+exports.TAXONOMY = [
+    { id: 'boundary', name: 'Boundary values', shapes: ['numeric-range'], probe: 'What happens exactly at each min/max/threshold — and one step either side?' },
+    { id: 'adjacency', name: 'Adjacency / touching', shapes: ['collection'], probe: 'When two things are exactly equal or just touch, do they merge, collide, or separate?' },
+    { id: 'empty', name: 'Empty / degenerate', shapes: ['collection', 'text'], probe: 'What is the result for empty, single-element, or null input?' },
+    { id: 'encoding', name: 'Encoding / representation', shapes: ['text'], probe: 'Whose definition of length/equality applies — bytes, code points, grapheme clusters, or normalized form?' },
+    { id: 'ordering', name: 'Ordering / stability', shapes: ['collection'], probe: 'When elements compare equal, is output order specified and stable?' },
+    { id: 'precision', name: 'Precision / overflow', shapes: ['numeric-range'], probe: 'Where can precision loss, overflow, or rounding/tie-breaking occur — and what is the exact contract (e.g. half-up vs half-to-even, ceil/floor/truncate)?' },
+    { id: 'idempotency', name: 'Idempotency / repetition', shapes: ['stateful'], probe: 'What happens if this runs twice on the same input?' },
+    { id: 'concurrency', name: 'Concurrency / effect ordering', shapes: ['stateful', 'io'], probe: 'If interrupted or run in parallel, what is guaranteed?' },
+];
+/** Return taxonomy category ids whose applicable shapes intersect the input set. */
+function applicableCategories(shapes) {
+    const set = new Set(shapes);
+    return exports.TAXONOMY.filter((c) => c.shapes.some((s) => set.has(s))).map((c) => c.id);
+}
+/**
+ * The edge adapter's injected runtime validators (ADR-550 #5). `categories` is the closed
+ * taxonomy; both verification tiers require a non-empty `resolution` (an explicit AC's text
+ * or a backstop note) so plan-phase has a criterion to lift.
+ */
+exports.EDGE_VALIDATORS = {
+    categories: exports.TAXONOMY.map((c) => c.id),
+    verification: ['explicit', 'backstop'],
+    requiredFieldsByVerification: { explicit: ['resolution'], backstop: ['resolution'] },
+};
+/**
+ * Validate a single requirement — the generic id/text checks (probe-core) plus the edge's
+ * `shapes`-must-be-an-array check. A bare string like `shapes:"numeric-range"` would otherwise
+ * fall through to prose classification, silently ignoring the authored override.
+ *
+ * The edge adapter's `text` is REQUIRED (the prose is the classification signal), so reject a
+ * missing/empty `text` when no authored `shapes` override is present. Without this, a `{ id }`
+ * requirement classifies to zero shapes → zero edges → it is silently DROPPED from coverage
+ * with no signal — the exact fail-open this feature exists to eliminate. An explicit `shapes`
+ * array (including `[]` for "no applicable categories") is the legitimate way to opt out of
+ * prose classification, so `text` is only required when `shapes` is absent.
+ */
+function validateRequirement(requirement) {
+    (0, probe_core_cjs_1.validateRequirement)(requirement);
+    const r = requirement;
+    if (r.shapes != null && !Array.isArray(r.shapes)) {
+        throw new Error(`requirement ${requirement.id} shapes must be an array when present`);
+    }
+    if (r.shapes == null && !(typeof r.text === 'string' && r.text.trim())) {
+        throw new Error(`requirement ${requirement.id} text must be a non-empty string when no shapes override is provided`);
+    }
+}
+/** Validate an edge resolution against the edge verification vocabulary. */
+function validateResolution(resolution) {
+    return (0, probe_core_cjs_1.validateResolution)(resolution, exports.EDGE_VALIDATORS);
+}
+/**
+ * Propose candidate edges for a requirement. Uses authored `shapes` when present, else
+ * classifies from prose. Every proposed edge starts unresolved (verification null).
+ */
+function proposeEdges(requirement) {
+    validateRequirement(requirement);
+    let shapes;
+    if (Array.isArray(requirement.shapes)) {
+        // Fail closed: an authored array must contain only locked shape values. A non-empty
+        // but invalid array (e.g. ['numeric'], a typo for 'numeric-range') would otherwise
+        // intersect no category and silently suppress every probe — the gate reads green while
+        // nothing was checked. An empty array stays a valid "no applicable categories" override.
+        for (const s of requirement.shapes) {
+            if (typeof s !== 'string' || !exports.VALID_SHAPES.has(s)) {
+                throw new Error(`invalid shape ${JSON.stringify(s)} for requirement ${requirement.id} — must be one of: ${[...exports.VALID_SHAPES].join(', ')}`);
+            }
+        }
+        shapes = requirement.shapes;
+    }
+    else {
+        shapes = classifyShape(requirement.text);
+    }
+    return applicableCategories(shapes).map((catId) => {
+        const cat = exports.TAXONOMY.find((c) => c.id === catId);
+        return {
+            requirement_id: requirement.id,
+            category: catId,
+            status: 'unresolved',
+            verification: null,
+            resolution: null,
+            reason: null,
+            probe: cat ? cat.probe : '',
+        };
+    });
+}
+/**
+ * Propose edges for every requirement (deterministic propose), then delegate the
+ * merge/rollup/orphan-reject to probe-core. Edge-specific pre-checks: requirements must be an
+ * array, requirement ids must be unique. Throws on any invalid resolution.
+ */
+function analyzeCoverage(requirements, resolutions = []) {
+    if (!Array.isArray(requirements)) {
+        throw new Error('requirements must be an array');
+    }
+    const items = [];
+    const seenReqIds = new Set();
+    for (const req of requirements) {
+        validateRequirement(req);
+        if (seenReqIds.has(req.id)) {
+            throw new Error(`duplicate requirement id ${JSON.stringify(req.id)}`);
+        }
+        seenReqIds.add(req.id);
+        for (const edge of proposeEdges(req))
+            items.push(edge);
+    }
+    return (0, probe_core_cjs_1.analyzeCoverage)(items, resolutions, exports.EDGE_VALIDATORS);
+}
+/*
+ * CLI entry (EP-06 invokable surface): `edge-probe.cjs <requirements.json> [resolutions.json]`.
+ * The generic I/O plumbing (parse, fail-closed exit 2, pretty-JSON out) lives in probe-core's
+ * `runProbeCli`; the edge adapter supplies its `analyzeCoverage`. Guarded by
+ * `require.main === module` so it runs only when the compiled `.cjs` is executed directly.
+ */
+if (require.main === module) {
+    (0, probe_core_cjs_1.runProbeCli)((requirements, resolutions) => analyzeCoverage(requirements, resolutions), { usage: 'edge-probe.cjs <requirements.json> [resolutions.json]' });
+}

package/gsd-core/bin/lib/fallow-runner.cjs

@@ -5,6 +5,9 @@
  * ADR-457 build-at-publish: the hand-written bin/lib/fallow-runner.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved
  * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ *
+ * Parses the real fallow `audit --format json` schema (schema_version 3
+ * envelope, nested dead_code/duplication sections). See fallow 2.70.0+.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -13,6 +16,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveFallowBinary = resolveFallowBinary;
 exports.requireFallowBinary = requireFallowBinary;
 exports.normalizeFallowReport = normalizeFallowReport;
+exports.normalizeFallowReportFile = normalizeFallowReportFile;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 function candidateNames() {
@@ -68,48 +72,82 @@ function requireFallowBinary({ cwd, envPath = process.env['PATH'] ?? '' }) {
     throw new Error('Fallow is enabled but no binary was found. Please install fallow via `npm install -D fallow` or `cargo install fallow`.');
 }
 function normalizeFallowReport(report) {
-    const unused = Array.isArray(report?.unusedExports)
-        ? report.unusedExports
-        : [];
-    const duplicates = Array.isArray(report?.duplicates)
-        ? report.duplicates
-        : [];
-    const circular = Array.isArray(report?.circularDependencies)
-        ? report.circularDependencies
-        : [];
+    const deadCodeRaw = report?.dead_code;
+    const duplicationRaw = report?.duplication;
+    const unusedExports = (Array.isArray(deadCodeRaw?.unused_exports)
+        ? (deadCodeRaw?.unused_exports ?? [])
+        : []).filter((x) => x !== null && typeof x === 'object');
+    const unusedFiles = (Array.isArray(deadCodeRaw?.unused_files)
+        ? (deadCodeRaw?.unused_files ?? [])
+        : []).filter((x) => x !== null && typeof x === 'object');
+    const circularDeps = (Array.isArray(deadCodeRaw?.circular_dependencies)
+        ? (deadCodeRaw?.circular_dependencies ?? [])
+        : []).filter((x) => x !== null && typeof x === 'object');
+    const cloneGroups = (Array.isArray(duplicationRaw?.clone_groups)
+        ? (duplicationRaw?.clone_groups ?? [])
+        : []).filter((x) => x !== null && typeof x === 'object');
     const findings = [];
-    for (const item of unused) {
+    for (const item of unusedExports) {
+        if (!item || typeof item !== 'object')
+            continue;
         findings.push({
             type: 'unused_export',
-            message: `Unused export ${item.symbol ?? '<unknown>'}`,
-            file: item.file ?? '',
+            message: `Unused export ${item.export_name ?? '<unknown>'}`,
+            file: item.path ?? '',
             line: item.line ?? null,
         });
     }
-    for (const item of duplicates) {
+    for (const item of unusedFiles) {
+        if (!item || typeof item !== 'object')
+            continue;
         findings.push({
-            type: 'duplicate_block',
-            message: `Duplicate block (${Math.round((item.similarity ?? 0) * 100)}% similarity)`,
-            file: item.left?.file ?? '',
-            line: item.left?.start ?? null,
-            related_file: item.right?.file ?? '',
+            type: 'unused_file',
+            message: `Unused file ${item.path ?? '<unknown>'}`,
+            file: item.path ?? '',
+            line: null,
         });
     }
-    for (const item of circular) {
+    for (const item of circularDeps) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const files = Array.isArray(item.files) ? item.files : [];
         findings.push({
             type: 'circular_dependency',
-            message: `Circular dependency: ${(item.cycle ?? []).join(' -> ')}`,
-            file: Array.isArray(item.cycle) && item.cycle.length > 0 ? item.cycle[0] : '',
-            line: null,
+            message: `Circular dependency: ${files.join(' -> ')}`,
+            file: files.length > 0 ? files[0] : '',
+            line: item.line ?? null,
+        });
+    }
+    for (const group of cloneGroups) {
+        if (!group || typeof group !== 'object')
+            continue;
+        const instances = Array.isArray(group.instances) ? group.instances : [];
+        findings.push({
+            type: 'duplicate_block',
+            message: `Duplicate block (${instances.length} instances)`,
+            file: instances[0]?.file ?? '',
+            line: instances[0]?.start_line ?? null,
+            related_file: instances[1]?.file ?? '',
         });
     }
     return {
         summary: {
-            unused_exports: unused.length,
-            duplicates: duplicates.length,
-            circular_dependencies: circular.length,
+            unused_exports: unusedExports.length,
+            unused_files: unusedFiles.length,
+            duplicates: cloneGroups.length,
+            circular_dependencies: circularDeps.length,
             total: findings.length,
         },
         findings,
     };
 }
+function normalizeFallowReportFile(filePath) {
+    try {
+        const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return normalizeFallowReport(parsed);
+    }
+    catch {
+        return normalizeFallowReport(null);
+    }
+}

package/gsd-core/bin/lib/federated-config.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Federated Config — Defensive merge of capability-declared config keys
+ *
+ * ADR-857 phase 3b: wires the Capability Registry's configSchema into
+ * loadConfig as a provably-empty no-op channel until capability keys are
+ * migrated out of the central config-schema.
+ *
+ * Exported function:
+ *   mergeFederatedConfig({ configSchema, isCentralKey, userConfig })
+ *     → { values, validKeys, warnings }
+ *
+ * Design:
+ *   - For each key in configSchema:
+ *       If isCentralKey(key) → SKIP; push a pending-migration warning.
+ *       Else if slice is malformed → SKIP; push a warning. Never throw.
+ *       Else (valid federated key absent from central):
+ *         resolvedValue = nested userConfig lookup if present & type-matches; else slice.default.
+ *         Add key→resolvedValue to values; add key to validKeys.
+ *   - Guard all object writes with inline literal __proto__/constructor/prototype checks.
+ *   - Zero external dependencies; no ajv; hand-rolled type checks only.
+ *
+ * ADR-857 no-op guarantee:
+ *   With the current registry, every UI key is still present in the central
+ *   config-schema, so isCentralKey() returns true for all of them and values
+ *   is always empty. The channel is live but carries no traffic until a key
+ *   is atomically removed from the central schema (the cutover step).
+ *
+ * Dependencies: none (zero-dep module).
+ */
+// ─── Allowed slice types (mirrors gen-capability-registry.cjs VALID_CONFIG_SLICE_TYPES) ──
+const VALID_SLICE_TYPES = new Set(['boolean', 'string', 'number', 'enum']);
+// ─── Internal helpers ──────────────────────────────────────────────────────────
+/**
+ * Returns true if `slice` has a non-empty type, a `default` property, and a
+ * non-empty string description. Does NOT throw.
+ */
+function _isWellFormedSlice(slice) {
+    if (typeof slice !== 'object' || slice === null || Array.isArray(slice))
+        return false;
+    const s = slice;
+    if (typeof s['type'] !== 'string' || s['type'].length === 0)
+        return false;
+    if (!VALID_SLICE_TYPES.has(s['type']))
+        return false;
+    if (!Object.prototype.hasOwnProperty.call(s, 'default'))
+        return false;
+    return true;
+}
+/**
+ * Returns true if `value` matches the declared type in the slice.
+ * For enum, also validates against slice.values if present.
+ */
+function _typeMatches(value, slice) {
+    switch (slice.type) {
+        case 'boolean': return typeof value === 'boolean';
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number';
+        case 'enum':
+            // Must be a string AND, if values list is present, must be in it
+            if (typeof value !== 'string')
+                return false;
+            if (Array.isArray(slice.values) && slice.values.length > 0) {
+                return slice.values.includes(value);
+            }
+            return true;
+        default: return false;
+    }
+}
+/**
+ * Traverse a dotted key path through a nested config object.
+ * E.g. key="workflow.ui_phase", obj={workflow:{ui_phase:false}} → {found:true, value:false}
+ * Returns {found:false} if any segment is missing or not an own property.
+ * Handles 1, 2, or N segments generically.
+ */
+function _getNestedValue(obj, key) {
+    const segments = key.split('.');
+    let current = obj;
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        // Inline literal prototype-pollution guard
+        if (seg === '__proto__' || seg === 'constructor' || seg === 'prototype') {
+            return { found: false, value: undefined };
+        }
+        if (typeof current !== 'object' || current === null) {
+            return { found: false, value: undefined };
+        }
+        const cur = current;
+        if (!Object.prototype.hasOwnProperty.call(cur, seg)) {
+            return { found: false, value: undefined };
+        }
+        current = cur[seg];
+    }
+    return { found: true, value: current };
+}
+// ─── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Defensive merge of capability-declared config slices into the loadConfig
+ * return value.
+ *
+ * DEFENSIVE contract (never throws, even on bad capability data):
+ *   - Null/undefined/non-object input → returns empty result.
+ *   - Null/undefined/non-object userConfig → treated as {} (no overrides).
+ *   - Central keys are skipped with a pending-migration warning.
+ *   - Malformed slices are skipped with a warning.
+ *   - User-supplied values with wrong types (or out-of-enum values) fall back
+ *     to the slice default (a type-mismatch warning is pushed but the key is
+ *     still federated with its default; this is best-effort degraded operation).
+ */
+function mergeFederatedConfig(input) {
+    // FIX 4: Guard null/undefined/non-object input
+    if (input === null || input === undefined || typeof input !== 'object') {
+        return { values: Object.create(null), validKeys: [], warnings: [] };
+    }
+    const { configSchema, isCentralKey } = input;
+    // FIX 4: Guard null/undefined/non-object userConfig — treat as {}
+    const userConfig = (input.userConfig !== null && input.userConfig !== undefined && typeof input.userConfig === 'object' && !Array.isArray(input.userConfig))
+        ? input.userConfig
+        : {};
+    // FIX 6b: Use null-prototype object for all return paths
+    const values = Object.create(null);
+    const validKeys = [];
+    const warnings = [];
+    if (typeof configSchema !== 'object' || configSchema === null) {
+        return { values: Object.create(null), validKeys: [], warnings: [] };
+    }
+    for (const key of Object.keys(configSchema)) {
+        // S2: inline literal prototype-pollution guard (CodeQL barrier)
+        // Guard both the full key AND all dotted-path segments
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
+        const _keySegments = key.split('.');
+        if (_keySegments.some((s) => s === '__proto__' || s === 'constructor' || s === 'prototype'))
+            continue;
+        const slice = configSchema[key];
+        // If this key is still in the central schema → pending migration, skip
+        try {
+            if (isCentralKey(key)) {
+                warnings.push('federated-config: key "' + key + '" is still in the central config-schema (pending-migration); ' +
+                    'skipping federated resolution until the central schema entry is removed');
+                continue;
+            }
+        }
+        catch {
+            // isCentralKey threw — treat as unknown, skip defensively
+            warnings.push('federated-config: isCentralKey("' + key + '") threw; skipping key');
+            continue;
+        }
+        // Validate slice shape — skip malformed entries
+        if (!_isWellFormedSlice(slice)) {
+            warnings.push('federated-config: config slice for key "' + key + '" is malformed (missing or invalid type/default); skipping');
+            continue;
+        }
+        const sliceEntry = slice;
+        // FIX 1: Resolve value using NESTED dotted-path lookup through userConfig
+        let resolvedValue = sliceEntry.default;
+        const { found: userHasKey, value: userValue } = _getNestedValue(userConfig, key);
+        if (userHasKey && userValue !== undefined) {
+            // FIX 5b: For enum, validate against slice.values if present; otherwise check type
+            if (_typeMatches(userValue, sliceEntry)) {
+                resolvedValue = userValue;
+            }
+            else {
+                const typeDesc = sliceEntry.type === 'enum' && Array.isArray(sliceEntry.values)
+                    ? 'enum(' + sliceEntry.values.join('|') + ')'
+                    : sliceEntry.type;
+                warnings.push('federated-config: user-supplied value for "' + key + '" has wrong type or invalid enum value ' +
+                    '(expected ' + typeDesc + ', got ' + typeof userValue +
+                    (typeof userValue === 'string' ? ' "' + String(userValue) + '"' : '') +
+                    '); falling back to slice default');
+                // resolvedValue stays as slice default
+            }
+        }
+        // S2: inline literal guard before writing to values
+        if (key !== '__proto__' && key !== 'constructor' && key !== 'prototype') {
+            values[key] = resolvedValue;
+            validKeys.push(key);
+        }
+    }
+    return { values, validKeys, warnings };
+}
+module.exports = { mergeFederatedConfig };

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

@@ -0,0 +1,74 @@
+'use strict';
+/**
+ * Graphify command router — CLI subcommand dispatcher for `gsd-tools graphify`.
+ *
+ * ADR-959 (phase 4d-impl-2) pilot: first real capability command cutover.
+ * Extracted from the hardcoded `case 'graphify':` arm in gsd-tools.cjs.
+ * Behaviour is preserved byte-for-behaviour from the prior inline case;
+ * the dispatch path now flows: default → dispatchCapabilityCommand →
+ * require(graphify-command-router.cjs) → routeGraphifyCommand.
+ *
+ * Router signature: { args, cwd, raw, error } — identical to the 12 existing
+ * host routers. No new handler/arg convention; the capability registry
+ * discovers this router by name.
+ *
+ * Arg indexing (preserved exactly from the original case):
+ *   args[0] = 'graphify'  (family — matched by dispatchCapabilityCommand)
+ *   args[1] = subcommand  (query | status | diff | build)
+ *   args[2] = term (query) | 'snapshot' (build snapshot)
+ *   args.indexOf('--budget') + 1 = budget value
+ *
+ * Test seam: pass `_graphify` in the options object to inject a recording mock
+ * instead of the real graphify module. The `_`-prefix follows the repo's
+ * established seam convention (see other routers). Production callers omit it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const graphify = require("./graphify.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { ERROR_REASON } = io;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeGraphifyCommand({ args, cwd, raw, error, _graphify }) {
+    const subcommand = args[1];
+    const g = _graphify ?? graphify;
+    if (subcommand === 'query') {
+        const term = args[2];
+        if (!term) {
+            error('Usage: gsd-tools graphify query <term>', ERROR_REASON.USAGE);
+            return;
+        }
+        const budgetIdx = args.indexOf('--budget');
+        let budget = null;
+        if (budgetIdx !== -1) {
+            const rawBudget = args[budgetIdx + 1];
+            if (rawBudget === undefined || Number.isNaN(parseInt(rawBudget, 10))) {
+                error('Usage: gsd-tools graphify query <term> [--budget <N>]', ERROR_REASON.USAGE);
+                return;
+            }
+            budget = parseInt(rawBudget, 10);
+        }
+        core.output(g.graphifyQuery(cwd, term, { budget }), raw);
+    }
+    else if (subcommand === 'status') {
+        core.output(g.graphifyStatus(cwd), raw);
+    }
+    else if (subcommand === 'diff') {
+        core.output(g.graphifyDiff(cwd), raw);
+    }
+    else if (subcommand === 'build') {
+        if (args[2] === 'snapshot') {
+            core.output(g.writeSnapshot(cwd), raw);
+        }
+        else {
+            core.output(g.graphifyBuild(cwd), raw);
+        }
+    }
+    else {
+        error('Unknown graphify subcommand. Available: build, query, status, diff', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}
+module.exports = {
+    routeGraphifyCommand,
+};

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

@@ -1718,16 +1718,22 @@ function buildSkillManifest(cwd, skillsDir = null) {
             roots.push(rootSummary);
             continue;
         }
-        let skillCount = 0;
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const skillMdPath = node_path_1.default.join(rootPath, entry.name, 'SKILL.md');
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(skillMdPath);
-            if (content === null)
-                continue;
+        // Track skill names seen within this root to deduplicate dual-routed concretes
+        // (e.g. spec-phase nested under both gsd-ns-workflow and gsd-ns-manage).
+        const seenNamesInRoot = new Set();
+        function pushSkillEntry(
+        // relPath must use forward slashes on all platforms (manifest paths are
+        // posix-style for cross-platform stability; flat entries use template
+        // literals that always produce '/'; nested entries are joined below
+        // with explicit '/' separators rather than path.join).
+        relPath, content) {
             const frontmatter = extractFrontmatter(content);
-            const name = frontmatter['name'] || entry.name;
+            const dirPart = relPath.replace(/\/SKILL\.md$/, '');
+            const stem = dirPart.includes('/') ? dirPart.split('/').pop() : dirPart;
+            const name = frontmatter['name'] || stem;
+            if (seenNamesInRoot.has(name))
+                return false; // dedupe dual-routed concretes
+            seenNamesInRoot.add(name);
             const description = frontmatter['description'] || '';
             const triggers = [];
             const bodyMatch = content.match(/^---[\s\S]*?---\s*\n([\s\S]*)$/);
@@ -1746,14 +1752,54 @@ function buildSkillManifest(cwd, skillsDir = null) {
                 name,
                 description,
                 triggers,
-                path: entry.name,
-                file_path: `${entry.name}/SKILL.md`,
+                path: dirPart,
+                file_path: relPath,
                 root: rootInfo.root,
                 scope: rootInfo.scope,
                 installed: rootInfo.scope !== 'import-only',
                 deprecated: !!rootInfo.deprecated,
             });
-            skillCount++;
+            return true;
+        }
+        let skillCount = 0;
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillMdPath = node_path_1.default.join(rootPath, entry.name, 'SKILL.md');
+            const content = (0, shell_command_projection_cjs_1.platformReadSync)(skillMdPath);
+            if (content !== null) {
+                if (pushSkillEntry(`${entry.name}/SKILL.md`, content))
+                    skillCount++;
+            }
+            // Nested layout: <entry>/skills/<stem>/SKILL.md
+            // Used by cline, qwen, hermes, augment, trae, antigravity (#69 nested=true).
+            // Descend exactly one level into <entry>/skills/ — no deeper recursion.
+            // Scope to gsd-ns-* routers only: never vacuum up an unrelated user skill
+            // that happens to have its own `skills/` subdirectory.
+            if (!entry.name.startsWith('gsd-ns-'))
+                continue;
+            const nestedSkillsDir = node_path_1.default.join(rootPath, entry.name, 'skills');
+            let nestedEntries = [];
+            try {
+                nestedEntries = node_fs_1.default.readdirSync(nestedSkillsDir, { withFileTypes: true });
+            }
+            catch {
+                // No skills/ subdir — flat layout or unreadable; nothing to do.
+                nestedEntries = [];
+            }
+            for (const nested of nestedEntries) {
+                if (!nested.isDirectory())
+                    continue;
+                const nestedSkillMd = node_path_1.default.join(nestedSkillsDir, nested.name, 'SKILL.md');
+                const nestedContent = (0, shell_command_projection_cjs_1.platformReadSync)(nestedSkillMd);
+                if (nestedContent === null)
+                    continue;
+                // Use forward-slash separator explicitly so manifest paths are posix-style
+                // on all platforms, matching the flat-layout behaviour above.
+                const relPath = `${entry.name}/skills/${nested.name}/SKILL.md`;
+                if (pushSkillEntry(relPath, nestedContent))
+                    skillCount++;
+            }
         }
         rootSummary.skill_count = skillCount;
         roots.push(rootSummary);