@fission-ai/openspec 1.4.1 → 1.6.0-beta.1

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

@@ -1,6 +1,8 @@
+import { buildCodeFenceMask } from './requirement-text.js';
 export function normalizeRequirementName(name) {
     return name.trim();
 }
+/** The canonical requirement header the delta reader recognizes. */
 const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
 /**
  * Extracts the Requirements section from a spec file and parses requirement blocks.
@@ -84,15 +86,26 @@ export function parseDeltaSpec(content) {
     const modifiedLookup = getSectionCaseInsensitive(sections, 'MODIFIED Requirements');
     const removedLookup = getSectionCaseInsensitive(sections, 'REMOVED Requirements');
     const renamedLookup = getSectionCaseInsensitive(sections, 'RENAMED Requirements');
-    const added = parseRequirementBlocksFromSection(addedLookup.body);
-    const modified = parseRequirementBlocksFromSection(modifiedLookup.body);
+    const skippedHeaders = [];
+    const added = parseRequirementBlocksFromSection(addedLookup.body, {
+        section: addedLookup.title,
+        bodyStartLine: addedLookup.bodyStartLine,
+        sink: skippedHeaders,
+    });
+    const modified = parseRequirementBlocksFromSection(modifiedLookup.body, {
+        section: modifiedLookup.title,
+        bodyStartLine: modifiedLookup.bodyStartLine,
+        sink: skippedHeaders,
+    });
     const removedNames = parseRemovedNames(removedLookup.body);
     const renamedPairs = parseRenamedPairs(renamedLookup.body);
+    skippedHeaders.sort((a, b) => a.line - b.line);
     return {
         added,
         modified,
         removed: removedNames,
         renamed: renamedPairs,
+        skippedHeaders,
         sectionPresence: {
             added: addedLookup.found,
             modified: modifiedLookup.found,
@@ -116,28 +129,48 @@ function splitTopLevelSections(content) {
         const current = indices[i];
         const next = indices[i + 1];
         const body = lines.slice(current.index + 1, next ? next.index : lines.length).join('\n');
-        result[current.title] = body;
+        // First body line, 1-based: the header is at 0-based current.index.
+        result[current.title] = { body, bodyStartLine: current.index + 2 };
     }
     return result;
 }
 function getSectionCaseInsensitive(sections, desired) {
     const target = desired.toLowerCase();
-    for (const [title, body] of Object.entries(sections)) {
+    for (const [title, { body, bodyStartLine }] of Object.entries(sections)) {
         if (title.toLowerCase() === target)
-            return { body, found: true };
+            return { title, body, bodyStartLine, found: true };
     }
-    return { body: '', found: false };
+    return { title: desired, body: '', bodyStartLine: 0, found: false };
 }
-function parseRequirementBlocksFromSection(sectionBody) {
+function parseRequirementBlocksFromSection(sectionBody, skipped) {
     if (!sectionBody)
         return [];
     const lines = normalizeLineEndings(sectionBody).split('\n');
+    // Record the non-canonical level-3 headers this reader skips, at the moment
+    // it skips them, so the INFO note describes the reader's real boundaries.
+    // Fence-masked lines are excluded: the body reader treats them as fenced
+    // content, not as headers.
+    const fenceMask = skipped ? buildCodeFenceMask(lines) : undefined;
+    const recordIfSkippedHeader = (index) => {
+        if (!skipped || fenceMask[index])
+            return;
+        const h3 = lines[index].match(/^###\s+(.+?)\s*$/);
+        if (h3 && !REQUIREMENT_HEADER_REGEX.test(lines[index])) {
+            skipped.sink.push({
+                header: h3[1].trim(),
+                section: skipped.section,
+                line: skipped.bodyStartLine + index,
+            });
+        }
+    };
     const blocks = [];
     let i = 0;
     while (i < lines.length) {
         // Seek next requirement header
-        while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i]))
+        while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i])) {
+            recordIfSkippedHeader(i);
             i++;
+        }
         if (i >= lines.length)
             break;
         const headerLine = lines[i];
@@ -150,6 +183,7 @@ function parseRequirementBlocksFromSection(sectionBody) {
         const buf = [headerLine];
         i++;
         while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i]) && !/^##\s+/.test(lines[i])) {
+            recordIfSkippedHeader(i);
             buf.push(lines[i]);
             i++;
         }

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

@@ -0,0 +1,55 @@
+/**
+ * Shared, fence-aware requirement-reading helpers.
+ *
+ * The requirement reader used to be implemented twice — once for main specs
+ * (`MarkdownParser.parseRequirements`) and once for change deltas
+ * (`Validator.extractRequirementText` / `countScenarios`) — and the two drifted
+ * apart. These helpers are the single source of truth for requirement-body
+ * extraction, scenario counting, and `SHALL`/`MUST` detection in
+ * `validate <change>`, `validate <spec>`, and `archive`.
+ */
+/**
+ * Build a per-line mask marking lines that fall inside a fenced code block
+ * (``` ``` ``` or ``` ~~~ ```), including the fence lines themselves. Mirrors the
+ * fence rules markdown uses: a fence opens on the first ```` ```/~~~ ```` of
+ * length >= 3 and closes on a line of the same marker whose length is >= the
+ * opening length, with nothing but whitespace after it.
+ */
+export declare function buildCodeFenceMask(lines: string[]): boolean[];
+/**
+ * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
+ * as whole words so the change-delta reader and the schema-based reader accept
+ * and reject identical text.
+ */
+export declare function containsShallOrMust(text: string): boolean;
+/**
+ * Extract the full requirement body from the lines that follow a
+ * `### Requirement:` header (the lines may include scenarios and fenced code).
+ *
+ * Captures every body line from the start up to the first header found on a
+ * non-fenced line — usually the first `#### Scenario:`, but also a stray `###`
+ * divider the delta reader absorbed into the block — skipping blank lines and
+ * any line inside a fenced code block. `**metadata**:` lines are skipped only
+ * when other body text remains: a requirement written entirely as
+ * `**Constraint**: The system MUST ...` keeps that line as its body. Captured
+ * lines are trimmed and joined with newlines so a requirement whose text wraps
+ * across lines — or whose `SHALL`/`MUST` lands on a later line — is read in
+ * full.
+ */
+export declare function extractRequirementBody(bodyLines: string[]): string;
+/**
+ * Parser/display fallback for a requirement block with no body text. This is
+ * what lets a bare `### The system SHALL ...` header remain readable on the
+ * spec path (the title is the requirement). Validator body-keyword checks for
+ * canonical `### Requirement:` blocks use `extractRequirementBody` directly so
+ * a keyword that appears only in the header still receives the #1156/#1280
+ * body-keyword hint.
+ */
+export declare function extractRequirementText(headerTitle: string, bodyLines: string[]): string;
+/**
+ * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
+ * lines. A `#### Scenario:` that lives inside a fenced example is not a real
+ * scenario and is not counted.
+ */
+export declare function countScenarios(bodyLines: string[]): number;
+//# sourceMappingURL=requirement-text.d.ts.map

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

