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

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

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Phase Locator — Phase-directory search and location
+ *
+ * ADR-857 rollout phase 2d: extracted from core.cts (issue #881).
+ * Owns active-phase discovery against the `.planning/phases/` tree
+ * (`searchPhaseInDir`, `findPhaseInternal`) and archived-phase-dir
+ * enumeration (`getArchivedPhaseDirs`), matching phase ids/tokens against
+ * the filesystem. Behaviour is preserved byte-for-behaviour from the prior
+ * location; only the module boundary moved. core.cjs re-exports
+ * `searchPhaseInDir`, `findPhaseInternal`, and `getArchivedPhaseDirs` for back-compat.
+ *
+ * New imports should pull phase-locator helpers from phase-locator.cjs
+ * directly.
+ *
+ * Dependencies (leaf modules only — no core.cjs, no loadConfig):
+ *   - node:fs / node:path (stdlib)
+ *   - ./phase-id.cjs       (normalizePhaseName, phaseTokenMatches, extractPhaseToken)
+ *   - ./core-utils.cjs     (readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath)
+ *   - ./planning-workspace.cjs (planningDir)
+ */
+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 phaseIdModule = require("./phase-id.cjs");
+const { normalizePhaseName, phaseTokenMatches, extractPhaseToken } = phaseIdModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtilsModule = require("./core-utils.cjs");
+const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath } = coreUtilsModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspace;
+// ─── Phase search helpers ─────────────────────────────────────────────────────
+function searchPhaseInDir(baseDir, relBase, normalized) {
+    try {
+        const dirs = readSubdirectories(baseDir, true);
+        const match = dirs.find(d => phaseTokenMatches(d, normalized));
+        if (!match)
+            return null;
+        const phaseToken = extractPhaseToken(match);
+        const phaseNumber = phaseToken || normalized;
+        const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
+        const phaseName = afterToken || null;
+        const phaseDir = node_path_1.default.join(baseDir, match);
+        const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = getPhaseFileStats(phaseDir);
+        const plans = unsortedPlans.sort();
+        const summaries = unsortedSummaries.sort();
+        const completedPlanIds = new Set(summaries.flatMap(s => {
+            const exact = s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+            const canonical = extractCanonicalPlanId(s);
+            return canonical === exact ? [exact] : [exact, canonical];
+        }));
+        const incompletePlans = plans.filter(p => {
+            const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+            const canonical = extractCanonicalPlanId(p);
+            return !completedPlanIds.has(planId) && !completedPlanIds.has(canonical);
+        });
+        return {
+            found: true,
+            directory: toPosixPath(node_path_1.default.join(relBase, match)),
+            phase_number: phaseNumber,
+            phase_name: phaseName,
+            phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null,
+            plans,
+            summaries,
+            incomplete_plans: incompletePlans,
+            has_research: hasResearch,
+            has_context: hasContext,
+            has_verification: hasVerification,
+            has_reviews: hasReviews,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function findPhaseInternal(cwd, phase) {
+    if (!phase)
+        return null;
+    const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
+    const normalized = normalizePhaseName(phase);
+    const relPhasesDir = toPosixPath(node_path_1.default.relative(cwd, phasesDir));
+    const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized);
+    if (current)
+        return current;
+    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    if (!node_fs_1.default.existsSync(milestonesDir))
+        return null;
+    try {
+        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
+        const archiveDirs = milestoneEntries
+            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+            .map(e => e.name)
+            .sort()
+            .reverse();
+        for (const archiveName of archiveDirs) {
+            const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
+            const version = versionMatch[1];
+            const archivePath = node_path_1.default.join(milestonesDir, archiveName);
+            const relBase = '.planning/milestones/' + archiveName;
+            const result = searchPhaseInDir(archivePath, relBase, normalized);
+            if (result) {
+                result.archived = version;
+                return result;
+            }
+        }
+    }
+    catch { /* intentionally empty */ }
+    return null;
+}
+function getArchivedPhaseDirs(cwd) {
+    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    const results = [];
+    if (!node_fs_1.default.existsSync(milestonesDir))
+        return results;
+    try {
+        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
+        const phaseDirs = milestoneEntries
+            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+            .map(e => e.name)
+            .sort()
+            .reverse();
+        for (const archiveName of phaseDirs) {
+            const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
+            const version = versionMatch[1];
+            const archivePath = node_path_1.default.join(milestonesDir, archiveName);
+            const dirs = readSubdirectories(archivePath, true);
+            for (const dir of dirs) {
+                results.push({
+                    name: dir,
+                    milestone: version,
+                    basePath: node_path_1.default.join('.planning', 'milestones', archiveName),
+                    fullPath: node_path_1.default.join(archivePath, dir),
+                });
+            }
+        }
+    }
+    catch { /* intentionally empty */ }
+    return results;
+}
+module.exports = {
+    searchPhaseInDir,
+    findPhaseInternal,
+    getArchivedPhaseDirs,
+};

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

@@ -32,6 +32,9 @@ const stateMod = require("./state.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
+const uatPredicate = require("./uat-predicate.cjs");
+const { evaluateUatPassed } = uatPredicate;
 const { escapeRegex, loadConfig, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, output, error, readSubdirectories, phaseTokenMatches, ERROR_REASON, } = core;
 const { planningDir, withPlanningLock } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
@@ -1292,6 +1295,19 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     };
     output(result, raw);
 }
+function cmdPhaseUatPassed(cwd, phaseNum, raw, opts = {}) {
+    if (!phaseNum) {
+        error('phase number required for phase uat-passed');
+    }
+    const phaseInfoRaw = findPhaseInternal(cwd, phaseNum);
+    if (!phaseInfoRaw) {
+        error(`Phase ${phaseNum} not found`);
+    }
+    const phaseInfo = phaseInfoRaw;
+    const phaseFullDir = node_path_1.default.join(cwd, phaseInfo['directory']);
+    const report = evaluateUatPassed(phaseFullDir, { policy: opts.policy });
+    output({ phase: phaseNum, ...report }, raw);
+}
 module.exports = {
     cmdPhasesList,
     cmdPhaseNextDecimal,
@@ -1303,5 +1319,6 @@ module.exports = {
     cmdPhaseInsert,
     cmdPhaseRemove,
     cmdPhaseComplete,
+    cmdPhaseUatPassed,
     computeDependencyLevels,
 };

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

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * probe-core — generic spec-phase probe resolution model (ADR-550 Decision 7).
+ *
+ * Extracted from the edge-probe (the first adapter) once the prohibition probe (#644)
+ * proved it the *second* adapter of the same model: one adapter is a hypothetical seam,
+ * two is a real one. This module owns everything generic — the resolution lifecycle,
+ * the status×verification re-cut, `validateResolution`/`validateRequirement`, the
+ * `analyzeCoverage(items, resolutions?, validators)` merge/rollup/orphan-reject engine,
+ * the `byVerification` rollup, and the `runProbeCli` I/O scaffold. Each probe is a thin
+ * adapter: it supplies the proposal logic (deterministic for edge, LLM-recall for
+ * prohibition) and its closed vocabularies via injected validators.
+ *
+ * Authored as strict TypeScript (`src/probe-core.cts`) and compiled by
+ * `tsc -p tsconfig.build.json` to the gitignored runtime artifact
+ * `gsd-core/bin/lib/probe-core.cjs`. Do NOT hand-write the `.cjs`; it is emitted.
+ *
+ * Two orthogonal axes (the re-cut):
+ *   - status: resolved | dismissed | unresolved   — the resolution LIFECYCLE (shared)
+ *   - verification: <probe-defined> | null          — HOW a resolved item is verified
+ * The edge adapter declares `verification: explicit | backstop`; the prohibition adapter
+ * (#644) will declare `test | judgment`. Splitting the axes keeps the lifecycle enum free
+ * of a verification fact and lets a sibling probe add its own tiers without a parallel enum.
+ *
+ * Typing is hybrid (ADR-550 #5): generic type params for adapter DX, but enforcement runs
+ * through injected runtime validators, because the CLI executes over JSON where TS types are
+ * erased. The contract test pins the validators, not the types.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_STATUS = void 0;
+exports.validateRequirement = validateRequirement;
+exports.validateResolution = validateResolution;
+exports.analyzeCoverage = analyzeCoverage;
+exports.runProbeCli = runProbeCli;
+const node_fs_1 = __importDefault(require("node:fs"));
+/** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
+exports.VALID_STATUS = ['resolved', 'dismissed', 'unresolved'];
+function errMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Structural guard for the report an adapter's `analyze` returns. The scaffold types `analyze`
+ * loosely (it runs over JSON-parsed input the adapter `as`-casts), so a future adapter (#644)
+ * that forgets to validate inside its closure could hand back a malformed object. Rather than
+ * stringify garbage as green output, `runProbeCli` checks the report shape and fails closed.
+ */
+function isValidReport(report) {
+    if (report == null || typeof report !== 'object')
+        return false;
+    const r = report;
+    if (!Array.isArray(r.items))
+        return false;
+    const c = r.coverage;
+    if (c == null || typeof c !== 'object')
+        return false;
+    if (typeof c.applicable !== 'number' || typeof c.resolved !== 'number' || typeof c.unresolved !== 'number') {
+        return false;
+    }
+    if (c.byVerification == null || typeof c.byVerification !== 'object')
+        return false;
+    return true;
+}
+/**
+ * Validate a requirement's generic structural fields — fail closed on malformed input rather
+ * than coercing it. Probe-specific fields (e.g. the edge adapter's `shapes`) are validated by
+ * the adapter. Typed loosely because the CLI casts arbitrary parsed JSON to `Requirement`.
+ */
+function validateRequirement(requirement) {
+    const r = requirement;
+    if (typeof r.id !== 'string' || !r.id.trim()) {
+        throw new Error(`requirement id must be a non-empty string (got ${JSON.stringify(r.id)})`);
+    }
+    if (r.text != null && typeof r.text !== 'string') {
+        throw new Error(`requirement ${r.id} text must be a string when present`);
+    }
+}
+/**
+ * Validate a resolution against the probe's injected validators. Rejects an unknown status,
+ * a dismissal without a non-empty reason, a `resolved` item with a missing/unknown
+ * verification tier, and a `resolved` item missing any field its tier requires (per
+ * `requiredFieldsByVerification`). Returns true on success.
+ */
+function validateResolution(r, validators) {
+    const key = `${r.requirement_id}::${r.category}`;
+    if (!exports.VALID_STATUS.includes(r.status)) {
+        throw new Error(`invalid status "${r.status}" for ${key}`);
+    }
+    // Invariant (this module's header): `verification` is null unless `status` is `resolved`.
+    // Enforce it for EVERY status — a dismissed/unresolved resolution carrying a verification
+    // tier would otherwise merge verbatim (`analyzeCoverage` below) and silently break the
+    // model for the second adapter (#644) that inherits this seam. Fail closed across the full
+    // status×verification space, not just `resolved`.
+    if (r.status !== 'resolved' && r.verification != null) {
+        throw new Error(`verification must be null unless status is "resolved" (got "${r.verification}") for ${key}`);
+    }
+    // An `unresolved` resolution is an UNACTED item: it must carry no resolution/reason payload.
+    // A populated payload is an authoring mistake (the author meant resolved/dismissed) that
+    // would otherwise be silently dropped into the unresolved count with no error pointing at
+    // it. Reject it so the mistake surfaces.
+    if (r.status === 'unresolved') {
+        if (r.resolution != null && String(r.resolution).trim()) {
+            throw new Error(`unresolved must not carry a resolution (${key})`);
+        }
+        if (r.reason != null && String(r.reason).trim()) {
+            throw new Error(`unresolved must not carry a reason (${key})`);
+        }
+    }
+    if (r.status === 'dismissed' && !(r.reason && String(r.reason).trim())) {
+        throw new Error(`dismissed requires a reason (${key})`);
+    }
+    if (r.status === 'resolved') {
+        const tier = r.verification;
+        if (tier == null) {
+            throw new Error(`resolved requires a verification tier (one of: ${validators.verification.join(', ')}) for ${key}`);
+        }
+        if (!validators.verification.includes(tier)) {
+            throw new Error(`invalid verification "${tier}" for ${key} — must be one of: ${validators.verification.join(', ')}`);
+        }
+        const required = validators.requiredFieldsByVerification[tier] ?? [];
+        for (const field of required) {
+            // field is 'resolution' | 'reason'; both are `string | null | undefined` on Resolution,
+            // so the indexed access is string-typed (no unknown-to-string coercion).
+            const value = r[field];
+            if (!(value != null && String(value).trim())) {
+                throw new Error(`${tier} requires a ${field} (${key})`);
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Merge author resolutions onto ALREADY-PROPOSED items and roll up coverage counts.
+ *
+ * Core operates on `items[]`, never a `proposeFn`: probes have different deterministic
+ * surfaces (edge = deterministic propose + LLM resolve; prohibition = LLM propose + deterministic
+ * validate/merge), so proposal stays in each adapter and core must not assume it is deterministic.
+ *
+ * `coverage.resolved` is the COUNT of CLOSED items (`resolved` + `dismissed` status) =
+ * `applicable - unresolved` — the pre-re-cut "covered + dismissed + backstop" set,
+ * count-preserved. `byVerification` breaks the `resolved`-status items down by tier (each tier
+ * initialized to 0). Throws on any invalid resolution, a duplicate, an orphan (a resolution
+ * matching no proposed item), or a proposed item whose category is outside `validators.categories`.
+ */
+function analyzeCoverage(items, resolutions = [], validators) {
+    if (!Array.isArray(items)) {
+        throw new Error('items must be an array');
+    }
+    const key = (r) => `${r.requirement_id}::${r.category}`;
+    const resMap = new Map();
+    for (const r of resolutions) {
+        validateResolution(r, validators);
+        if (resMap.has(key(r))) {
+            throw new Error(`duplicate resolution for ${key(r)}`);
+        }
+        resMap.set(key(r), r);
+    }
+    const validCategories = new Set(validators.categories);
+    const merged = [];
+    const itemKeys = new Set();
+    for (const item of items) {
+        if (!validCategories.has(item.category)) {
+            throw new Error(`item ${key(item)} has unknown category "${item.category}" — not one of: ${validators.categories.join(', ')}`);
+        }
+        itemKeys.add(key(item));
+        const o = resMap.get(key(item));
+        if (o) {
+            merged.push({ ...item, status: o.status, verification: o.verification ?? null, resolution: o.resolution ?? null, reason: o.reason ?? null });
+        }
+        else {
+            // No author resolution: the item is rolled up VERBATIM, so its own status/fields must be
+            // valid too. The edge adapter only proposes `unresolved` items, but the prohibition adapter
+            // (#644) proposes LLM-generated items that arrive already populated — one carrying an
+            // out-of-enum status (e.g. the dropped "covered") or `dismissed` with no reason would
+            // otherwise be counted closed without validation. An Item is structurally a superset of a
+            // Resolution, so the same fail-closed check guards both. (ADR-550 Decision 5 hardens this
+            // shared seam for the second adapter; m1.)
+            validateResolution(item, validators);
+            merged.push(item);
+        }
+    }
+    // Reject orphan resolutions — a resolution whose (requirement_id, category) matches no
+    // proposed item (typo'd category or a non-applicable one) would otherwise be silently
+    // dropped, leaving the author believing an item is resolved while the report shows it
+    // unresolved (adversarial-review HIGH; preserved from the edge-probe's original engine).
+    for (const k of resMap.keys()) {
+        if (!itemKeys.has(k)) {
+            throw new Error(`unknown resolution for ${k} — no matching proposed item (typo'd category or non-applicable shape?)`);
+        }
+    }
+    const unresolved = merged.filter((i) => i.status === 'unresolved').length;
+    const applicable = merged.length;
+    const resolved = applicable - unresolved; // closed set: resolved-status + dismissed
+    const byVerification = {};
+    for (const tier of validators.verification)
+        byVerification[tier] = 0;
+    for (const i of merged) {
+        if (i.status === 'resolved' && i.verification != null) {
+            byVerification[i.verification] = (byVerification[i.verification] ?? 0) + 1;
+        }
+    }
+    return { items: merged, coverage: { applicable, resolved, unresolved, byVerification } };
+}
+/**
+ * Read the requirements file (and optional resolutions file), run the adapter's `analyze`,
+ * and write the report as pretty JSON + newline. With no requirements path, writes the usage
+ * line to stderr and exits 2. A JSON-parse failure or any `analyze` throw is a handled error:
+ * stderr + exit 2, never an uncaught stack trace — so the engine's fail-closed validation
+ * surfaces at the workflow boundary rather than failing open.
+ */
+function runProbeCli(analyze, options) {
+    const argv = options.argv ?? process.argv;
+    const readFile = options.readFile ?? ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
+    const write = options.write ?? ((s) => { process.stdout.write(s); });
+    const writeErr = options.writeErr ?? ((s) => { process.stderr.write(s); });
+    const exit = options.exit ?? ((code) => { process.exit(code); });
+    const reqPath = argv[2];
+    const resPath = argv[3];
+    if (!reqPath) {
+        writeErr(`usage: ${options.usage}\n`);
+        exit(2);
+        return;
+    }
+    let requirements;
+    try {
+        requirements = JSON.parse(readFile(reqPath));
+    }
+    catch (e) {
+        writeErr(`error: cannot parse JSON from ${reqPath}: ${errMessage(e)}\n`);
+        exit(2);
+        return;
+    }
+    let resolutions = [];
+    if (resPath) {
+        try {
+            resolutions = JSON.parse(readFile(resPath));
+        }
+        catch (e) {
+            writeErr(`error: cannot parse JSON from ${resPath}: ${errMessage(e)}\n`);
+            exit(2);
+            return;
+        }
+    }
+    try {
+        const report = analyze(requirements, resolutions);
+        if (!isValidReport(report)) {
+            throw new Error('adapter returned a structurally-invalid coverage report (expected { items[], coverage{ applicable, resolved, unresolved, byVerification } })');
+        }
+        write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    catch (e) {
+        writeErr(`error: ${errMessage(e)}\n`);
+        exit(2);
+    }
+}

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

@@ -20,8 +20,8 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_readline_1 = __importDefault(require("node:readline"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const core = require("./core.cjs");
-const { output, error, reapStaleTempFiles, ensureGsdTempDir, GSD_TEMP_DIR } = core;
+const ioModule = require("./io.cjs");
+const { output, error, reapStaleTempFiles, ensureGsdTempDir, GSD_TEMP_DIR } = ioModule;
 // ─── Session I/O Helpers ──────────────────────────────────────────────────────
 function getSessionsDir(overridePath) {
     const dir = overridePath || node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'projects');