@fission-ai/openspec 1.16.0 → 1.16.1

package/dist/cli/index.js

@@ -123,7 +123,7 @@ program
     .action(async (options) => {
     const { getCliInstallInfo, checkForCliUpdate, getCliUpdateCommand, canSelfUpgrade, buildVersionReportLines, } = await import('../core/version-check.js');
     const install = getCliInstallInfo();
-    const update = options.check ? await checkForCliUpdate() : undefined;
+    const update = options.check ? await checkForCliUpdate({ requested: true }) : undefined;
     const command = update?.status === 'available' ? getCliUpdateCommand(install) : null;
     const output = {
         schemaVersion: 1,

package/dist/core/parsers/change-parser.js

@@ -1,6 +1,6 @@
 import { MarkdownParser } from './markdown-parser.js';
 import { buildCodeFenceMask } from './requirement-text.js';
-import { parseDeltaSpec } from './requirement-blocks.js';
+import { parseDeltaSpec, stripClosingSequence } from './requirement-blocks.js';
 import path from 'path';
 import { promises as fs } from 'fs';
 import { discoverSpecFiles } from '../../utils/spec-discovery.js';
@@ -171,7 +171,8 @@ export class ChangeParser extends MarkdownParser {
             const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
             if (headerMatch) {
                 const level = headerMatch[1].length;
-                const title = headerMatch[2].trim();
+                // `## Purpose ##` is the same heading as `## Purpose`.
+                const title = stripClosingSequence(headerMatch[2]);
                 const contentLines = this.getContentUntilNextHeaderFromLines(lines, codeFenceLineMask, i + 1, level);
                 const section = {
                     level,

package/dist/core/parsers/markdown-parser.js

@@ -1,5 +1,5 @@
 import { buildCodeFenceMask, extractRequirementText, hasScenarioBody } from './requirement-text.js';
-import { normalizeRequirementName, scenarioNameFromHeaderText } from './requirement-blocks.js';
+import { normalizeRequirementName, scenarioNameFromHeaderText, stripClosingSequence } from './requirement-blocks.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -68,7 +68,8 @@ export class MarkdownParser {
             const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
             if (headerMatch) {
                 const level = headerMatch[1].length;
-                const title = headerMatch[2].trim();
+                // `## Purpose ##` is the same heading as `## Purpose`.
+                const title = stripClosingSequence(headerMatch[2]);
                 const content = this.getContentUntilNextHeader(i + 1, level);
                 const section = {
                     level,

package/dist/core/parsers/requirement-blocks.d.ts

@@ -10,6 +10,15 @@ export interface RequirementsSectionParts {
     bodyBlocks: RequirementBlock[];
     after: string;
 }
+/**
+ * Drop an ATX heading's closing run of `#`s: `## Purpose ##` renders as
+ * `Purpose`, so the run is not part of the title. As for scenario names, only a
+ * run preceded by a space or tab closes the heading, so `C#` keeps its `#`, and
+ * `[ \t]` rather than `\s` keeps an NBSP-separated run in the title.
+ */
+export declare function stripClosingSequence(title: string): string;
+/** The main spec's `## Requirements` header, closing run allowed (`## Requirements ##`). */
+export declare const REQUIREMENTS_SECTION_HEADER_REGEX: RegExp;
 export declare function normalizeRequirementName(name: string): string;
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
@@ -105,6 +114,15 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+/**
+ * True when an orphaned requirement sits under a `## ... Requirements` header
+ * that is not one of the four delta sections - `## DEPRECATED Requirements`,
+ * `## Add Requirements`, `## Requirements`. Such a header reads as a delta
+ * operation, so its requirements were meant to be applied: validate reports
+ * them as an ERROR and archive refuses (#2195). Orphans under prose sections
+ * (`## Notes`, `## Behavior`) or above the first `## ` stay warnings.
+ */
+export declare function isUnrecognizedDeltaSection(section: string | null): boolean;
 export declare function describeUnappliedContent(content: UnappliedContent, sentenceStart?: boolean): string;
 /**
  * One `#### ` child of a requirement block: its rendered name and its lines,

package/dist/core/parsers/requirement-blocks.js

@@ -1,10 +1,18 @@
 import { buildCodeFenceMask, SCENARIO_HEADER } from './requirement-text.js';
+/**
+ * Drop an ATX heading's closing run of `#`s: `## Purpose ##` renders as
+ * `Purpose`, so the run is not part of the title. As for scenario names, only a
+ * run preceded by a space or tab closes the heading, so `C#` keeps its `#`, and
+ * `[ \t]` rather than `\s` keeps an NBSP-separated run in the title.
+ */
+export function stripClosingSequence(title) {
+    return title.replace(/[ \t]+#+[ \t]*$/, '').trim();
+}
+/** The main spec's `## Requirements` header, closing run allowed (`## Requirements ##`). */
+export const REQUIREMENTS_SECTION_HEADER_REGEX = /^##\s+Requirements(?:[ \t]+#+)?\s*$/i;
 export function normalizeRequirementName(name) {
-    // An ATX heading may end in a closing run of `#`s: `### Requirement: Foo ###`
-    // renders as `Foo`, so the run is not part of the name. As for scenario names,
-    // only a run preceded by a space or tab closes the heading, so `C#` keeps its
-    // `#`, and `[ \t]` rather than `\s` keeps an NBSP-separated run in the name.
-    return name.replace(/[ \t]+#+[ \t]*$/, '').trim();
+    // `### Requirement: Foo ###` names the requirement `Foo`.
+    return stripClosingSequence(name);
 }
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
@@ -26,7 +34,7 @@ export function extractRequirementsSection(content) {
     const normalized = normalizeLineEndings(content);
     const lines = normalized.split('\n');
     const fenceMask = buildCodeFenceMask(lines);
-    const reqHeaderIndex = lines.findIndex((l, i) => !fenceMask[i] && /^##\s+Requirements\s*$/i.test(l));
+    const reqHeaderIndex = lines.findIndex((l, i) => !fenceMask[i] && REQUIREMENTS_SECTION_HEADER_REGEX.test(l));
     if (reqHeaderIndex === -1) {
         // No requirements section; create an empty one at the end
         const before = content.trimEnd();
@@ -154,6 +162,19 @@ export function parseDeltaSpec(content) {
  * under it would be dropped without this warning.
  */
 const DELTA_SECTION_TITLES = new Set(['ADDED Requirements', 'MODIFIED Requirements', 'REMOVED Requirements', 'RENAMED Requirements'].map((title) => title.toLowerCase()));
+/**
+ * True when an orphaned requirement sits under a `## ... Requirements` header
+ * that is not one of the four delta sections - `## DEPRECATED Requirements`,
+ * `## Add Requirements`, `## Requirements`. Such a header reads as a delta
+ * operation, so its requirements were meant to be applied: validate reports
+ * them as an ERROR and archive refuses (#2195). Orphans under prose sections
+ * (`## Notes`, `## Behavior`) or above the first `## ` stay warnings.
+ */
+export function isUnrecognizedDeltaSection(section) {
+    return (section !== null &&
+        /\brequirements?$/i.test(section) &&
+        !DELTA_SECTION_TITLES.has(section.toLowerCase()));
+}
 /**
  * Every canonical `### Requirement:` header that is not inside a delta section,
  * in document order.
@@ -161,10 +182,12 @@ const DELTA_SECTION_TITLES = new Set(['ADDED Requirements', 'MODIFIED Requiremen
  * Walks the whole file rather than the parsed sections so a requirement written
  * ABOVE the first `## ` header is reported too - it is dropped just as silently
  * as one under `## Notes`. Fenced lines are skipped, so a requirement shown
- * inside a markdown example is not mistaken for an authored one.
+ * inside a markdown example is not mistaken for an authored one, and so are
+ * HTML comments, so a commented-out draft is not reported as dropped.
  */
 function findOrphanedRequirements(lines, fenceMask) {
     const orphans = [];
+    const masked = maskHtmlComments(lines, fenceMask);
     let section = null;
     for (let i = 0; i < lines.length; i++) {
         if (fenceMask[i])
@@ -172,12 +195,12 @@ function findOrphanedRequirements(lines, fenceMask) {
         // The same `## ` test splitTopLevelSections uses, so both agree on sections.
         const sectionMatch = lines[i].match(/^(##)\s+(.+)$/);
         if (sectionMatch) {
-            section = sectionMatch[2].trim();
+            section = stripClosingSequence(sectionMatch[2]);
             continue;
         }
         if (section !== null && DELTA_SECTION_TITLES.has(section.toLowerCase()))
             continue;
-        const header = lines[i].match(REQUIREMENT_HEADER_REGEX);
+        const header = masked[i].match(REQUIREMENT_HEADER_REGEX);
         if (header) {
             orphans.push({
                 name: normalizeRequirementName(header[1]),
@@ -201,18 +224,24 @@ export function describeUnappliedContent(content, sentenceStart = false) {
  * (warned about separately), REMOVED/RENAMED bodies, and stray `###` headers
  * before the first requirement (INFO since #498) are not reported.
  */
-function findUnappliedContent(lines, fenceMask) {
-    // Blank out comments outside fences, keeping line count; an unterminated one
-    // runs to EOF. Comments only decide whether a line holds text: sections come
-    // from the same split the merge reads, where a `## ` line inside a comment is
-    // still a boundary. Fenced lines keep their text, so a `<!--` in a code sample
-    // never hides what follows the fence.
+/**
+ * Blank out comments outside fences, keeping line count; an unterminated one
+ * runs to EOF. Fenced lines keep their text, so a `<!--` in a code sample never
+ * hides what follows the fence.
+ */
+function maskHtmlComments(lines, fenceMask) {
     const comments = lines
         .map((line, i) => (fenceMask[i] ? '' : line))
         .join('\n')
         .replace(/<!--[\s\S]*?(?:--!?>|$)/g, (m) => m.replace(/[^\n]/g, ' '))
         .split('\n');
-    const masked = lines.map((line, i) => (fenceMask[i] ? line : comments[i]));
+    return lines.map((line, i) => (fenceMask[i] ? line : comments[i]));
+}
+function findUnappliedContent(lines, fenceMask) {
+    // Comments only decide whether a line holds text: sections come from the
+    // same split the merge reads, where a `## ` line inside a comment is still a
+    // boundary.
+    const masked = maskHtmlComments(lines, fenceMask);
     const sections = splitTopLevelSections(lines, fenceMask);
     const firstText = (from, to, skip) => {
         for (let i = from; i < to; i++)
@@ -260,7 +289,8 @@ function splitTopLevelSections(lines, fenceMask) {
             continue;
         const m = lines[i].match(/^(##)\s+(.+)$/);
         if (m) {
-            indices.push({ title: m[2].trim(), index: i });
+            // `## ADDED Requirements ##` is the same section as `## ADDED Requirements`.
+            indices.push({ title: stripClosingSequence(m[2]), index: i });
         }
     }
     for (let i = 0; i < indices.length; i++) {

package/dist/core/parsers/spec-structure.js

@@ -1,8 +1,7 @@
 import { buildCodeFenceMask } from './code-fence.js';
-import { normalizeRequirementName } from './requirement-blocks.js';
-const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
+import { normalizeRequirementName, REQUIREMENTS_SECTION_HEADER_REGEX as REQUIREMENTS_SECTION_HEADER, } from './requirement-blocks.js';
 const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
-const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
+const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements(?:[ \t]+#+)?\s*$/i;
 const REQUIREMENT_HEADER = /^###\s*Requirement:\s*(.+)\s*$/i;
 export function findMainSpecStructureIssues(content) {
     const normalized = content.replace(/\r\n?/g, '\n');

package/dist/core/specs-apply.js

@@ -8,7 +8,7 @@ import { promises as fs } from 'fs';
 import { randomUUID } from 'crypto';
 import path from 'path';
 import chalk from 'chalk';
-import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, foldRequirementName, isUnrecognizedDeltaSection, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { buildCodeFenceMask } from './parsers/code-fence.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
@@ -137,7 +137,15 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // A well-formed requirement written outside every delta section is not
     // applied. Say so here as well as in validate: archive is the last point at
     // which the author can still notice, and the block reads exactly like one
-    // that would have applied.
+    // that would have applied. Under an unrecognized `## ... Requirements`
+    // header it was meant as a delta operation, so refuse rather than drop it -
+    // the same verdict validate gives (#2195).
+    const misplaced = plan.orphanedRequirements.find((o) => isUnrecognizedDeltaSection(o.section));
+    if (misplaced) {
+        throw new Error(`${specName} validation failed - requirement "${misplaced.name}" (line ${misplaced.line}) is under ` +
+            `"## ${misplaced.section}", which is not a delta section, so it would not be applied. ` +
+            `Move it under ADDED/MODIFIED/REMOVED/RENAMED Requirements.`);
+    }
     for (const orphan of plan.orphanedRequirements) {
         const where = orphan.section
             ? `under "## ${orphan.section}"`
@@ -1141,7 +1149,7 @@ function extractPurposeSection(content) {
     const masked = maskHtmlComments(normalized).split('\n');
     const fenceMask = buildCodeFenceMask(masked);
     const isStructural = (i) => !fenceMask[i];
-    const start = masked.findIndex((line, i) => isStructural(i) && /^##\s+Purpose\s*$/i.test(line));
+    const start = masked.findIndex((line, i) => isStructural(i) && /^##\s+Purpose(?:[ \t]+#+)?\s*$/i.test(line));
     if (start === -1)
         return undefined;
     let end = masked.length;

package/dist/core/validation/purpose-placeholder.js

@@ -25,7 +25,7 @@ const MARKER_PUNCTUATION = '(?=[ \\t]*(?:$|\\n|[:\\-\u2013\u2014.,;()\\[\\]{}]))
 const LEADING_MARKER_SHOUTED = new RegExp(`^(?:TBD|TODO)${WORD_END}`, 'u');
 /** Any other case: a marker only when punctuation or the line end says so. */
 const LEADING_MARKER_PUNCTUATED = new RegExp(`^(?:TBD|TODO)${WORD_END}${MARKER_PUNCTUATION}`, 'iu');
-const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
+const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose(?:[ \t]+#+)?[ \t]*$/i;
 const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
 /**
  * The lines of `text` that sit outside a fenced code block, with line endings

package/dist/core/validation/validator.js

@@ -5,7 +5,7 @@ import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, parseScenarioBlocks, isScenarioLabeledHeader, describeUnappliedContent, } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, parseScenarioBlocks, isScenarioLabeledHeader, describeUnappliedContent, isUnrecognizedDeltaSection, } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, hasScenarioBody, scenarioStepCoverage, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
@@ -195,12 +195,15 @@ export class Validator {
                 // ignored - reported as a WARNING rather than an ERROR because a
                 // handful of pre-format archived changes still carry this shape, and
                 // the fix is to move the block, not to reject the change outright.
+                // Under an unrecognized `## ... Requirements` header it is an ERROR:
+                // that header reads as a delta operation, so the requirement was meant
+                // to be applied and archive refuses it too (#2195).
                 for (const orphan of plan.orphanedRequirements) {
                     const where = orphan.section
                         ? `under "## ${orphan.section}"`
                         : 'above the first "## " section';
                     issues.push({
-                        level: 'WARNING',
+                        level: isUnrecognizedDeltaSection(orphan.section) ? 'ERROR' : 'WARNING',
                         path: entryPath,
                         line: orphan.line,
                         message: `Requirement "${orphan.name}" is ${where}, which is not a delta section, so it is ignored. Move it under "## ADDED Requirements", "## MODIFIED Requirements", "## REMOVED Requirements", or "## RENAMED Requirements".`,

package/dist/core/version-check.d.ts

@@ -28,9 +28,12 @@ export interface CliUpdateCheck {
 }
 /**
  * Checks the registry while preserving enough detail for callers to explain
- * why no newer version was reported. Never throws.
+ * why no newer version was reported. Never throws. Pass `requested` only when
+ * the user explicitly asked for the check.
  */
-export declare function checkForCliUpdate(): Promise<CliUpdateCheck>;
+export declare function checkForCliUpdate(options?: {
+    requested?: boolean;
+}): Promise<CliUpdateCheck>;
 /**
  * Returns the published version when the installed CLI is behind it, otherwise
  * null. Kept as the compatibility surface used by `openspec update`.

package/dist/core/version-check.js

@@ -57,15 +57,21 @@ function standaloneUpgradeCommand() {
  * tests, an explicit escape hatch for anyone offline or air-gapped, and the
  * same privacy signals telemetry already honors — a user who set DO_NOT_TRACK
  * or telemetry.enabled false did not agree to a different outbound request.
+ *
+ * `requested` is an explicit `openspec version --check`: the user asked for
+ * this one request, so neither the telemetry signals nor CI detection apply
+ * to it. Only the update-check opt-out and the test guard still stop it.
  */
-function isCheckEnabled() {
+function isCheckEnabled(requested) {
     if (process.env.OPENSPEC_NO_UPDATE_CHECK !== undefined)
         return false;
-    if (isTelemetryOptedOutByEnv())
+    if (process.env.NODE_ENV === 'test')
         return false;
+    if (requested)
+        return true;
     if (isCiEnvironment())
         return false;
-    if (process.env.NODE_ENV === 'test')
+    if (isTelemetryOptedOutByEnv())
         return false;
     // Same config opt-out as telemetry (env remains the hard override above).
     if (getGlobalConfig().telemetry?.enabled === false)
@@ -180,40 +186,28 @@ export function compareVersions(a, b) {
     return comparePrerelease(left.prerelease, right.prerelease);
 }
 /**
- * Reads the `latest` dist-tag. Sends no custom Accept header: the registry
- * answers `/<pkg>/latest` with 406 for npm's abbreviated-metadata type, which
- * it only serves on the full packument.
+ * One GET, finished by `deadline`. Uses node:http(s) rather than fetch so the
+ * timeout can destroy the socket. Aborting a fetch that is still completing
+ * its TCP handshake — a firewall dropping packets, a captive portal — leaves
+ * the connect handle open and the CLI cannot exit until the OS gives up, long
+ * after the hint has printed.
  *
- * Uses node:http(s) rather than fetch so the timeout can destroy the socket.
- * Aborting a fetch that is still completing its TCP handshake — a firewall
- * dropping packets, a captive portal — leaves the connect handle open and the
- * CLI cannot exit until the OS gives up, long after the hint has printed.
+ * Resolves the final status (with the body only for a 200), or null on any
+ * network failure, an oversized body, or a redirect that cannot be followed.
+ * With `followRedirects: false` a redirect is returned as-is, unread.
  */
-function fetchLatestVersion() {
+function httpsGet(url, options) {
     return new Promise((resolve) => {
         let settled = false;
         let timer;
-        const finish = (version) => {
+        const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             if (timer)
                 clearTimeout(timer);
-            resolve(version);
+            resolve(result);
         };
-        let url;
-        try {
-            const resolved = registryUrl();
-            if (resolved === null) {
-                resolve(null);
-                return;
-            }
-            url = new URL(resolved);
-        }
-        catch {
-            resolve(null);
-            return;
-        }
         // Mirrors and corporate front-ends redirect; without following one the
         // check would be permanently and silently dead for them.
         let redirectsLeft = MAX_REDIRECTS;
@@ -229,6 +223,10 @@ function fetchLatestVersion() {
                 if (status >= 300 && status < 400 && location) {
                     response.resume();
                     request.destroy();
+                    if (!options.followRedirects) {
+                        finish({ status, body: '' });
+                        return;
+                    }
                     if (redirectsLeft <= 0) {
                         finish(null);
                         return;
@@ -256,29 +254,20 @@ function fetchLatestVersion() {
                 if (status !== 200) {
                     response.resume();
                     request.destroy();
-                    finish(null);
+                    finish({ status, body: '' });
                     return;
                 }
                 let body = '';
                 response.setEncoding('utf-8');
                 response.on('data', (chunk) => {
                     body += chunk;
-                    // The dist-tag document is small; refuse to buffer a firehose.
+                    // Version documents are small; refuse to buffer a firehose.
                     if (body.length > MAX_RESPONSE_BYTES) {
                         request.destroy();
                         finish(null);
                     }
                 });
-                response.on('end', () => {
-                    try {
-                        const parsed = JSON.parse(body);
-                        const version = parsed.version;
-                        finish(typeof version === 'string' && SAFE_VERSION.test(version) ? version : null);
-                    }
-                    catch {
-                        finish(null);
-                    }
-                });
+                response.on('end', () => finish({ status, body }));
                 response.on('error', () => finish(null));
             });
             activeRequest = request;
@@ -292,22 +281,105 @@ function fetchLatestVersion() {
                 timer = setTimeout(() => {
                     activeRequest?.destroy();
                     finish(null);
-                }, REQUEST_TIMEOUT_MS);
+                }, Math.max(0, options.deadline - Date.now()));
             }
         };
         send(url);
     });
 }
+/**
+ * Reads the `latest` dist-tag. Sends no custom Accept header: the registry
+ * answers `/<pkg>/latest` with 406 for npm's abbreviated-metadata type, which
+ * it only serves on the full packument.
+ */
+async function fetchLatestVersion() {
+    let url;
+    try {
+        const resolved = registryUrl();
+        if (resolved === null)
+            return null;
+        url = new URL(resolved);
+    }
+    catch {
+        return null;
+    }
+    const response = await httpsGet(url, {
+        deadline: Date.now() + REQUEST_TIMEOUT_MS,
+        followRedirects: true,
+    });
+    if (!response || response.status !== 200)
+        return null;
+    try {
+        const version = JSON.parse(response.body).version;
+        return typeof version === 'string' && SAFE_VERSION.test(version) ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where `openspec install` gets the standalone binary: install.sh and
+ * install.ps1 default to this releases page.
+ */
+const RELEASES_URL = 'https://github.com/Fission-AI/OpenSpec/releases';
+/**
+ * The release `openspec install` would install, found the way install.sh and
+ * install.ps1 find it: stable tags from the releases feed, newest first, and
+ * the first one whose SHA256SUMS (uploaded last) exists. npm's `latest` is not
+ * the answer here: it is published minutes before the standalone files are
+ * attached to the GitHub release (and for good, if that job fails), and
+ * offering a version the installer cannot get makes `openspec install`
+ * quietly reinstall the old one.
+ *
+ * Stops at the first tag that is not newer than this CLI, since nothing from
+ * there on is an update, so an up-to-date binary costs only the feed request.
+ * Null when the answer is not known: the feed or a probe failed or ran out of
+ * time, or every listed newer release is still incomplete.
+ */
+async function fetchLatestStandaloneRelease() {
+    // The same total budget as the registry check, across every request.
+    const deadline = Date.now() + REQUEST_TIMEOUT_MS;
+    const feed = await httpsGet(new URL(`${RELEASES_URL}.atom`), { deadline, followRedirects: true });
+    if (!feed || feed.status !== 200)
+        return null;
+    const versions = [
+        ...new Set(Array.from(feed.body.matchAll(/\/releases\/tag\/v(\d+\.\d+\.\d+)"/g), (m) => m[1])),
+    ].filter((version) => SAFE_VERSION.test(version));
+    for (const version of versions) {
+        if (compareVersions(version, OPENSPEC_VERSION) <= 0)
+            return version;
+        // GitHub answers for an attached file with a redirect to its storage, so
+        // the file itself never needs downloading.
+        const probe = await httpsGet(new URL(`${RELEASES_URL}/download/v${version}/SHA256SUMS`), {
+            deadline,
+            followRedirects: false,
+        });
+        if (!probe)
+            return null;
+        if (probe.status === 200 || (probe.status >= 300 && probe.status < 400))
+            return version;
+        // Still being prepared: the installer moves on to the next release too.
+        if (probe.status === 404)
+            continue;
+        // Rate-limited or failing: not knowing beats a wrong answer.
+        return null;
+    }
+    return null;
+}
 /**
  * Checks the registry while preserving enough detail for callers to explain
- * why no newer version was reported. Never throws.
+ * why no newer version was reported. Never throws. Pass `requested` only when
+ * the user explicitly asked for the check.
  */
-export async function checkForCliUpdate() {
-    if (!isCheckEnabled() || registryUrl() === null) {
+export async function checkForCliUpdate(options = {}) {
+    // The standalone binary updates from GitHub releases, not npm, so the
+    // registry neither answers for it nor can disable its check.
+    const standalone = standaloneBinaryPath !== null;
+    if (!isCheckEnabled(options.requested === true) || (!standalone && registryUrl() === null)) {
         return { status: 'disabled', latest: null };
     }
     try {
-        const latest = await fetchLatestVersion();
+        const latest = standalone ? await fetchLatestStandaloneRelease() : await fetchLatestVersion();
         if (!latest)
             return { status: 'offline', latest: null };
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -43,15 +43,15 @@
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
-    "@types/node": "^20.19.43",
+    "@types/node": "^22.12.0",
     "@types/picomatch": "^4.0.3",
-    "@vitest/ui": "^4.1.12",
+    "@vitest/ui": "^5.0.3",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
     "vite": "^8.3.5",
-    "vitest": "^4.1.12"
+    "vitest": "^5.0.3"
   },
   "dependencies": {
     "@inquirer/core": "^12.0.0",