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

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

@@ -2,6 +2,16 @@ import { buildCodeFenceMask } from './requirement-text.js';
 export function normalizeRequirementName(name) {
     return name.trim();
 }
+/**
+ * Case- and whitespace-insensitive fold of a requirement name. Requirement
+ * matching itself is case-sensitive (normalizeRequirementName); this fold
+ * exists only for typo detection - near-miss REMOVED headers and the
+ * RENAMED+REMOVED cross-section conflict - where two spellings that differ
+ * only in case or interior whitespace mean a mistake, never two requirements.
+ */
+export function foldRequirementName(name) {
+    return normalizeRequirementName(name).toLowerCase().replace(/\s+/g, ' ');
+}
 /** The canonical requirement header the delta reader recognizes. */
 const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
 /**
@@ -10,7 +20,8 @@ const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
 export function extractRequirementsSection(content) {
     const normalized = normalizeLineEndings(content);
     const lines = normalized.split('\n');
-    const reqHeaderIndex = lines.findIndex(l => /^##\s+Requirements\s*$/i.test(l));
+    const fenceMask = buildCodeFenceMask(lines);
+    const reqHeaderIndex = lines.findIndex((l, i) => !fenceMask[i] && /^##\s+Requirements\s*$/i.test(l));
     if (reqHeaderIndex === -1) {
         // No requirements section; create an empty one at the end
         const before = content.trimEnd();
@@ -26,7 +37,7 @@ export function extractRequirementsSection(content) {
     // Find end of this section: next line that starts with '## ' at same or higher level
     let endIndex = lines.length;
     for (let i = reqHeaderIndex + 1; i < lines.length; i++) {
-        if (/^##\s+/.test(lines[i])) {
+        if (!fenceMask[i] && /^##\s+/.test(lines[i])) {
             endIndex = i;
             break;
         }
@@ -34,29 +45,31 @@ export function extractRequirementsSection(content) {
     const before = lines.slice(0, reqHeaderIndex).join('\n');
     const headerLine = lines[reqHeaderIndex];
     const sectionBodyLines = lines.slice(reqHeaderIndex + 1, endIndex);
+    const sectionBodyMask = fenceMask.slice(reqHeaderIndex + 1, endIndex);
+    const isRequirementHeader = (cursor) => !sectionBodyMask[cursor] && REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor]);
+    const isTopLevelHeader = (cursor) => !sectionBodyMask[cursor] && /^##\s+/.test(sectionBodyLines[cursor]);
     // Parse requirement blocks within section body
     const blocks = [];
     let cursor = 0;
     let preambleLines = [];
     // Collect preamble lines until first requirement header
-    while (cursor < sectionBodyLines.length && !REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor])) {
+    while (cursor < sectionBodyLines.length && !isRequirementHeader(cursor)) {
         preambleLines.push(sectionBodyLines[cursor]);
         cursor++;
     }
     while (cursor < sectionBodyLines.length) {
-        const headerStart = cursor;
         const headerLineCandidate = sectionBodyLines[cursor];
-        const headerMatch = headerLineCandidate.match(REQUIREMENT_HEADER_REGEX);
-        if (!headerMatch) {
+        if (!isRequirementHeader(cursor)) {
             // Not a requirement header; skip line defensively
             cursor++;
             continue;
         }
+        const headerMatch = headerLineCandidate.match(REQUIREMENT_HEADER_REGEX);
         const name = normalizeRequirementName(headerMatch[1]);
         cursor++;
         // Gather lines until next requirement header or end of section
         const bodyLines = [headerLineCandidate];
-        while (cursor < sectionBodyLines.length && !REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor]) && !/^##\s+/.test(sectionBodyLines[cursor])) {
+        while (cursor < sectionBodyLines.length && !isRequirementHeader(cursor) && !isTopLevelHeader(cursor)) {
             bodyLines.push(sectionBodyLines[cursor]);
             cursor++;
         }
@@ -74,14 +87,18 @@ export function extractRequirementsSection(content) {
     };
 }
 function normalizeLineEndings(content) {
-    return content.replace(/\r\n?/g, '\n');
+    // Strip a UTF-8 BOM: Windows editors and PowerShell redirects prepend one,
+    // and it would keep the first line's `## ADDED Requirements` from matching.
+    return content.replace(/^/, '').replace(/\r\n?/g, '\n');
 }
 /**
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export function parseDeltaSpec(content) {
     const normalized = normalizeLineEndings(content);
-    const sections = splitTopLevelSections(normalized);
+    const lines = normalized.split('\n');
+    const fenceMask = buildCodeFenceMask(lines);
+    const sections = splitTopLevelSections(lines, fenceMask);
     const addedLookup = getSectionCaseInsensitive(sections, 'ADDED Requirements');
     const modifiedLookup = getSectionCaseInsensitive(sections, 'MODIFIED Requirements');
     const removedLookup = getSectionCaseInsensitive(sections, 'REMOVED Requirements');
@@ -114,43 +131,45 @@ export function parseDeltaSpec(content) {
         },
     };
 }
-function splitTopLevelSections(content) {
-    const lines = content.split('\n');
+function splitTopLevelSections(lines, fenceMask) {
     const result = {};
     const indices = [];
     for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
         const m = lines[i].match(/^(##)\s+(.+)$/);
         if (m) {
-            const level = m[1].length; // only care for '##'
-            indices.push({ title: m[2].trim(), index: i, level });
+            indices.push({ title: m[2].trim(), index: i });
         }
     }
     for (let i = 0; i < indices.length; i++) {
         const current = indices[i];
         const next = indices[i + 1];
-        const body = lines.slice(current.index + 1, next ? next.index : lines.length).join('\n');
-        // First body line, 1-based: the header is at 0-based current.index.
-        result[current.title] = { body, bodyStartLine: current.index + 2 };
+        const end = next ? next.index : lines.length;
+        result[current.title] = {
+            lines: lines.slice(current.index + 1, end),
+            fenceMask: fenceMask.slice(current.index + 1, end),
+            bodyStartLine: current.index + 2,
+        };
     }
     return result;
 }
+const EMPTY_SECTION_BODY = { lines: [], fenceMask: [], bodyStartLine: 0 };
 function getSectionCaseInsensitive(sections, desired) {
     const target = desired.toLowerCase();
-    for (const [title, { body, bodyStartLine }] of Object.entries(sections)) {
-        if (title.toLowerCase() === target)
-            return { title, body, bodyStartLine, found: true };
+    for (const [title, body] of Object.entries(sections)) {
+        if (title.toLowerCase() === target) {
+            return { title, body, bodyStartLine: body.bodyStartLine, found: true };
+        }
     }
-    return { title: desired, body: '', bodyStartLine: 0, found: false };
+    return { title: desired, body: EMPTY_SECTION_BODY, bodyStartLine: 0, found: false };
 }
 function parseRequirementBlocksFromSection(sectionBody, skipped) {
-    if (!sectionBody)
+    const { lines, fenceMask } = sectionBody;
+    if (lines.length === 0)
         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 isRequirementHeader = (i) => !fenceMask[i] && REQUIREMENT_HEADER_REGEX.test(lines[i]);
+    const isTopLevelHeader = (i) => !fenceMask[i] && /^##\s+/.test(lines[i]);
     const recordIfSkippedHeader = (index) => {
         if (!skipped || fenceMask[index])
             return;
@@ -167,7 +186,7 @@ function parseRequirementBlocksFromSection(sectionBody, skipped) {
     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 && !isRequirementHeader(i)) {
             recordIfSkippedHeader(i);
             i++;
         }
@@ -182,7 +201,7 @@ function parseRequirementBlocksFromSection(sectionBody, skipped) {
         const name = normalizeRequirementName(m[1]);
         const buf = [headerLine];
         i++;
-        while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i]) && !/^##\s+/.test(lines[i])) {
+        while (i < lines.length && !isRequirementHeader(i) && !isTopLevelHeader(i)) {
             recordIfSkippedHeader(i);
             buf.push(lines[i]);
             i++;
@@ -192,11 +211,14 @@ function parseRequirementBlocksFromSection(sectionBody, skipped) {
     return blocks;
 }
 function parseRemovedNames(sectionBody) {
-    if (!sectionBody)
+    const { lines, fenceMask } = sectionBody;
+    if (lines.length === 0)
         return [];
     const names = [];
-    const lines = normalizeLineEndings(sectionBody).split('\n');
-    for (const line of lines) {
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
+        const line = lines[i];
         const m = line.match(REQUIREMENT_HEADER_REGEX);
         if (m) {
             names.push(normalizeRequirementName(m[1]));
@@ -211,12 +233,15 @@ function parseRemovedNames(sectionBody) {
     return names;
 }
 function parseRenamedPairs(sectionBody) {
-    if (!sectionBody)
+    const { lines, fenceMask } = sectionBody;
+    if (lines.length === 0)
         return [];
     const pairs = [];
-    const lines = normalizeLineEndings(sectionBody).split('\n');
     let current = {};
-    for (const line of lines) {
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
+        const line = lines[i];
         const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
         const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
         if (fromMatch) {

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

@@ -8,14 +8,7 @@
  * 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[];
+export { buildCodeFenceMask } from './code-fence.js';
 /**
  * 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

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

@@ -8,48 +8,10 @@
  * 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);
-}
+// Re-exported so existing importers keep working; the single implementation
+// lives in code-fence.ts.
+export { buildCodeFenceMask } from './code-fence.js';
+import { buildCodeFenceMask } from './code-fence.js';
 /** Lines that look like `**ID**: ...` / `**Priority**: ...` metadata. */
 const METADATA_LINE = /^\*\*[^*]+\*\*:/;
 /** Any markdown header line — the boundary where a requirement body ends. */

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

