@opengsd/gsd-core 1.6.0-rc.2 → 1.6.0

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

@@ -0,0 +1,464 @@
+"use strict";
+/**
+ * Coverage metadata — deterministic UAT routing (#1602)
+ *
+ * Parses the optional `coverage:` block in a SUMMARY.md frontmatter, validates
+ * each deliverable entry against the coverage schema, and classifies each into
+ * `auto_passed` (deterministically covered — no human prompt) or `present`
+ * (a human UAT checkpoint is required).
+ *
+ * Design constraints (see issue #1602, plus the Postel/Goodhart/Hyrum analysis):
+ *  - Lenient parse, strict auto-pass. The parser NEVER throws on malformed
+ *    input; a structurally surprising entry degrades to `present` + an error.
+ *  - Fail-safe asymmetry. Auto-pass is the narrow, fully-proven case
+ *    (strict-boolean `human_judgment:false` AND non-empty all-`pass`
+ *    verification AND zero validation errors). Everything else is presented to
+ *    the human. A false-negative is a redundant prompt (the status quo); a
+ *    false-positive ships a bug UAT existed to catch.
+ *  - Absent block ≠ empty block. No `coverage:` key → `mode: legacy` so the
+ *    caller falls through to today's prose-based extraction (byte-identical for
+ *    un-migrated phases). `coverage: []` → `mode: coverage`, zero entries.
+ *
+ * The classifier is deterministic code, not a prompt heuristic — the issue's
+ * central thesis. Tests assert on the frozen typed-IR surface below, not prose.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtils = require("./core-utils.cjs");
+const { toPosixPath } = coreUtils;
+const security_cjs_1 = require("./security.cjs");
+// ─── Frozen typed-IR surface ────────────────────────────────────────────────
+const MODE = Object.freeze({
+    COVERAGE: 'coverage',
+    LEGACY: 'legacy',
+});
+/** Why an entry was routed to the human path. Order of precedence below. */
+const PRESENT_REASON = Object.freeze({
+    VALIDATION_FAILED: 'validation_failed',
+    HUMAN_JUDGMENT: 'human_judgment',
+    NO_VERIFICATION: 'no_verification',
+    VERIFICATION_NOT_PASSING: 'verification_not_passing',
+});
+/** Per-entry validation error codes. */
+const ERROR_CODE = Object.freeze({
+    MISSING_ID: 'missing_id',
+    MISSING_DESCRIPTION: 'missing_description',
+    MISSING_HUMAN_JUDGMENT: 'missing_human_judgment',
+    INVALID_HUMAN_JUDGMENT: 'invalid_human_judgment',
+    MISSING_RATIONALE: 'missing_rationale',
+    DUPLICATE_ID: 'duplicate_id',
+    VERIFICATION_NOT_LIST: 'verification_not_list',
+    INVALID_KIND: 'invalid_kind',
+    INVALID_STATUS: 'invalid_status',
+    MISSING_REF: 'missing_ref',
+    MALFORMED_ENTRY: 'malformed_entry',
+    MALFORMED_BLOCK: 'malformed_block',
+});
+const VALID_KINDS = Object.freeze([
+    'unit', 'integration', 'e2e', 'automated_ui', 'manual_procedural', 'other',
+]);
+const VALID_STATUSES = Object.freeze(['pass', 'fail', 'unknown']);
+// ─── YAML-subset block parser (scoped to the coverage schema) ────────────────
+//
+// `extractFrontmatter` (src/frontmatter.cts) flattens `- ` list items to
+// scalars and cannot represent the coverage schema's list-of-maps-with-nested-
+// list-of-maps. `parseMustHavesBlock` is the existing precedent for hand-rolling
+// a focused parser for one schema; this is the same approach, one level deeper.
+// We deliberately do NOT pull in a general YAML engine (no external deps in
+// core; Greenspun's-tenth restraint).
+function lineIndent(line) {
+    const m = /^( *)/.exec(line);
+    return m ? m[1].length : 0;
+}
+function isSignificant(line) {
+    return line.trim() !== '';
+}
+function parseScalar(raw) {
+    const t = raw.trim();
+    if (t === '')
+        return '';
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    if (t === 'true')
+        return true;
+    if (t === 'false')
+        return false;
+    if (t === 'null' || t === '~')
+        return null;
+    return t;
+}
+/** Parse a block of lines (all indented ≥ `indent`) into a value. */
+function parseNode(lines, indent) {
+    const firstSig = lines.find(isSignificant);
+    if (firstSig === undefined)
+        return null;
+    if (lineIndent(firstSig) === indent && /^ *-(?: |$)/.test(firstSig)) {
+        return parseSequence(lines, indent);
+    }
+    return parseMapping(lines, indent);
+}
+function parseSequence(lines, indent) {
+    const items = [];
+    // Item-start lines: at exactly `indent`, beginning with a dash.
+    const starts = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!isSignificant(lines[i]))
+            continue;
+        if (lineIndent(lines[i]) === indent && /^ *-(?: |$)/.test(lines[i]))
+            starts.push(i);
+    }
+    for (let k = 0; k < starts.length; k++) {
+        const start = starts[k];
+        const end = k + 1 < starts.length ? starts[k + 1] : lines.length;
+        const itemLines = lines.slice(start, end);
+        // Re-base the dash line: replace the `indent` + "- " prefix with spaces so
+        // the inline content aligns at `indent + 2` and parses as a normal node.
+        itemLines[0] = ' '.repeat(indent + 2) + itemLines[0].slice(indent + 2);
+        const itemFirst = itemLines.find(isSignificant);
+        const head = itemFirst ? itemFirst.trim() : '';
+        if (/^[\w-]+:(?: |$)/.test(head)) {
+            items.push(parseMapping(itemLines, indent + 2));
+        }
+        else if (head === '') {
+            items.push(null);
+        }
+        else {
+            items.push(parseScalar(head));
+        }
+    }
+    return items;
+}
+function parseMapping(lines, indent) {
+    const map = {};
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!isSignificant(line) || lineIndent(line) !== indent) {
+            i++;
+            continue;
+        }
+        const km = /^[\w-]+:\s*(.*)$/.exec(line.trim());
+        if (!km) {
+            i++;
+            continue;
+        }
+        const key = /^([\w-]+):/.exec(line.trim())[1];
+        const inlineVal = km[1];
+        if (inlineVal === '[]') {
+            setKey(map, key, []);
+            i++;
+        }
+        else if (inlineVal === '') {
+            // Nested block: following lines indented deeper than `indent`.
+            let j = i + 1;
+            while (j < lines.length && (!isSignificant(lines[j]) || lineIndent(lines[j]) > indent))
+                j++;
+            const block = lines.slice(i + 1, j);
+            const blockFirst = block.find(isSignificant);
+            if (blockFirst === undefined) {
+                setKey(map, key, null);
+            }
+            else {
+                setKey(map, key, parseNode(block, lineIndent(blockFirst)));
+            }
+            i = j;
+        }
+        else {
+            setKey(map, key, parseScalar(inlineVal));
+            i++;
+        }
+    }
+    return map;
+}
+// Prototype-pollution-safe assignment (CodeQL js/prototype-pollution-utility:
+// inline literal key guard at the write site).
+function setKey(obj, key, value) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+        return;
+    obj[key] = value;
+}
+// ─── Frontmatter region helpers ──────────────────────────────────────────────
+function getFrontmatterYaml(content) {
+    const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
+    if (headerEnd === -1)
+        return null;
+    const closingLineStart = content.indexOf('\n---', headerEnd);
+    if (closingLineStart === -1)
+        return null;
+    const yamlEnd = content[closingLineStart - 1] === '\r' ? closingLineStart - 1 : closingLineStart;
+    return content.slice(headerEnd, yamlEnd);
+}
+/**
+ * Locate and parse the top-level `coverage:` block from a SUMMARY document.
+ * `malformed` is true when a `coverage:` key IS present with body content that
+ * does NOT parse into a non-empty sequence of entries — a distinct, fail-safe
+ * signal so a broken block can never masquerade as "all covered" (the caller
+ * falls back to prose extraction and surfaces the error). Distinct from
+ * `coverage: []` / an empty body, which is the legitimate zero-entry case.
+ */
+function parseCoverage(content) {
+    const yaml = getFrontmatterYaml(content);
+    if (yaml === null)
+        return { found: false, entries: [], malformed: false };
+    const lines = yaml.split(/\r?\n/);
+    let covIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^coverage:(?:\s|$)/.test(lines[i])) {
+            covIdx = i;
+            break;
+        }
+    }
+    if (covIdx === -1)
+        return { found: false, entries: [], malformed: false };
+    // Strip a trailing YAML comment from the header value. The `coverage:` header
+    // only ever carries `[]` or a comment — refs (which legitimately contain `#`)
+    // live in quoted scalars on deeper lines, never on this line.
+    const rawInline = /^coverage:\s*(.*)$/.exec(lines[covIdx])[1];
+    const inline = rawInline.replace(/\s*#.*$/, '').trim();
+    if (inline === '[]')
+        return { found: true, entries: [], malformed: false };
+    if (inline !== '') {
+        // A non-empty, non-`[]` inline scalar where a block was expected is malformed.
+        return { found: true, entries: [], malformed: true };
+    }
+    // Gather the block body: every line after the header up to the next top-level
+    // frontmatter key (a `key:` at column 0) or end of frontmatter. Mis-indented
+    // lines (tabs, wrong column) are INCLUDED so they surface as a malformed block
+    // rather than being silently excluded and the block read as falsely empty.
+    let j = covIdx + 1;
+    while (j < lines.length) {
+        const l = lines[j];
+        if (l.trim() === '') {
+            j++;
+            continue;
+        }
+        if (/^[A-Za-z0-9_-]+:(?:\s|$)/.test(l))
+            break; // next top-level key
+        j++;
+    }
+    const block = lines.slice(covIdx + 1, j);
+    const blockFirst = block.find(isSignificant);
+    if (blockFirst === undefined)
+        return { found: true, entries: [], malformed: false }; // empty body == coverage: []
+    const node = parseNode(block, lineIndent(blockFirst));
+    if (!Array.isArray(node) || node.length === 0) {
+        // Body had content but did not parse into a sequence of entries → malformed.
+        return { found: true, entries: [], malformed: true };
+    }
+    return { found: true, entries: node, malformed: false };
+}
+// ─── Validation ───────────────────────────────────────────────────────────────
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function validateEntry(entry, index, seenIds) {
+    const errors = [];
+    // Object-check FIRST — before any property access — so a `null`/scalar
+    // sequence item (e.g. a bare `-` or `- "string"`) can never throw.
+    if (!isPlainObject(entry)) {
+        errors.push({ index, id: null, code: ERROR_CODE.MALFORMED_ENTRY, message: 'coverage entry is not a mapping' });
+        return errors;
+    }
+    const id = typeof entry.id === 'string' ? entry.id : null;
+    const push = (code, message, field) => {
+        errors.push({ index, id, code, field, message });
+    };
+    if (typeof entry.id !== 'string' || entry.id.trim() === '') {
+        push(ERROR_CODE.MISSING_ID, 'entry is missing a non-empty id', 'id');
+    }
+    else if (seenIds.has(entry.id)) {
+        push(ERROR_CODE.DUPLICATE_ID, `duplicate coverage id "${entry.id}"`, 'id');
+    }
+    else {
+        seenIds.add(entry.id);
+    }
+    if (typeof entry.description !== 'string' || entry.description.trim() === '') {
+        push(ERROR_CODE.MISSING_DESCRIPTION, 'entry is missing a non-empty description', 'description');
+    }
+    if (!('human_judgment' in entry)) {
+        push(ERROR_CODE.MISSING_HUMAN_JUDGMENT, 'entry is missing the required human_judgment flag', 'human_judgment');
+    }
+    else if (typeof entry.human_judgment !== 'boolean') {
+        push(ERROR_CODE.INVALID_HUMAN_JUDGMENT, 'human_judgment must be a boolean (true|false)', 'human_judgment');
+    }
+    if (entry.human_judgment === true && (typeof entry.rationale !== 'string' || entry.rationale.trim() === '')) {
+        push(ERROR_CODE.MISSING_RATIONALE, 'rationale is required when human_judgment is true', 'rationale');
+    }
+    const v = entry.verification;
+    if (v !== undefined && !Array.isArray(v)) {
+        push(ERROR_CODE.VERIFICATION_NOT_LIST, 'verification must be a list', 'verification');
+    }
+    else if (Array.isArray(v)) {
+        v.forEach((ve, vi) => {
+            if (!isPlainObject(ve)) {
+                push(ERROR_CODE.MALFORMED_ENTRY, 'verification item is not a mapping', `verification[${vi}]`);
+                return;
+            }
+            if (typeof ve.kind !== 'string' || !VALID_KINDS.includes(ve.kind)) {
+                push(ERROR_CODE.INVALID_KIND, `verification kind must be one of ${VALID_KINDS.join(', ')}`, `verification[${vi}].kind`);
+            }
+            if (typeof ve.status !== 'string' || !VALID_STATUSES.includes(ve.status)) {
+                push(ERROR_CODE.INVALID_STATUS, `verification status must be one of ${VALID_STATUSES.join(', ')}`, `verification[${vi}].status`);
+            }
+            if (typeof ve.ref !== 'string' || ve.ref.trim() === '') {
+                push(ERROR_CODE.MISSING_REF, 'verification entry is missing a non-empty ref', `verification[${vi}].ref`);
+            }
+        });
+    }
+    return errors;
+}
+// ─── Classification ───────────────────────────────────────────────────────────
+function verificationList(entry) {
+    return Array.isArray(entry.verification) ? entry.verification : [];
+}
+/**
+ * Auto-pass is the narrow, fully-proven case:
+ *   - zero validation errors, AND
+ *   - human_judgment is the strict boolean `false`, AND
+ *   - verification is a NON-EMPTY list, AND
+ *   - every verification entry has status === 'pass'.
+ * The non-empty guard defeats the vacuous-`every` trap; the strict-boolean
+ * guard defeats a gamed string flag; the zero-errors guard means a malformed
+ * entry can never auto-pass.
+ */
+function isAutoPass(entry, errors) {
+    if (errors.length > 0)
+        return false;
+    if (entry.human_judgment !== false)
+        return false;
+    const v = verificationList(entry);
+    if (v.length === 0)
+        return false;
+    return v.every((ve) => isPlainObject(ve) && ve.status === 'pass');
+}
+function presentReason(entry, errors) {
+    if (errors.length > 0)
+        return PRESENT_REASON.VALIDATION_FAILED;
+    if (entry.human_judgment === true)
+        return PRESENT_REASON.HUMAN_JUDGMENT;
+    const v = verificationList(entry);
+    if (v.length === 0)
+        return PRESENT_REASON.NO_VERIFICATION;
+    return PRESENT_REASON.VERIFICATION_NOT_PASSING;
+}
+function san(value) {
+    return typeof value === 'string' ? (0, security_cjs_1.sanitizeForDisplay)(value) : null;
+}
+function entryView(entry) {
+    // Null-safe: a malformed (non-object) entry still gets a minimal view so it
+    // can be presented to the human rather than dropped or throwing.
+    if (!isPlainObject(entry)) {
+        return { id: null, description: null, verification: [], human_judgment: null };
+    }
+    const verification = verificationList(entry).map((ve) => ({
+        kind: isPlainObject(ve) && typeof ve.kind === 'string' ? ve.kind : null,
+        ref: isPlainObject(ve) ? san(ve.ref) : null,
+        status: isPlainObject(ve) && typeof ve.status === 'string' ? ve.status : null,
+    }));
+    const view = {
+        id: san(entry.id),
+        description: san(entry.description),
+        verification,
+        human_judgment: typeof entry.human_judgment === 'boolean' ? entry.human_judgment : null,
+    };
+    if (typeof entry.requirement === 'string')
+        view.requirement = (0, security_cjs_1.sanitizeForDisplay)(entry.requirement);
+    if (typeof entry.rationale === 'string')
+        view.rationale = (0, security_cjs_1.sanitizeForDisplay)(entry.rationale);
+    return view;
+}
+function legacyResult(summaryFile, errors) {
+    return {
+        mode: MODE.LEGACY,
+        summary_file: summaryFile,
+        total: 0,
+        all_auto_covered: false,
+        auto_passed: [],
+        present: [],
+        errors,
+    };
+}
+/** Pure classification core — no I/O. Testable in isolation. */
+function classifyContent(content, summaryFile) {
+    const { found, entries, malformed } = parseCoverage(content);
+    if (!found)
+        return legacyResult(summaryFile, []);
+    if (malformed) {
+        // A coverage block is present but unparseable. Fail-safe: fall back to the
+        // prose `## Accomplishments` path (the human still gets UAT) and surface the
+        // error so the author can fix the block. NEVER report all_auto_covered here.
+        return legacyResult(summaryFile, [{
+                index: -1,
+                id: null,
+                code: ERROR_CODE.MALFORMED_BLOCK,
+                message: 'coverage block is present but could not be parsed into entries; falling back to prose extraction',
+            }]);
+    }
+    const seenIds = new Set();
+    const autoPassed = [];
+    const present = [];
+    const allErrors = [];
+    entries.forEach((entry, index) => {
+        const errs = validateEntry(entry, index, seenIds);
+        allErrors.push(...errs);
+        const view = entryView(entry);
+        if (isAutoPass(entry, errs)) {
+            autoPassed.push({ ...view, source: 'automated' });
+        }
+        else {
+            present.push({ ...view, reason: presentReason(entry, errs) });
+        }
+    });
+    return {
+        mode: MODE.COVERAGE,
+        summary_file: summaryFile,
+        total: entries.length,
+        all_auto_covered: present.length === 0,
+        auto_passed: autoPassed,
+        present,
+        errors: allErrors,
+    };
+}
+// ─── CLI command ────────────────────────────────────────────────────────────
+function cmdClassify(cwd, options = {}, raw) {
+    const filePath = options.summary || options.file;
+    if (!filePath) {
+        error('SUMMARY file required: use uat classify-coverage --summary <path>');
+    }
+    let resolvedPath;
+    try {
+        resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'SUMMARY file', { allowAbsolute: true });
+    }
+    catch (e) {
+        // Emit a structured command error instead of leaking a raw stack trace.
+        error(`Invalid SUMMARY path: ${e instanceof Error ? e.message : 'unsafe path'}`);
+        return;
+    }
+    if (!node_fs_1.default.existsSync(resolvedPath)) {
+        error(`SUMMARY file not found: ${filePath}`);
+    }
+    const content = node_fs_1.default.readFileSync(resolvedPath, 'utf-8');
+    const result = classifyContent(content, toPosixPath(node_path_1.default.relative(cwd, resolvedPath)));
+    output(result, raw, undefined);
+}
+module.exports = {
+    cmdClassify,
+    classifyContent,
+    parseCoverage,
+    validateEntry,
+    isAutoPass,
+    presentReason,
+    MODE,
+    PRESENT_REASON,
+    ERROR_CODE,
+    VALID_KINDS,
+    VALID_STATUSES,
+};

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