@@ -0,0 +1,136 @@
+/**
+ * Shared, fence-aware requirement-reading helpers.
+ *
+ * The requirement reader used to be implemented twice — once for main specs
+ * (`MarkdownParser.parseRequirements`) and once for change deltas
+ * (`Validator.extractRequirementText` / `countScenarios`) — and the two drifted
+ * apart. These helpers are the single source of truth for requirement-body
+ * extraction, scenario counting, and `SHALL`/`MUST` detection in
+ * `validate <change>`, `validate <spec>`, and `archive`.
+ */
+/**
+ * Build a per-line mask marking lines that fall inside a fenced code block
+ * (``` ``` ``` or ``` ~~~ ```), including the fence lines themselves. Mirrors the
+ * fence rules markdown uses: a fence opens on the first ```` ```/~~~ ```` of
+ * length >= 3 and closes on a line of the same marker whose length is >= the
+ * opening length, with nothing but whitespace after it.
+ */
+export function buildCodeFenceMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let activeFence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const fence = getFenceMarker(lines[i]);
+        if (!activeFence) {
+            if (fence) {
+                activeFence = fence;
+                mask[i] = true;
+            }
+            continue;
+        }
+        mask[i] = true;
+        if (isClosingFence(lines[i], activeFence)) {
+            activeFence = null;
+        }
+    }
+    return mask;
+}
+function getFenceMarker(line) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (!fenceMatch) {
+        return null;
+    }
+    return {
+        marker: fenceMatch[1][0],
+        length: fenceMatch[1].length,
+    };
+}
+function isClosingFence(line, activeFence) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
+    return Boolean(fenceMatch &&
+        fenceMatch[1][0] === activeFence.marker &&
+        fenceMatch[1].length >= activeFence.length);
+}
+/** Lines that look like `**ID**: ...` / `**Priority**: ...` metadata. */
+const METADATA_LINE = /^\*\*[^*]+\*\*:/;
+/** Any markdown header line — the boundary where a requirement body ends. */
+const HEADER_LINE = /^#{1,6}\s/;
+/**
+ * A level-4 header. Deliberately matches ANY `####` header, not only
+ * `#### Scenario:` — the spec path treats every level-4 child of a requirement
+ * as a scenario, so the delta counter must too (parity). Don't tighten this to
+ * `Scenario:` without changing both paths together.
+ */
+const SCENARIO_HEADER = /^####\s+/;
+/**
+ * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
+ * as whole words so the change-delta reader and the schema-based reader accept
+ * and reject identical text.
+ */
+export function containsShallOrMust(text) {
+    return /\b(SHALL|MUST)\b/.test(text);
+}
+/**
+ * Extract the full requirement body from the lines that follow a
+ * `### Requirement:` header (the lines may include scenarios and fenced code).
+ *
+ * Captures every body line from the start up to the first header found on a
+ * non-fenced line — usually the first `#### Scenario:`, but also a stray `###`
+ * divider the delta reader absorbed into the block — skipping blank lines and
+ * any line inside a fenced code block. `**metadata**:` lines are skipped only
+ * when other body text remains: a requirement written entirely as
+ * `**Constraint**: The system MUST ...` keeps that line as its body. Captured
+ * lines are trimmed and joined with newlines so a requirement whose text wraps
+ * across lines — or whose `SHALL`/`MUST` lands on a later line — is read in
+ * full.
+ */
+export function extractRequirementBody(bodyLines) {
+    const mask = buildCodeFenceMask(bodyLines);
+    const captured = [];
+    const metadata = [];
+    for (let i = 0; i < bodyLines.length; i++) {
+        if (mask[i])
+            continue; // inside a fenced code block
+        const line = bodyLines[i];
+        if (HEADER_LINE.test(line))
+            break; // first scenario or stray divider
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue; // blank
+        if (METADATA_LINE.test(trimmed)) {
+            metadata.push(trimmed); // **ID**: / **Priority**: ...
+            continue;
+        }
+        captured.push(trimmed);
+    }
+    if (captured.length > 0)
+        return captured.join('\n');
+    return metadata.join('\n'); // metadata-only body: the metadata IS the body
+}
+/**
+ * Parser/display fallback for a requirement block with no body text. This is
+ * what lets a bare `### The system SHALL ...` header remain readable on the
+ * spec path (the title is the requirement). Validator body-keyword checks for
+ * canonical `### Requirement:` blocks use `extractRequirementBody` directly so
+ * a keyword that appears only in the header still receives the #1156/#1280
+ * body-keyword hint.
+ */
+export function extractRequirementText(headerTitle, bodyLines) {
+    return extractRequirementBody(bodyLines) || headerTitle.trim();
+}
+/**
+ * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
+ * lines. A `#### Scenario:` that lives inside a fenced example is not a real
+ * scenario and is not counted.
+ */
+export function countScenarios(bodyLines) {
+    const mask = buildCodeFenceMask(bodyLines);
+    let count = 0;
+    for (let i = 0; i < bodyLines.length; i++) {
+        if (mask[i])
+            continue;
+        if (SCENARIO_HEADER.test(bodyLines[i]))
+            count++;
+    }
+    return count;
+}
+//# sourceMappingURL=requirement-text.js.map

