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

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

@@ -16,6 +16,10 @@ const node_child_process_1 = require("node:child_process");
 const core = require("./core.cjs");
 const { output, error, ERROR_REASON } = core;
 const decisions_cjs_1 = require("./decisions.cjs");
+const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapModule = require("./roadmap.cjs");
+const { getRoadmapPhaseWithFallback } = roadmapModule;
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -320,8 +324,130 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
         message: buildVerifyMessage(notHonored),
     }, raw, undefined);
 }
+// ─── ui-plan-gate ─────────────────────────────────────────────────────────────
+/**
+ * ui-plan-gate: given a phase number, checks whether the phase has frontend
+ * indicators and whether a *-UI-SPEC.md already exists in the phase directory.
+ *
+ * Returns JSON: { frontend: boolean, hasUiSpec: boolean, block: boolean }
+ *   block = frontend && !hasUiSpec (gate fires when UI work is detected but no spec exists)
+ *
+ * Invocable as: gsd_run check ui-plan-gate <phase>
+ *
+ * Uses checkUiPresence from ui-safety-gate.cjs — does NOT reimplement frontend detection.
+ * Uses getRoadmapPhaseInternal + findPhaseInternal from core.cjs for phase data.
+ */
+function findUiSpecInDir(phaseDir) {
+    if (!phaseDir || !node_fs_1.default.existsSync(phaseDir))
+        return '';
+    try {
+        const files = node_fs_1.default.readdirSync(phaseDir);
+        const found = files.find((f) => /-UI-SPEC\.md$/.test(f));
+        return found ? node_path_1.default.join(phaseDir, found) : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Pure logic for ui-plan-gate — exposed for direct behavioral testing.
+ *
+ * Given a projectDir and phase number:
+ *   (a) Reads the phase section from ROADMAP.md via getRoadmapPhaseWithFallback —
+ *       same two-pass lookup (current milestone → full roadmap) as `roadmap.get-phase`
+ *       (cmdRoadmapGetPhase). Cross-milestone / older frontend phases resolve correctly.
+ *       If ROADMAP.md is missing, phaseSection is '' (ROADMAP.md not present = project
+ *       has no roadmap = cannot be frontend). If the phase truly can't be found after
+ *       both passes, phaseSection is '' and phaseLookupFailed is set so callers can
+ *       surface the miss — we do NOT silently degrade to frontend:false if the roadmap
+ *       exists but the phase header is absent.
+ *   (b) Runs checkUiPresence (frontend detection) — no reimplementation.
+ *   (c) Resolves the phase directory via core.findPhaseInternal; checks for *-UI-SPEC.md.
+ *
+ * Returns: { frontend, hasUiSpec, block, uiSpecPath, phaseLookupFailed }
+ *   block = frontend && !hasUiSpec
+ *   phaseLookupFailed = ROADMAP.md present but phase header not found (surfaced for
+ *                       onError:halt gates so a missing phase doesn't silently bypass)
+ */
+function computeUiPlanGate(projectDir, phase) {
+    // (a) Read the phase section text using the same two-pass lookup as roadmap.get-phase.
+    // getRoadmapPhaseWithFallback: current-milestone first, then stripShippedMilestones
+    // fallback — mirrors cmdRoadmapGetPhase exactly.
+    let phaseSection = '';
+    let phaseLookupFailed;
+    try {
+        const section = getRoadmapPhaseWithFallback(projectDir, phase);
+        if (section === null) {
+            // Distinguish: ROADMAP.md missing (no-roadmap project) vs phase not found in ROADMAP.
+            // core.planningDir(cwd) resolves the .planning/ root for workstream-aware paths.
+            const planDir = typeof core['planningDir'] === 'function'
+                ? core['planningDir'](projectDir)
+                : node_path_1.default.join(projectDir, '.planning');
+            const roadmapPath = node_path_1.default.join(planDir, 'ROADMAP.md');
+            if (node_fs_1.default.existsSync(roadmapPath)) {
+                // ROADMAP.md exists but phase was not found → surface the miss
+                phaseLookupFailed = true;
+            }
+            // phaseSection stays ''
+        }
+        else {
+            phaseSection = section;
+        }
+    }
+    catch { /* roadmap read failure → treat as empty (non-frontend) */ }
+    // (b) Run checkUiPresence (frontend detection) — reuse existing helper; no reimplementation
+    const presenceResult = (0, ui_safety_gate_cjs_1.checkUiPresence)(phaseSection);
+    const frontend = presenceResult.hasUI;
+    // (c) Resolve phase directory via findPhaseInternal and check for *-UI-SPEC.md
+    const coreModule = core;
+    let phaseDir = '';
+    try {
+        const findPhase = coreModule['findPhaseInternal'];
+        if (typeof findPhase === 'function') {
+            const result = findPhase(projectDir, phase);
+            if (result && typeof result === 'object') {
+                // findPhaseInternal returns { directory: '<relative-posix-path>', ... }
+                // directory is relative to cwd — resolve it to absolute.
+                const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
+                if (relDir) {
+                    phaseDir = node_path_1.default.resolve(projectDir, relDir);
+                }
+            }
+            else if (typeof result === 'string') {
+                phaseDir = result;
+            }
+        }
+    }
+    catch { /* phase dir lookup failure → hasUiSpec=false */ }
+    const uiSpecPath = findUiSpecInDir(phaseDir);
+    const hasUiSpec = uiSpecPath !== '';
+    // block = frontend phase with no UI-SPEC
+    const block = frontend && !hasUiSpec;
+    const result = {
+        frontend, hasUiSpec, block, uiSpecPath: hasUiSpec ? uiSpecPath : null,
+    };
+    if (phaseLookupFailed)
+        result.phaseLookupFailed = true;
+    return result;
+}
+function cmdUiPlanGate(projectDir, args, raw) {
+    // args[0] = 'check', args[1] = 'ui-plan-gate', args[2] = phase
+    const phase = args[2] || '';
+    if (!phase) {
+        error('ui-plan-gate requires a phase argument: check ui-plan-gate <phase>', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    output(computeUiPlanGate(projectDir, phase), raw, undefined);
+}
 function routeCheckCommand({ args, cwd, raw }) {
-    const subcommand = args[1];
+    // Normalize dots to hyphens in the subcommand so both forms are accepted.
+    // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
+    // directly runnable as `gsd_run check ui.plan-gate` — the dot is normalized to
+    // `ui-plan-gate` before routing. The generic gate-dispatch in §5.6 reads
+    // `check.query` from the active gate hook and runs `gsd_run check ${hook.check.query}`,
+    // so the declared query must be dispatchable exactly as declared.
+    const rawSubcommand = args[1];
+    const subcommand = typeof rawSubcommand === 'string' ? rawSubcommand.replace(/\./g, '-') : rawSubcommand;
     if (subcommand === 'auto-mode') {
         cmdAutoMode(cwd, raw);
         return;
@@ -334,10 +460,15 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdDecisionCoverageVerify(cwd, args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    if (subcommand === 'ui-plan-gate') {
+        cmdUiPlanGate(cwd, args, raw);
+        return;
+    }
+    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, ui-plan-gate', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,
     decisionMentioned,
     extractPlanDesignatedSections,
+    computeUiPlanGate,
 };

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

@@ -159,6 +159,7 @@ function checkAgentsInstalled(runtime) {
             agents_installed: false,
             missing_agents: expectedAgents,
             installed_agents: [],
+            incomplete_agents: [],
             agents_dir: agentsDir,
             agent_runtime: resolvedRuntime,
         };
@@ -182,10 +183,59 @@ function checkAgentsInstalled(runtime) {
             missing.push(agent);
         }
     }
+    // ── Manifest-backed completeness check ──────────────────────────────────────
+    // If a gsd-file-manifest.json exists alongside the agents dir (parent dir),
+    // verify that every manifest-tracked file for each expected agent is present
+    // on disk. Missing manifest-tracked files indicate an incomplete install even
+    // when the plain presence check above passed (e.g. .md present, .toml absent).
+    // If no manifest is found the check is a no-op (graceful for claude/bundled).
+    const incomplete = [];
+    const manifestPath = node_path_1.default.join(node_path_1.default.dirname(agentsDir), 'gsd-file-manifest.json');
+    let manifestFiles = {};
+    try {
+        const raw = node_fs_1.default.readFileSync(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            'files' in parsed &&
+            typeof parsed['files'] === 'object' &&
+            parsed['files'] !== null) {
+            manifestFiles = parsed['files'];
+        }
+    }
+    catch {
+        // No manifest or unreadable — completeness check is skipped
+    }
+    if (Object.keys(manifestFiles).length > 0) {
+        for (const agent of expectedAgents) {
+            // Find all manifest keys that belong to this agent:
+            // key must be "agents/<agentName>.<ext>" with no further path segments.
+            const agentPrefix = `agents/${agent}.`;
+            const agentManifestKeys = Object.keys(manifestFiles).filter(key => {
+                if (!key.startsWith(agentPrefix))
+                    return false;
+                const rest = key.slice(agentPrefix.length);
+                // rest must be a bare extension (no slashes, non-empty)
+                return rest.length > 0 && !rest.includes('/');
+            });
+            if (agentManifestKeys.length === 0) {
+                // Agent not tracked in manifest — skip completeness check for this agent
+                continue;
+            }
+            const allPresent = agentManifestKeys.every(key => {
+                const basename = key.slice('agents/'.length);
+                return node_fs_1.default.existsSync(node_path_1.default.join(agentsDir, basename));
+            });
+            if (!allPresent) {
+                incomplete.push(agent);
+            }
+        }
+    }
     return {
-        agents_installed: installed.length > 0 && missing.length === 0,
+        agents_installed: installed.length > 0 && missing.length === 0 && incomplete.length === 0,
         missing_agents: missing,
         installed_agents: installed,
+        incomplete_agents: incomplete,
         agents_dir: agentsDir,
         agent_runtime: resolvedRuntime,
     };

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/intel.cjs

@@ -149,7 +149,7 @@ function matchesInValue(value, lowerTerm) {
 }
 /**
  * Query intel files for a search term.
- * Searches across all JSON intel files (keys and values) and arch.md (text lines).
+ * Searches across all JSON intel files in INTEL_FILES (keys and values), including arch-decisions.json (parsed as JSON, not as text).
  */
 function intelQuery(term, planningDir) {
     if (!isIntelEnabled(planningDir))
@@ -328,7 +328,7 @@ function intelValidate(planningDir) {
         }
         // Validate entries are objects with expected fields
         if (data.entries && typeof data.entries === 'object') {
-            // files.json: check exports are actual symbol names (no spaces)
+            // file-roles.json (INTEL_FILES key 'files'): check exports are actual symbol names (no spaces)
             if (key === 'files') {
                 for (const [entryPath, entry] of Object.entries(data.entries)) {
                     const entryObj = entry;
@@ -348,7 +348,7 @@ function intelValidate(planningDir) {
                     }
                 }
             }
-            // deps.json: check entries have version, type, used_by
+            // dependency-graph.json (INTEL_FILES key 'deps'): check entries have version, type, used_by
             if (key === 'deps') {
                 for (const [depName, entry] of Object.entries(data.entries)) {
                     const entryObj = entry;

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

@@ -65,6 +65,61 @@ function reapStaleTempFiles(prefix = 'gsd-', { maxAgeMs = 5 * 60 * 1000, dirsOnl
     }
 }
 // ─── Output helpers ───────────────────────────────────────────────────────────
+/**
+ * Transient write errnos. When stdout/stderr is a NON-BLOCKING pipe — as it is
+ * under the parallel `node --test` runner on Linux CI — a full pipe buffer makes
+ * `fs.writeSync` throw EAGAIN, and a signal can interrupt it with EINTR. Both
+ * clear on retry once the reader drains. This is the same transient class the
+ * STATE.md lock path already retries (ACQUIRE_LOCK_RETRY_ERRNOS, #3776); #1008.
+ */
+const WRITE_RETRY_ERRNOS = new Set(['EAGAIN', 'EINTR']);
+// Bounded so a pathological never-draining fd cannot spin forever. Each retry
+// yields the thread for ~1ms via Atomics.wait (the project's sync-sleep idiom —
+// see clock.cts realClock.sleep), so the cap is ~1s of total back-pressure wait.
+const WRITE_MAX_RETRIES = 1000;
+const WRITE_RETRY_BACKOFF_MS = 1;
+// Sleep buffer is lazily allocated on the FIRST back-pressure retry (rare — only
+// when a non-blocking pipe is full) and then reused. Keeping it out of module
+// load costs nothing on the overwhelmingly common no-retry path and avoids
+// perturbing SharedArrayBuffer-allocation accounting in other modules (perf-316).
+let _writeSleepBuf = null;
+function backoffOnce() {
+    if (_writeSleepBuf === null)
+        _writeSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(_writeSleepBuf, 0, 0, WRITE_RETRY_BACKOFF_MS);
+}
+/**
+ * Write the entire payload to `fd`, tolerating non-blocking-pipe back-pressure.
+ *
+ * `fs.writeSync` does NOT block on a non-blocking pipe: a full buffer throws
+ * EAGAIN, and a partially-drained buffer returns a SHORT count (fewer bytes than
+ * requested). The previous bare `fs.writeSync(fd, string)` call assumed it always
+ * blocked until the kernel accepted every byte — false under load, which both
+ * threw spurious errors and risked silently truncating output (#1008).
+ *
+ * This loops on short counts (advancing the offset) and retries EAGAIN/EINTR with
+ * a brief Atomics.wait backoff that yields the thread so the reader can drain.
+ * Non-transient errors (e.g. EPIPE) propagate unchanged.
+ */
+function writeAllSync(fd, data) {
+    const buf = Buffer.from(data, 'utf8');
+    let offset = 0;
+    let retries = 0;
+    while (offset < buf.length) {
+        try {
+            offset += node_fs_1.default.writeSync(fd, buf, offset, buf.length - offset);
+        }
+        catch (err) {
+            const code = err.code ?? '';
+            if (WRITE_RETRY_ERRNOS.has(code) && retries < WRITE_MAX_RETRIES) {
+                retries += 1;
+                backoffOnce();
+                continue;
+            }
+            throw err;
+        }
+    }
+}
 function output(result, raw, rawValue) {
     let data;
     if (raw && rawValue !== undefined) {
@@ -87,10 +142,10 @@ function output(result, raw, rawValue) {
         }
     }
     // process.stdout.write() is async when stdout is a pipe — process.exit()
-    // can tear down the process before the reader consumes the buffer.
-    // fs.writeSync(1, ...) blocks until the kernel accepts the bytes, and
-    // skipping process.exit() lets the event loop drain naturally.
-    node_fs_1.default.writeSync(1, data);
+    // can tear down the process before the reader consumes the buffer. writeAllSync
+    // pushes every byte synchronously (looping short counts, retrying EAGAIN/EINTR),
+    // and skipping process.exit() lets the event loop drain naturally.
+    writeAllSync(1, data);
 }
 /**
  * Frozen enum of typed reason codes used by error() for structured errors.
@@ -148,10 +203,10 @@ function getJsonErrorMode() { return _jsonErrorMode; }
 function error(message, reason = ERROR_REASON.UNKNOWN) {
     if (_jsonErrorMode) {
         const payload = JSON.stringify({ ok: false, reason, message }) + '\n';
-        node_fs_1.default.writeSync(2, payload);
+        writeAllSync(2, payload);
     }
     else {
-        node_fs_1.default.writeSync(2, 'Error: ' + message + '\n');
+        writeAllSync(2, 'Error: ' + message + '\n');
     }
     process.exit(1);
 }