@@ -42,6 +42,18 @@ const bulletColonRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)
  * Accepts both U+2014 em-dash (—) and U+2013 en-dash (–) for robustness.
  */
 const bulletEmDashRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?[^*]*[—–][^*]*\*\*\s*(.*)$/;
+/**
+ * Titled-colon form: `- **D-NN[ [tags]]: Title.** body`
+ * A title sits between the colon and the closing `**` (so the `:**` anchor of
+ * bulletColonRe fails, and there is no em-dash for bulletEmDashRe). This is a strict
+ * superset of the colon-immediate form, so it MUST be checked AFTER bulletColonRe and
+ * bulletEmDashRe — it only catches bullets those two miss. The title run is `[^:*]*` (no
+ * colon, no `*`) so a genuinely-malformed bullet with a colon in the pre-separator run
+ * (e.g. `D-07 ratio 3:1:**`) still fails the anchor and falls through to the parse-miss
+ * guard — matching bulletColonRe's `[^:*]*` discipline that the separator colon is the
+ * only colon permitted before `**`. (#1639)
+ */
+const bulletTitledColonRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?[^:*]*:[^:*]*\*\*\s*(.*)$/;
 /**
  * Parse decision lines from a block of text (the inner text of a <decisions>
  * or markdown-header section body). Returns the extracted decisions and a count
@@ -110,6 +122,21 @@ function parseDecisionLines(block) {
             current = { id, text: emDashMatch[3] || '', category, tags, trackable };
             continue;
         }
+        // Titled-colon form: `- **D-NN[ [tags]]: Title.** body` (#1639). Checked LAST — it is
+        // a strict superset of bulletColonRe, so it only catches bullets the colon-immediate
+        // and em-dash forms missed (minimal blast radius). id + [tags] trackability honored;
+        // the body after the closing bold run is reported as text.
+        const titledColonMatch = line.match(bulletTitledColonRe);
+        if (titledColonMatch) {
+            flush();
+            const id = `D-${titledColonMatch[1]}`;
+            const tags = titledColonMatch[2]
+                ? titledColonMatch[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)
+                : [];
+            const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
+            current = { id, text: titledColonMatch[3] || '', category, tags, trackable };
+            continue;
+        }
         // Parse-miss guard (FIX B + #1343): a line that looks like a `D-NN` decision
         // bullet but failed both patterns — flush, warn, and record the miss.
         // parseMisses > 0 forces could-not-parse even when other decisions parsed.

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

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Manifest-backed eval subcommand router (#10).
+ */
+const command_aliases_cjs_1 = require("./command-aliases.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
+function routeEvalCommand({ evalMod, args, cwd, raw, error }) {
+    routeCjsCommandFamily({
+        args,
+        subcommands: command_aliases_cjs_1.EVAL_SUBCOMMANDS,
+        unsupported: {},
+        error,
+        unknownMessage: (_s, available) => `Unknown eval subcommand. Available: ${available.join(', ')}`,
+        handlers: {
+            score: () => evalMod.cmdEvalScore(cwd, args, raw),
+        },
+    });
+}
+module.exports = { routeEvalCommand };

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

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Deterministic eval scoring verb (#10).
+ * Moves coverage/infra/overall arithmetic out of the gsd-eval-auditor prompt
+ * into code, per the framework's code-delegation discipline.
+ */
+function parseFlag(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+const INFRA_VALUE = { ok: 1, partial: 0.5, missing: 0 };
+const INFRA_TOKENS = new Set(Object.keys(INFRA_VALUE));
+function computeEvalScore(covered, total, infra) {
+    const coverage = total > 0 ? (covered / total) * 100 : 0;
+    // unknown/typo tokens are treated as `missing` (score 0) by design — upstream agent only passes ok|partial|missing
+    const infraSum = infra.reduce((acc, s) => acc + (INFRA_VALUE[s.trim().toLowerCase()] ?? 0), 0);
+    const infraScore = (infraSum / 5) * 100;
+    const overall = coverage * 0.6 + infraScore * 0.4;
+    const round = (n) => Math.round(n * 100) / 100;
+    const o = round(overall);
+    const verdict = o >= 80 ? 'PRODUCTION READY' :
+        o >= 60 ? 'NEEDS WORK' :
+            o >= 40 ? 'SIGNIFICANT GAPS' : 'NOT IMPLEMENTED';
+    return { coverage_score: round(coverage), infra_score: round(infraScore), overall_score: o, verdict };
+}
+function cmdEvalScore(_cwd, args, raw) {
+    const coveredRaw = parseFlag(args, '--covered');
+    const totalRaw = parseFlag(args, '--total');
+    const infraRaw = parseFlag(args, '--infra') || '';
+    const infra = infraRaw ? infraRaw.split(',').map((s) => s.trim().toLowerCase()) : [];
+    const covered = Number(coveredRaw);
+    const total = Number(totalRaw);
+    if (coveredRaw === undefined || coveredRaw.trim() === '' ||
+        totalRaw === undefined || totalRaw.trim() === '' ||
+        !Number.isFinite(covered) || !Number.isFinite(total) ||
+        infra.length !== 5) {
+        process.stderr.write('Usage: gsd-tools query eval.score --covered N --total N --infra a,b,c,d,e (each ok|partial|missing)\n');
+        process.exitCode = 1;
+        return;
+    }
+    // Domain validation: this is a public CLI verb, so reject out-of-domain inputs
+    // rather than emit nonsense (covered>total -> coverage_score>100; negatives ->
+    // negative scores). Counts must be non-negative integers and covered cannot
+    // exceed total; infra tokens must match the documented ok|partial|missing set.
+    if (!Number.isInteger(covered) || !Number.isInteger(total) || covered < 0 || total < 0 || covered > total) {
+        process.stderr.write('Invalid eval.score domain: require integer counts with 0 <= covered <= total.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const invalidInfra = infra.find((s) => !INFRA_TOKENS.has(s));
+    if (invalidInfra !== undefined) {
+        process.stderr.write(`Invalid eval.score infra token: ${invalidInfra || '<empty>'}. Expected ok|partial|missing.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = computeEvalScore(covered, total, infra);
+    process.stdout.write(raw ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+    process.stdout.write('\n');
+}
+module.exports = { cmdEvalScore, computeEvalScore };