@fission-ai/openspec 1.5.0 → 1.6.0

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

@@ -1,4 +1,5 @@
 import { MarkdownParser } from './markdown-parser.js';
+import { buildCodeFenceMask } from './requirement-text.js';
 import path from 'path';
 import { promises as fs } from 'fs';
 export class ChangeParser extends MarkdownParser {
@@ -148,7 +149,7 @@ export class ChangeParser extends MarkdownParser {
     parseSectionsFromContent(content) {
         const normalizedContent = ChangeParser.normalizeContent(content);
         const lines = normalizedContent.split('\n');
-        const codeFenceLineMask = ChangeParser.buildCodeFenceMask(lines);
+        const codeFenceLineMask = buildCodeFenceMask(lines);
         const sections = [];
         const stack = [];
         for (let i = 0; i < lines.length; i++) {

package/dist/core/parsers/markdown-parser.d.ts

@@ -11,9 +11,6 @@ export declare class MarkdownParser {
     private currentLine;
     constructor(content: string);
     protected static normalizeContent(content: string): string;
-    protected static buildCodeFenceMask(lines: string[]): boolean[];
-    private static getFenceMarker;
-    private static isClosingFence;
     parseSpec(name: string): Spec;
     parseChange(name: string): Change;
     protected parseSections(): Section[];

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

@@ -1,3 +1,4 @@
+import { buildCodeFenceMask, extractRequirementText } from './requirement-text.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -5,47 +6,12 @@ export class MarkdownParser {
     constructor(content) {
         const normalized = MarkdownParser.normalizeContent(content);
         this.lines = normalized.split('\n');
-        this.codeFenceLineMask = MarkdownParser.buildCodeFenceMask(this.lines);
+        this.codeFenceLineMask = buildCodeFenceMask(this.lines);
         this.currentLine = 0;
     }
     static normalizeContent(content) {
         return content.replace(/\r\n?/g, '\n');
     }
-    static buildCodeFenceMask(lines) {
-        const mask = new Array(lines.length).fill(false);
-        let activeFence = null;
-        for (let i = 0; i < lines.length; i++) {
-            const fence = MarkdownParser.getFenceMarker(lines[i]);
-            if (!activeFence) {
-                if (fence) {
-                    activeFence = fence;
-                    mask[i] = true;
-                }
-                continue;
-            }
-            mask[i] = true;
-            if (MarkdownParser.isClosingFence(lines[i], activeFence)) {
-                activeFence = null;
-            }
-        }
-        return mask;
-    }
-    static getFenceMarker(line) {
-        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
-        if (!fenceMatch) {
-            return null;
-        }
-        return {
-            marker: fenceMatch[1][0],
-            length: fenceMatch[1].length,
-        };
-    }
-    static isClosingFence(line, activeFence) {
-        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
-        return Boolean(fenceMatch &&
-            fenceMatch[1][0] === activeFence.marker &&
-            fenceMatch[1].length >= activeFence.length);
-    }
     parseSpec(name) {
         const sections = this.parseSections();
         const purpose = this.findSection(sections, 'Purpose')?.content || '';
@@ -149,29 +115,9 @@ export class MarkdownParser {
     parseRequirements(section) {
         const requirements = [];
         for (const child of section.children) {
-            // Extract requirement text from first non-empty content line, fall back to heading
-            let text = child.title;
-            // Get content before any child sections (scenarios)
-            if (child.content.trim()) {
-                // Split content into lines and find content before any child headers
-                const lines = child.content.split('\n');
-                const contentBeforeChildren = [];
-                for (const line of lines) {
-                    // Stop at child headers (scenarios start with ####)
-                    if (line.trim().startsWith('#')) {
-                        break;
-                    }
-                    contentBeforeChildren.push(line);
-                }
-                // Find first non-empty line
-                const directContent = contentBeforeChildren.join('\n').trim();
-                if (directContent) {
-                    const firstLine = directContent.split('\n').find(l => l.trim());
-                    if (firstLine) {
-                        text = firstLine.trim();
-                    }
-                }
-            }
+            // Read the requirement text via the shared reader (multi-line, fence- and
+            // metadata-aware, with the shared header-title fallback for empty bodies).
+            const text = extractRequirementText(child.title, child.content.split('\n'));
             const scenarios = this.parseScenarios(child);
             requirements.push({
                 text,

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

@@ -15,6 +15,16 @@ export declare function normalizeRequirementName(name: string): string;
  * Extracts the Requirements section from a spec file and parses requirement blocks.
  */
 export declare function extractRequirementsSection(content: string): RequirementsSectionParts;
+/**
+ * A level-3 header inside `## ADDED`/`## MODIFIED Requirements` that is not a
+ * canonical `### Requirement:` header, recorded at the moment the delta reader
+ * skips over it. Surfaced as an INFO note by `validate <change>` (#498).
+ */
+export interface SkippedHeader {
+    header: string;
+    section: string;
+    line: number;
+}
 export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
@@ -23,6 +33,7 @@ export interface DeltaPlan {
         from: string;
         to: string;
     }>;
+    skippedHeaders: SkippedHeader[];
     sectionPresence: {
         added: boolean;
         modified: boolean;

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/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/schemas/base.schema.js

@@ -4,9 +4,14 @@ export const ScenarioSchema = z.object({
     rawText: z.string().min(1, VALIDATION_MESSAGES.SCENARIO_EMPTY),
 });
 export const RequirementSchema = z.object({
+    // SHALL/MUST body-keyword enforcement lives in the imperative validator
+    // (Validator.applySpecRules), not here: the parser collapses the requirement
+    // header into `text`, so a Zod refine on `text` cannot tell "keyword in header
+    // only" from "keyword in body" and emits a misleading generic error. The
+    // validator recovers the header and emits the targeted hint for both the
+    // main-spec and change-delta paths (#1156).
     text: z.string()
-        .min(1, VALIDATION_MESSAGES.REQUIREMENT_EMPTY)
-        .refine((text) => text.includes('SHALL') || text.includes('MUST'), VALIDATION_MESSAGES.REQUIREMENT_NO_SHALL),
+        .min(1, VALIDATION_MESSAGES.REQUIREMENT_EMPTY),
     scenarios: z.array(ScenarioSchema)
         .min(1, VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS),
 });

package/dist/core/shared/allowed-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-approved tools for generated skills and slash commands, emitted as the
+ * `allowed-tools` frontmatter field (Agent Skills standard for SKILL.md;
+ * same field for Claude Code slash commands). Scoped to the OpenSpec CLI so
+ * agents that honor it stop prompting on each `openspec` call; the field
+ * only pre-approves — it does not restrict — so any other tool a skill or
+ * command needs (Read, Write, arbitrary Bash for builds/tests) stays
+ * available under the user's normal permission settings. Tools that don't
+ * recognize the field ignore it.
+ */
+export declare const OPENSPEC_CLI_ALLOWED_TOOLS = "Bash(openspec:*)";
+//# sourceMappingURL=allowed-tools.d.ts.map

package/dist/core/shared/allowed-tools.js

@@ -0,0 +1,12 @@
+/**
+ * Pre-approved tools for generated skills and slash commands, emitted as the
+ * `allowed-tools` frontmatter field (Agent Skills standard for SKILL.md;
+ * same field for Claude Code slash commands). Scoped to the OpenSpec CLI so
+ * agents that honor it stop prompting on each `openspec` call; the field
+ * only pre-approves — it does not restrict — so any other tool a skill or
+ * command needs (Read, Write, arbitrary Bash for builds/tests) stays
+ * available under the user's normal permission settings. Tools that don't
+ * recognize the field ignore it.
+ */
+export const OPENSPEC_CLI_ALLOWED_TOOLS = 'Bash(openspec:*)';
+//# sourceMappingURL=allowed-tools.js.map

package/dist/core/shared/skill-generation.js

@@ -3,7 +3,8 @@
  *
  * Shared utilities for generating skill and command files.
  */
-import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, } from '../templates/skill-templates.js';
+import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getUpdateChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxUpdateCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, } from '../templates/skill-templates.js';
+import { OPENSPEC_CLI_ALLOWED_TOOLS } from './allowed-tools.js';
 /**
  * Gets skill templates with their directory names, optionally filtered by workflow IDs.
  *
@@ -15,6 +16,7 @@ export function getSkillTemplates(workflowFilter) {
         { template: getNewChangeSkillTemplate(), dirName: 'openspec-new-change', workflowId: 'new' },
         { template: getContinueChangeSkillTemplate(), dirName: 'openspec-continue-change', workflowId: 'continue' },
         { template: getApplyChangeSkillTemplate(), dirName: 'openspec-apply-change', workflowId: 'apply' },
+        { template: getUpdateChangeSkillTemplate(), dirName: 'openspec-update-change', workflowId: 'update' },
         { template: getFfChangeSkillTemplate(), dirName: 'openspec-ff-change', workflowId: 'ff' },
         { template: getSyncSpecsSkillTemplate(), dirName: 'openspec-sync-specs', workflowId: 'sync' },
         { template: getArchiveChangeSkillTemplate(), dirName: 'openspec-archive-change', workflowId: 'archive' },
@@ -39,6 +41,7 @@ export function getCommandTemplates(workflowFilter) {
         { template: getOpsxNewCommandTemplate(), id: 'new' },
         { template: getOpsxContinueCommandTemplate(), id: 'continue' },
         { template: getOpsxApplyCommandTemplate(), id: 'apply' },
+        { template: getOpsxUpdateCommandTemplate(), id: 'update' },
         { template: getOpsxFfCommandTemplate(), id: 'ff' },
         { template: getOpsxSyncCommandTemplate(), id: 'sync' },
         { template: getOpsxArchiveCommandTemplate(), id: 'archive' },
@@ -82,6 +85,7 @@ export function generateSkillContent(template, generatedByVersion, transformInst
     return `---
 name: ${template.name}
 description: ${template.description}
+allowed-tools: ${OPENSPEC_CLI_ALLOWED_TOOLS}
 license: ${template.license || 'MIT'}
 compatibility: ${template.compatibility || 'Requires openspec CLI.'}
 metadata:

package/dist/core/shared/tool-detection.d.ts

@@ -6,12 +6,12 @@
 /**
  * Names of skill directories created by openspec init.
  */
-export declare const SKILL_NAMES: readonly ["openspec-explore", "openspec-new-change", "openspec-continue-change", "openspec-apply-change", "openspec-ff-change", "openspec-sync-specs", "openspec-archive-change", "openspec-bulk-archive-change", "openspec-verify-change", "openspec-onboard", "openspec-propose"];
+export declare const SKILL_NAMES: readonly ["openspec-explore", "openspec-new-change", "openspec-continue-change", "openspec-apply-change", "openspec-update-change", "openspec-ff-change", "openspec-sync-specs", "openspec-archive-change", "openspec-bulk-archive-change", "openspec-verify-change", "openspec-onboard", "openspec-propose"];
 export type SkillName = (typeof SKILL_NAMES)[number];
 /**
  * IDs of command templates created by openspec init.
  */
-export declare const COMMAND_IDS: readonly ["explore", "new", "continue", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard", "propose"];
+export declare const COMMAND_IDS: readonly ["explore", "new", "continue", "apply", "update", "ff", "sync", "archive", "bulk-archive", "verify", "onboard", "propose"];
 export type CommandId = (typeof COMMAND_IDS)[number];
 /**
  * Status of skill configuration for a tool.

package/dist/core/shared/tool-detection.js

@@ -14,6 +14,7 @@ export const SKILL_NAMES = [
     'openspec-new-change',
     'openspec-continue-change',
     'openspec-apply-change',
+    'openspec-update-change',
     'openspec-ff-change',
     'openspec-sync-specs',
     'openspec-archive-change',
@@ -30,6 +31,7 @@ export const COMMAND_IDS = [
     'new',
     'continue',
     'apply',
+    'update',
     'ff',
     'sync',
     'archive',

package/dist/core/specs-apply.js

@@ -207,7 +207,8 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // MODIFIED
     for (const mod of plan.modified) {
         const key = normalizeRequirementName(mod.name);
-        if (!nameToBlock.has(key)) {
+        const currentBlock = nameToBlock.get(key);
+        if (!currentBlock) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
         }
         // Replace block with provided raw (ensure header line matches key)
@@ -215,6 +216,10 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }
+        const missingScenarios = findMissingCurrentScenarios(currentBlock, mod);
+        if (missingScenarios.length > 0) {
+            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${missingScenarios.map(name => `"${name}"`).join(', ')}. Refresh the change spec before archiving to avoid dropping scenarios.`);
+        }
         nameToBlock.set(key, mod);
     }
     // ADDED
@@ -290,6 +295,35 @@ export function buildSpecSkeleton(specFolderName, changeName) {
     const titleBase = specFolderName;
     return `# ${titleBase} Specification\n\n## Purpose\nTBD - created by archiving change ${changeName}. Update Purpose after archive.\n\n## Requirements\n`;
 }
+function findMissingCurrentScenarios(current, incoming) {
+    const incomingScenarioNames = new Set(parseScenarioBlocks(incoming.raw).map((scenario) => scenario.name));
+    return parseScenarioBlocks(current.raw)
+        .filter((scenario) => !incomingScenarioNames.has(scenario.name))
+        .map((scenario) => scenario.name);
+}
+function parseScenarioBlocks(requirementRaw) {
+    const lines = requirementRaw.replace(/\r\n?/g, '\n').split('\n');
+    const scenarios = [];
+    let index = 0;
+    while (index < lines.length) {
+        const headerMatch = lines[index].match(/^####\s*Scenario:\s*(.+)\s*$/);
+        if (!headerMatch) {
+            index++;
+            continue;
+        }
+        const start = index;
+        const name = headerMatch[1].trim();
+        index++;
+        while (index < lines.length && !/^####\s*Scenario:\s*(.+)\s*$/.test(lines[index])) {
+            index++;
+        }
+        scenarios.push({
+            name,
+            raw: lines.slice(start, index).join('\n').trimEnd(),
+        });
+    }
+    return scenarios;
+}
 /**
  * Apply all delta specs from a change to main specs.
  *