package/dist/core/planning-home.d.ts

@@ -1,19 +1,14 @@
-export type PlanningHomeKind = 'repo' | 'workspace';
+export type PlanningHomeKind = 'repo';
 export interface PlanningHome {
     kind: PlanningHomeKind;
     root: string;
     changesDir: string;
     defaultSchema: string;
-    workspace?: {
-        name: string;
-        links: string[];
-    };
 }
 export interface ResolvePlanningHomeOptions {
     startPath?: string;
     allowImplicitRepoRoot?: boolean;
 }
-export declare function findWorkspacePlanningRootSync(startPath?: string): string | null;
 export declare function findRepoPlanningRootSync(startPath?: string): string | null;
 export declare function resolveCurrentPlanningHomeSync(options?: ResolvePlanningHomeOptions): PlanningHome;
 export declare function getChangeDir(planningHome: PlanningHome, changeName: string): string;

package/dist/core/planning-home.js

@@ -1,9 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getWorkspaceChangesDir, readWorkspaceViewStateSync, workspaceStateFileExistsSync, } from './workspace/index.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 const REPO_DEFAULT_SCHEMA = 'spec-driven';
-const WORKSPACE_DEFAULT_SCHEMA = 'workspace-planning';
 function pathExistsAsDirectory(candidatePath) {
     try {
         return fs.statSync(candidatePath).isDirectory();
@@ -36,41 +34,9 @@ function findNearestAncestor(startPath, predicate) {
         currentDir = parentDir;
     }
 }
-export function findWorkspacePlanningRootSync(startPath = process.cwd()) {
-    return findNearestAncestor(startPath, workspaceStateFileExistsSync);
-}
 export function findRepoPlanningRootSync(startPath = process.cwd()) {
     return findNearestAncestor(startPath, (dirPath) => pathExistsAsDirectory(path.join(dirPath, 'openspec')));
 }
-function isSameOrDescendant(rootPath, candidatePath) {
-    const relative = path.relative(rootPath, candidatePath);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-}
-function countPathSegments(candidatePath) {
-    return path.resolve(candidatePath).split(path.sep).filter(Boolean).length;
-}
-function isWindowsLikePath(candidatePath) {
-    return /^[A-Za-z]:[\\/]/.test(candidatePath) || candidatePath.startsWith('\\\\');
-}
-function relativePlanningPath(fromPath, toPath) {
-    if (isWindowsLikePath(fromPath) || isWindowsLikePath(toPath)) {
-        return path.win32.relative(path.win32.normalize(fromPath), path.win32.normalize(toPath));
-    }
-    return path.posix.relative(fromPath.replace(/\\/g, '/'), toPath.replace(/\\/g, '/'));
-}
-function workspacePlanningHome(workspaceRoot) {
-    const viewState = readWorkspaceViewStateSync(workspaceRoot);
-    return {
-        kind: 'workspace',
-        root: workspaceRoot,
-        changesDir: getWorkspaceChangesDir(workspaceRoot),
-        defaultSchema: WORKSPACE_DEFAULT_SCHEMA,
-        workspace: {
-            name: viewState?.name ?? path.basename(workspaceRoot),
-            links: Object.keys(viewState?.links ?? {}).sort((a, b) => a.localeCompare(b)),
-        },
-    };
-}
 function repoPlanningHome(repoRoot) {
     return {
         kind: 'repo',
@@ -82,13 +48,7 @@ function repoPlanningHome(repoRoot) {
 export function resolveCurrentPlanningHomeSync(options = {}) {
     const startPath = options.startPath ?? process.cwd();
     const searchStart = getSearchStartDirectory(startPath);
-    const workspaceRoot = findWorkspacePlanningRootSync(searchStart);
     const repoRoot = findRepoPlanningRootSync(searchStart);
-    if (workspaceRoot && isSameOrDescendant(workspaceRoot, searchStart)) {
-        if (!repoRoot || countPathSegments(workspaceRoot) >= countPathSegments(repoRoot)) {
-            return workspacePlanningHome(workspaceRoot);
-        }
-    }
     if (repoRoot) {
         return repoPlanningHome(repoRoot);
     }
@@ -101,8 +61,7 @@ export function getChangeDir(planningHome, changeName) {
     return FileSystemUtils.joinPath(planningHome.changesDir, changeName);
 }
 export function formatChangeLocation(planningHome, changeName) {
-    const changeDir = getChangeDir(planningHome, changeName);
-    const relative = relativePlanningPath(planningHome.root, changeDir);
-    return relative.length > 0 ? relative : changeDir;
+    // Repo homes always nest changesDir under the root.
+    return path.relative(planningHome.root, getChangeDir(planningHome, changeName));
 }
 //# sourceMappingURL=planning-home.js.map

package/dist/core/profile-sync-drift.js

@@ -12,6 +12,7 @@ export const WORKFLOW_TO_SKILL_DIR = {
     'new': 'openspec-new-change',
     'continue': 'openspec-continue-change',
     'apply': 'openspec-apply-change',
+    'update': 'openspec-update-change',
     'ff': 'openspec-ff-change',
     'sync': 'openspec-sync-specs',
     'archive': 'openspec-archive-change',

package/dist/core/profiles.d.ts

@@ -9,11 +9,11 @@ import type { Profile } from './global-config.js';
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "sync", "archive"];
+export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "update", "sync", "archive"];
 /**
  * All available workflows in the system.
  */
-export declare const ALL_WORKFLOWS: readonly ["propose", "explore", "new", "continue", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard"];
+export declare const ALL_WORKFLOWS: readonly ["propose", "explore", "new", "continue", "apply", "update", "ff", "sync", "archive", "bulk-archive", "verify", "onboard"];
 export type WorkflowId = (typeof ALL_WORKFLOWS)[number];
 export type CoreWorkflowId = (typeof CORE_WORKFLOWS)[number];
 /**

package/dist/core/profiles.js

@@ -8,7 +8,7 @@
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'sync', 'archive'];
+export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'update', 'sync', 'archive'];
 /**
  * All available workflows in the system.
  */
@@ -18,6 +18,7 @@ export const ALL_WORKFLOWS = [
     'new',
     'continue',
     'apply',
+    'update',
     'ff',
     'sync',
     'archive',

package/dist/core/project-config.d.ts

@@ -16,8 +16,18 @@ export declare const ProjectConfigSchema: z.ZodObject<{
     schema: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    store: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+/** Normalized in-memory shape of a referenced store declaration. */
+export interface DeclarationEntry {
+    id: string;
+    /** Clone source rendered into onboarding fixes. */
+    remote?: string;
+}
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema> & {
+    references?: DeclarationEntry[];
+};
+export declare const MAX_CONTEXT_SIZE: number;
 /**
  * Read and parse openspec/config.yaml from project root.
  * Uses resilient parsing - validates each field independently using Zod safeParse.
@@ -61,4 +71,37 @@ export declare function suggestSchemas(invalidSchemaName: string, availableSchem
     name: string;
     isBuiltIn: boolean;
 }[]): string;
+export interface StorePointerRead {
+    /** The declared store id, when present and a string. */
+    value?: string;
+    /** Set when the pointer cannot be trusted: the config file could not be
+     * read as YAML, or the store key is present but not a string. An empty
+     * or comments-only config is NOT malformed - it simply has no pointer. */
+    malformed?: 'unparseable' | 'non_string';
+    /** Absolute path of the config file actually read, or null when none exists. */
+    filePath: string | null;
+}
+/**
+ * Warning-silent targeted read of the `store:` pointer. Used by root
+ * resolution (which must not re-emit the resilient parser's field
+ * warnings) and by `openspec init`'s pointer guard. Unlike
+ * `readProjectConfig`, a malformed value is REPORTED, not dropped —
+ * a dropped pointer would silently flip where work lands.
+ */
+export declare function readStorePointer(projectRoot: string): StorePointerRead;
+/** Shared .yaml/.yml probe used by readProjectConfig and readStorePointer. */
+export declare function resolveConfigFilePath(projectRoot: string): string | null;
+/** Human rendering of a malformed pointer reason, shared by every surface. */
+export declare function storePointerProblem(reason: 'unparseable' | 'non_string'): string;
+export interface OpenSpecDirClassification {
+    /** True when openspec/specs or openspec/changes exists as a directory. */
+    hasPlanningShape: boolean;
+    pointer: StorePointerRead;
+}
+/**
+ * One classification for "real root vs config-only pointer dir", shared
+ * by root resolution and the init pointer guard so they can never
+ * disagree (slice 3.2).
+ */
+export declare function classifyOpenSpecDir(projectRoot: string): OpenSpecDirClassification;
 //# sourceMappingURL=project-config.d.ts.map