@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -17,11 +17,16 @@ exports.isCompletedInventory = isCompletedInventory;
 exports.buildWorkstreamInventory = buildWorkstreamInventory;
 const node_path_1 = __importDefault(require("node:path"));
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+// #5060: `phase-status.cjs` is a load-time leaf (no top-level requires) — its
+// `phaseStatusFromFacts`/`toWireStatus` are pure functions of facts, so
+// importing them here does not violate this module's "No I/O. No async."
+// contract.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 // Internal helpers
 function toPosixPath(p) {
     return p.split('\\').join('/');
 }
-// #2562/#2645's FAILING_VERIFICATION_STATUSES set (the verdicts that used to
+// #2562/#2645's former failing-verdict set (the verdicts that used to
 // disqualify a phase from `complete` when combined with a local
 // summary-count-meets-plan-count check) was removed by ADR-3180 §7.4
 // (#3186): `complete` is now the single canonical owner's verdict
@@ -133,11 +138,14 @@ function buildWorkstreamInventory(inputs) {
         // read `pending` instead of `complete`. `complete` defaults to `false`
         // when absent so a caller that has not been updated to pass it never
         // silently reads as complete.
-        const status = (counts?.complete ?? false)
-            ? 'complete'
-            : planCount > 0
-                ? 'in_progress'
-                : 'pending';
+        // #5060: routed through the Phase Status Module's owner ladder rather
+        // than a local re-derivation of the same complete/planCount branches.
+        const status = (0, phase_status_cjs_1.toWireStatus)((0, phase_status_cjs_1.phaseStatusFromFacts)({
+            planCount,
+            summaryCount,
+            complete: counts?.complete ?? false,
+            verificationStatus: counts?.verificationStatus ?? null,
+        }));
         // #2562: only current-milestone phases feed the rollup when scoping is on,
         // and only one directory per phase key (see rollupDirs above).
         const countsTowardMilestone = (!scoped || counts?.inMilestone !== false) && rollupDirs.has(dir);

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

@@ -33,7 +33,7 @@ const { extractFrontmatter, stripFrontmatter } = frontmatterMod;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
-const { isPhaseComplete } = verificationMod;
+const { isPhaseComplete, isVerificationStatus, VERIFICATION_STATUS } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { phaseKeyFromDir, phaseKeyFromProse, parentPhaseKey } = phaseIdMod;
@@ -269,7 +269,10 @@ function readVerificationLedger(wsDir) {
     }
     const out = {};
     for (const [key, value] of Object.entries(parsed)) {
-        if (typeof value === 'string')
+        // #5118: an entry outside the closed enum (a stored `unknown` from an
+        // older run) reads as absent — the phase then fails CLOSED to
+        // `unrecorded`, the same posture as a corrupt ledger.
+        if (isVerificationStatus(value))
             out[key] = value;
     }
     return { state: 'ok', entries: out };
@@ -555,7 +558,7 @@ function inspectWorkstream(cwd, name, options = {}) {
         // unverified-fallback diagnostic (#3057 B4) — the closest existing idiom,
         // since `WorkstreamInventory`'s aggregate return shape carries no
         // per-phase verification detail for this to attach to.
-        if (verificationResult.staleCheckIndeterminate) {
+        if ('staleCheckIndeterminate' in verificationResult && verificationResult.staleCheckIndeterminate) {
             writeDiagnostic(`⚠ workstream-inventory: verification staleness check could not complete for phase directory '${dir}' in workstream '${name}' — routed as not-stale, but this was not actually verified. See #3057.\n`, { phaseDir: dir, reason: 'staleCheckIndeterminate' });
         }
         return {
@@ -566,14 +569,24 @@ function inspectWorkstream(cwd, name, options = {}) {
             summaryCount: counts.summaryCount,
             inMilestone: isDirInCurrentMilestone(dir),
             liveVerificationStatus: verificationResult.status,
+            // #5118: the owner's out-of-set report error, carried to the check below.
+            statusError: completionResult.value.statusError,
             // ADR-3180 §7.4 (#3186): the owner's verdict, read live off disk — never
             // ledger-adjusted (see the phaseFilesCounts map below; the ledger only
             // ever substitutes a 'missing' status with a remembered one, and under
-            // disk-strict neither 'missing' nor 'unrecorded' is ever complete, so
-            // there is nothing for the ledger to override here).
+            // disk-strict 'missing' is never complete, so there is nothing for the
+            // ledger to override here).
             complete: completionResult.value.complete,
         };
     });
+    // #5118 (no write before the error): this inspection WRITES the ledger
+    // below, so a report whose `status` is outside the closed set fails it
+    // first — the owner's own error thrown as-is (like `init *`, `phase *` and
+    // `state *`), which the CLI entry seam projects once into its reason and
+    // message; nothing persisted.
+    const firstStatusError = rawPhaseEntries.find((entry) => entry.statusError)?.statusError;
+    if (firstStatusError)
+        throw firstStatusError;
     // #2645: only the directory Bug #2445's de-dup rollup would actually pick
     // for a phase key may read or write that key's ledger entry. Letting every
     // same-keyed directory (including a stale leftover) write would let a
@@ -604,10 +617,11 @@ function inspectWorkstream(cwd, name, options = {}) {
     const verificationLedger = ledgerRead.entries;
     let ledgerDirty = false;
     for (const winner of ledgerWinnerByKey.values()) {
-        if (winner.liveVerificationStatus === 'missing')
+        const live = winner.liveVerificationStatus;
+        if (live === null || live === VERIFICATION_STATUS.MISSING)
             continue;
-        if (verificationLedger[winner.phaseKey] !== winner.liveVerificationStatus) {
-            verificationLedger[winner.phaseKey] = winner.liveVerificationStatus;
+        if (verificationLedger[winner.phaseKey] !== live) {
+            verificationLedger[winner.phaseKey] = live;
             ledgerDirty = true;
         }
     }
@@ -620,20 +634,16 @@ function inspectWorkstream(cwd, name, options = {}) {
         writeVerificationLedger(wsDir, verificationLedger);
     const phaseFilesCounts = rawPhaseEntries.map(entry => {
         const isLedgerWinner = ledgerWinnerByKey.get(entry.phaseKey) === entry;
+        // A live `missing` on the ledger winner reads the remembered verdict when
+        // there is one. #5118: the former `unrecorded` state ("adopted, never
+        // recorded") is deleted — its only reader, phaseStatusFromFacts, treats it
+        // exactly like `missing` (only `human_needed` changes the ladder, and under
+        // disk-strict neither is ever complete), so it was a dead distinction.
         let verificationStatus = entry.liveVerificationStatus;
-        if (entry.liveVerificationStatus === 'missing' && isLedgerWinner) {
-            if (ledgerRead.state === 'absent') {
-                // State 1: pre-adoption. Exactly today's behavior — 'missing' is
-                // NOT in FAILING_VERIFICATION_STATUSES, so this does not gate.
-                verificationStatus = 'missing';
-            }
-            else {
-                // States 2/3 ('corrupt' or 'ok'): this workstream has adopted the
-                // ledger. A remembered entry wins; no entry fails CLOSED to the
-                // 'unrecorded' sentinel rather than falling open to 'missing'.
-                const remembered = verificationLedger[entry.phaseKey];
-                verificationStatus = remembered !== undefined ? remembered : 'unrecorded';
-            }
+        if (entry.liveVerificationStatus === VERIFICATION_STATUS.MISSING && isLedgerWinner) {
+            const remembered = verificationLedger[entry.phaseKey];
+            if (remembered !== undefined)
+                verificationStatus = remembered;
         }
         return {
             directory: entry.directory,

package/gsd-core/bin/lib/workstream-name-policy.cjs

@@ -26,7 +26,9 @@
  * phase-id.cts's toDir/getPhaseDirFromPhaseId.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
+exports.RESERVED_WORKSTREAM_NAMES = exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
+exports.isReservedWorkstreamName = isReservedWorkstreamName;
+exports.reservedWorkstreamNameMessage = reservedWorkstreamNameMessage;
 exports.normalizeWorkstreamNameInput = normalizeWorkstreamNameInput;
 exports.hasInvalidPathSegment = hasInvalidPathSegment;
 exports.validateActiveWorkstreamName = validateActiveWorkstreamName;
@@ -36,6 +38,34 @@ exports.isValidActiveWorkstreamName = isValidActiveWorkstreamName;
 exports.assertValidActiveWorkstreamName = assertValidActiveWorkstreamName;
 exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = 'Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots';
 const ACTIVE_WORKSTREAM_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/**
+ * Names that pass the charset check but can never name a workstream (#4772).
+ * `none` reads as "no workstream" to every caller that types it, yet the path
+ * layer treated it as a literal directory, so `--ws none` silently resolved
+ * `.planning/workstreams/none/...` (and fell back to the root config). Single
+ * owner: resolveActiveWorkstream and workstream create/set all consume this list.
+ */
+exports.RESERVED_WORKSTREAM_NAMES = Object.freeze(['none']);
+/** True when `name` (trimmed, case-insensitive) is a reserved workstream name. */
+function isReservedWorkstreamName(name) {
+    const value = normalizeWorkstreamNameInput(name);
+    return value !== null && exports.RESERVED_WORKSTREAM_NAMES.includes(value.toLowerCase());
+}
+/**
+ * The error text shared by every site that rejects a reserved name. `source`
+ * (where the name came from: 'cli' | 'env' | 'store') picks a remedy that can
+ * actually be carried out: the rejection happens in the gsd-tools bootstrap
+ * before any verb runs, so advising `workstream set --clear` would fail too.
+ */
+function reservedWorkstreamNameMessage(name, source = null) {
+    const value = normalizeWorkstreamNameInput(name) ?? '';
+    const remedy = source === 'env'
+        ? 'unset GSD_WORKSTREAM for flat mode'
+        : source === 'store'
+            ? 'delete the stale active-workstream pointer for flat mode'
+            : 'omit --ws for flat mode';
+    return `Workstream name '${value}' is reserved and cannot name a workstream; ${remedy}`;
+}
 function normalizeWorkstreamNameInput(name) {
     const value = String(name ?? '').trim();
     return value || null;

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

@@ -50,6 +50,9 @@ function migrateToWorkstreams(cwd, workstreamName) {
     catch {
         throw new Error('Invalid workstream name for migration');
     }
+    if ((0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(workstreamName)) {
+        throw new Error((0, workstream_name_policy_cjs_1.reservedWorkstreamNameMessage)(workstreamName));
+    }
     const baseDir = planningRoot(cwd);
     const wsDir = node_path_1.default.join(baseDir, 'workstreams', workstreamName);
     if (node_fs_1.default.existsSync(node_path_1.default.join(baseDir, 'workstreams'))) {
@@ -101,6 +104,9 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
     if (!slug) {
         error('Invalid workstream name — must contain at least one alphanumeric character');
     }
+    if ((0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(slug)) {
+        error((0, workstream_name_policy_cjs_1.reservedWorkstreamNameMessage)(slug));
+    }
     const baseDir = planningRoot(cwd);
     if (!node_fs_1.default.existsSync(baseDir)) {
         error(`.planning/ directory not found — run ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-project', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} first`);
@@ -331,8 +337,11 @@ function cmdWorkstreamSet(cwd, name, raw) {
         output({ active: null, cleared: true, previous: previous || null }, raw, undefined);
         return;
     }
-    if (!(0, workstream_name_policy_cjs_1.isValidActiveWorkstreamName)(name)) {
-        output({ active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, underscores, or dots' }, raw, undefined);
+    if (!(0, workstream_name_policy_cjs_1.isValidActiveWorkstreamName)(name) || (0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(name)) {
+        const message = (0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(name)
+            ? (0, workstream_name_policy_cjs_1.reservedWorkstreamNameMessage)(name)
+            : 'Workstream name must be alphanumeric, hyphens, underscores, or dots';
+        output({ active: null, error: 'invalid_name', message }, raw, undefined);
         return;
     }
     const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);