@@ -1,3 +1,4 @@
+import { buildCodeFenceMask } from './code-fence.js';
 const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
 const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
 const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
@@ -55,34 +56,7 @@ export function findMainSpecStructureIssues(content) {
 }
 export function stripFencedCodeBlocksPreservingLines(content) {
     const lines = content.split('\n');
-    const output = [];
-    let activeFence = null;
-    for (const line of lines) {
-        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})(.*)$/);
-        if (!activeFence) {
-            if (fenceMatch) {
-                activeFence = {
-                    marker: fenceMatch[1][0],
-                    length: fenceMatch[1].length,
-                };
-                output.push('');
-            }
-            else {
-                output.push(line);
-            }
-            continue;
-        }
-        output.push('');
-        if (isClosingFence(line, activeFence)) {
-            activeFence = null;
-        }
-    }
-    return output.join('\n');
-}
-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);
+    const mask = buildCodeFenceMask(lines);
+    return lines.map((line, i) => (mask[i] ? '' : line)).join('\n');
 }
 //# sourceMappingURL=spec-structure.js.map

package/dist/core/profile-sync-drift.d.ts

@@ -5,14 +5,6 @@ type WorkflowId = (typeof ALL_WORKFLOWS)[number];
  * Maps workflow IDs to their skill directory names.
  */
 export declare const WORKFLOW_TO_SKILL_DIR: Record<WorkflowId, string>;
-/**
- * Checks whether a tool has at least one generated OpenSpec command file.
- */
-export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string): boolean;
-/**
- * Returns tools with at least one generated command file on disk.
- */
-export declare function getCommandConfiguredTools(projectPath: string): string[];
 /**
  * Returns tools that are configured via either skills or commands.
  */

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

@@ -3,7 +3,8 @@ import * as fs from 'fs';
 import { AI_TOOLS } from './config.js';
 import { ALL_WORKFLOWS } from './profiles.js';
 import { CommandAdapterRegistry } from './command-generation/index.js';
-import { COMMAND_IDS, getConfiguredTools } from './shared/index.js';
+import { getConfiguredTools } from './shared/index.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
 /**
  * Maps workflow IDs to their skill directory names.
  */
@@ -24,48 +25,11 @@ export const WORKFLOW_TO_SKILL_DIR = {
 function toKnownWorkflows(workflows) {
     return workflows.filter((workflow) => ALL_WORKFLOWS.includes(workflow));
 }
-/**
- * Checks whether a tool has at least one generated OpenSpec command file.
- */
-export function toolHasAnyConfiguredCommand(projectPath, toolId) {
-    const adapter = CommandAdapterRegistry.get(toolId);
-    if (!adapter)
-        return false;
-    for (const commandId of COMMAND_IDS) {
-        const cmdPath = adapter.getFilePath(commandId);
-        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
-        if (fs.existsSync(fullPath)) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Returns tools with at least one generated command file on disk.
- */
-export function getCommandConfiguredTools(projectPath) {
-    return AI_TOOLS
-        .filter((tool) => {
-        if (!tool.skillsDir)
-            return false;
-        const toolDir = path.join(projectPath, tool.skillsDir);
-        try {
-            return fs.statSync(toolDir).isDirectory();
-        }
-        catch {
-            return false;
-        }
-    })
-        .map((tool) => tool.value)
-        .filter((toolId) => toolHasAnyConfiguredCommand(projectPath, toolId));
-}
 /**
  * Returns tools that are configured via either skills or commands.
  */
 export function getConfiguredToolsForProfileSync(projectPath) {
-    const skillConfigured = getConfiguredTools(projectPath);
-    const commandConfigured = getCommandConfiguredTools(projectPath);
-    return [...new Set([...skillConfigured, ...commandConfigured])];
+    return getConfiguredTools(projectPath);
 }
 /**
  * Detects if a single tool has profile/delivery drift against the desired state.
@@ -83,8 +47,8 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
     const desiredWorkflowSet = new Set(knownDesiredWorkflows);
     const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
     const adapter = CommandAdapterRegistry.get(toolId);
-    const shouldGenerateSkills = delivery !== 'commands';
-    const shouldGenerateCommands = delivery !== 'skills';
+    const shouldGenerateSkills = shouldGenerateSkillsForTool(toolId, delivery);
+    const shouldGenerateCommands = shouldGenerateCommandsForTool(toolId, delivery);
     if (shouldGenerateSkills) {
         for (const workflow of knownDesiredWorkflows) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
@@ -104,7 +68,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
             }
         }
     }
-    else {
+    else if (shouldRemoveSkillsForTool(toolId, delivery)) {
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             const skillDir = path.join(skillsDir, dirName);
@@ -132,7 +96,7 @@ export function hasToolProfileOrDeliveryDrift(projectPath, toolId, desiredWorkfl
             }
         }
     }
-    else if (!shouldGenerateCommands && adapter) {
+    else if (shouldReconcileCommandFilesForTool(toolId, delivery) && adapter) {
         for (const workflow of ALL_WORKFLOWS) {
             const cmdPath = adapter.getFilePath(workflow);
             const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
@@ -188,9 +152,9 @@ export function hasProjectConfigDrift(projectPath, desiredWorkflows, delivery) {
         return true;
     }
     const desiredSet = new Set(toKnownWorkflows(desiredWorkflows));
-    const includeSkills = delivery !== 'commands';
-    const includeCommands = delivery !== 'skills';
     for (const toolId of configuredTools) {
+        const includeSkills = shouldGenerateSkillsForTool(toolId, delivery);
+        const includeCommands = shouldGenerateCommandsForTool(toolId, delivery);
         const installed = getInstalledWorkflowsForTool(projectPath, toolId, { includeSkills, includeCommands });
         if (installed.some((workflow) => !desiredSet.has(workflow))) {
             return true;

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

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+export declare const OPERATION_IDS: readonly ["apply", "archive"];
+export type OperationId = (typeof OPERATION_IDS)[number];
+export interface OperationConfig {
+    guidance?: string[];
+}
+export type OperationsConfig = Partial<Record<OperationId, OperationConfig>>;
 /**
  * Zod schema for project configuration.
  *
@@ -16,6 +22,14 @@ 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>>>;
+    operations: z.ZodOptional<z.ZodObject<{
+        apply: z.ZodOptional<z.ZodObject<{
+            guidance: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        archive: z.ZodOptional<z.ZodObject<{
+            guidance: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     store: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** Normalized in-memory shape of a referenced store declaration. */
@@ -27,6 +41,11 @@ export interface DeclarationEntry {
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema> & {
     references?: DeclarationEntry[];
 };
+export interface OperationInputs {
+    context?: string;
+    operationGuidance?: string[];
+}
+export declare function loadOperationInputs(projectConfig: ProjectConfig | null, operationId: OperationId): OperationInputs;
 export declare const MAX_CONTEXT_SIZE: number;
 /**
  * Read and parse openspec/config.yaml from project root.
@@ -49,16 +68,16 @@ export declare const MAX_CONTEXT_SIZE: number;
  */
 export declare function readProjectConfig(projectRoot: string): ProjectConfig | null;
 /**
- * Validate artifact IDs in rules against a schema's artifacts.
- * Called during instruction loading (when schema is known).
- * Returns warnings for unknown artifact IDs.
+ * Validate artifact IDs in rules against the artifacts of every available
+ * schema. The `rules:` map is global, but each change can use a different
+ * schema, so a key is only unknown when it matches no artifact in ANY schema.
+ * Returns warnings for keys that are unknown everywhere.
  *
  * @param rules - The rules object from config
- * @param validArtifactIds - Set of valid artifact IDs from the schema
- * @param schemaName - Name of the schema for error messages
+ * @param validArtifactIds - Set of valid artifact IDs across all schemas
  * @returns Array of warning messages for unknown artifact IDs
  */
-export declare function validateConfigRules(rules: Record<string, string[]>, validArtifactIds: Set<string>, schemaName: string): string[];
+export declare function validateConfigRules(rules: Record<string, string[]>, validArtifactIds: Set<string>): string[];
 /**
  * Suggest valid schema names when user provides invalid schema.
  * Uses fuzzy matching to find similar names.

package/dist/core/project-config.js

@@ -2,6 +2,10 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
+export const OPERATION_IDS = ['apply', 'archive'];
+const OperationConfigSchema = z.object({
+    guidance: z.array(z.string()).optional(),
+});
 /**
  * Zod schema for project configuration.
  *
@@ -34,6 +38,14 @@ export const ProjectConfigSchema = z.object({
     )
         .optional()
         .describe('Per-artifact rules, keyed by artifact ID'),
+    // Optional: per-operation advisory guidance, kept separate from artifact rules.
+    operations: z
+        .object({
+        apply: OperationConfigSchema.optional(),
+        archive: OperationConfigSchema.optional(),
+    })
+        .optional()
+        .describe('Per-operation advisory guidance'),
     // Note: the `references` field (id strings or {id, remote} maps) is
     // deliberately absent here — readProjectConfig parses and normalizes
     // it by hand (see DeclarationEntry below); a schema entry nothing
@@ -46,6 +58,60 @@ export const ProjectConfigSchema = z.object({
         .optional()
         .describe('Store id used as the OpenSpec root when no local planning shape exists'),
 });
+export function loadOperationInputs(projectConfig, operationId) {
+    const context = projectConfig?.context !== undefined && projectConfig.context.trim().length > 0
+        ? projectConfig.context
+        : undefined;
+    const guidance = projectConfig?.operations?.[operationId]?.guidance;
+    const operationGuidance = guidance && guidance.length > 0 ? guidance : undefined;
+    return {
+        ...(context !== undefined ? { context } : {}),
+        ...(operationGuidance !== undefined ? { operationGuidance } : {}),
+    };
+}
+function parseOperations(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        console.warn(`Invalid 'operations' field in config (must be object)`);
+        return undefined;
+    }
+    const supported = new Set(OPERATION_IDS);
+    const operations = {};
+    for (const [operationId, value] of Object.entries(raw)) {
+        if (!supported.has(operationId)) {
+            console.warn(`Unknown operation ID '${operationId}' in config. Supported operation IDs: ${OPERATION_IDS.join(', ')}`);
+            continue;
+        }
+        const typedOperationId = operationId;
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            console.warn(`Invalid 'operations.${operationId}' field in config (must be object), ignoring this operation`);
+            continue;
+        }
+        const operation = value;
+        const unknownFields = Object.keys(operation).filter((field) => field !== 'guidance');
+        if (unknownFields.length > 0) {
+            console.warn(`Unknown field(s) in 'operations.${operationId}': ${unknownFields.join(', ')}. Supported fields: guidance`);
+        }
+        if (operation.guidance === undefined) {
+            continue;
+        }
+        const guidanceResult = z.array(z.string()).safeParse(operation.guidance);
+        if (!guidanceResult.success) {
+            console.warn(`Guidance for operation '${operationId}' must be an array of strings, ignoring this operation's guidance`);
+            continue;
+        }
+        const guidance = guidanceResult.data.filter((entry) => entry.length > 0);
+        if (guidance.length < guidanceResult.data.length) {
+            console.warn(`Some guidance for operation '${operationId}' are empty strings, ignoring them`);
+        }
+        if (guidance.length > 0) {
+            operations[typedOperationId] = { guidance };
+        }
+    }
+    return Object.keys(operations).length > 0 ? operations : undefined;
+}
 /**
  * Parser for `references:` declarations: string entries or
  * {id, remote} maps, normalized to DeclarationEntry[]. Dedup keys on
@@ -196,6 +262,10 @@ export function readProjectConfig(projectRoot) {
                 console.warn(`Invalid 'rules' field in config (must be object)`);
             }
         }
+        const operations = parseOperations(raw.operations);
+        if (operations) {
+            config.operations = operations;
+        }
         const references = parseDeclarationList(raw.references);
         if (references) {
             config.references = references;
@@ -223,22 +293,22 @@ function configPathForWarnings(projectRoot) {
     return resolveConfigFilePath(projectRoot) ?? path.join(projectRoot, 'openspec', 'config.yaml');
 }
 /**
- * Validate artifact IDs in rules against a schema's artifacts.
- * Called during instruction loading (when schema is known).
- * Returns warnings for unknown artifact IDs.
+ * Validate artifact IDs in rules against the artifacts of every available
+ * schema. The `rules:` map is global, but each change can use a different
+ * schema, so a key is only unknown when it matches no artifact in ANY schema.
+ * Returns warnings for keys that are unknown everywhere.
  *
  * @param rules - The rules object from config
- * @param validArtifactIds - Set of valid artifact IDs from the schema
- * @param schemaName - Name of the schema for error messages
+ * @param validArtifactIds - Set of valid artifact IDs across all schemas
  * @returns Array of warning messages for unknown artifact IDs
  */
-export function validateConfigRules(rules, validArtifactIds, schemaName) {
+export function validateConfigRules(rules, validArtifactIds) {
     const warnings = [];
     for (const artifactId of Object.keys(rules)) {
         if (!validArtifactIds.has(artifactId)) {
             const validIds = Array.from(validArtifactIds).sort().join(', ');
             warnings.push(`Unknown artifact ID in rules: "${artifactId}". ` +
-                `Valid IDs for schema "${schemaName}": ${validIds}`);
+                `It matches no artifact in any available schema. Known artifact IDs: ${validIds}`);
         }
     }
     return warnings;