@fission-ai/openspec 1.6.0 → 1.8.0

package/dist/core/command-generation/invocation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Command Invocation
+ *
+ * How a tool spells an OpenSpec command has two parts, and only one of them
+ * can be read off the file the adapter writes:
+ *
+ * - The *name* comes from the file. `.../commands/opsx/<id>.md` is namespaced
+ *   by its directory, so the tool registers `opsx:<id>` (Claude Code, Gemini,
+ *   Crush, ...). `.../commands/opsx-<id>.md` names the command with the
+ *   filename, so the tool registers `opsx-<id>` (Cursor, GitHub Copilot,
+ *   OpenCode, ...).
+ * - The *prefix* is the tool's own and cannot be derived. Almost every tool
+ *   uses `/`; Amazon Q loads these files into its prompt library, which is
+ *   invoked with `@` (`@opsx-propose`), so its adapter declares that prefix.
+ *
+ * Deriving the name from `getFilePath` keeps generated cross-references and
+ * onboarding hints in step with the files OpenSpec actually writes. A
+ * hand-maintained list drifted before: only OpenCode was rewritten when the
+ * hyphen form was introduced (#727), and Cursor still advertised `/opsx:`
+ * commands its palette never registered (#1307). Carrying the prefix as
+ * adapter metadata rather than inferring it keeps the one tool that does not
+ * use a slash from being advertised as if it did.
+ */
+import type { ToolCommandAdapter } from './types.js';
+export type CommandInvocationStyle = 'namespaced' | 'flat';
+/**
+ * Everything needed to spell one of a tool's OpenSpec commands.
+ */
+export interface CommandInvocation {
+    /** How the command file names the command. */
+    style: CommandInvocationStyle;
+    /** What the user types before the name, e.g. `/` or Amazon Q's `@`. */
+    prefix: string;
+}
+/** The form these docs, command bodies, and skill templates are authored in. */
+export declare const CANONICAL_INVOCATION: CommandInvocation;
+/**
+ * Classifies a generated command file by the name the tool will answer to.
+ *
+ * The test is the filename, not the directory: an `opsx-` prefix means the
+ * filename is the command. Every other shape is treated as namespaced, which
+ * is what all seven `opsx/<id>.*` adapters need. An adapter that neither
+ * prefixes the filename nor nests under `opsx/` would land here too — none
+ * does, and the registry-wide test in invocation.test.ts fails if one appears.
+ *
+ * @param commandFilePath - Path returned by an adapter's `getFilePath`
+ * @returns 'flat' when the filename carries the `opsx-` prefix, otherwise
+ *          'namespaced'
+ */
+export declare function getInvocationStyleForPath(commandFilePath: string): CommandInvocationStyle;
+/**
+ * Resolves how a tool's generated commands are invoked: the name from the
+ * files its adapter writes, the prefix from the adapter's own declaration.
+ *
+ * @param adapter - The tool-specific command adapter
+ * @returns The invocation shared by every command that adapter generates
+ */
+export declare function getInvocationForAdapter(adapter: ToolCommandAdapter): CommandInvocation;
+/**
+ * Spells one command the way the tool registers it.
+ *
+ * @param invocation - The tool's invocation, from getInvocationForAdapter()
+ * @param commandId - The command identifier (e.g. 'apply')
+ * @returns What the user types, e.g. `/opsx:apply`, `/opsx-apply`, `@opsx-apply`
+ */
+export declare function formatCommandInvocation(invocation: CommandInvocation, commandId: string): string;
+/**
+ * Whether a tool's invocation differs from the canonical `/opsx:<id>` that
+ * command bodies and skill templates are authored in — that is, whether
+ * generated text has to be rewritten for that tool at all.
+ */
+export declare function needsInvocationRewrite(invocation: CommandInvocation): boolean;
+//# sourceMappingURL=invocation.d.ts.map

package/dist/core/command-generation/invocation.js

@@ -0,0 +1,77 @@
+/**
+ * Command Invocation
+ *
+ * How a tool spells an OpenSpec command has two parts, and only one of them
+ * can be read off the file the adapter writes:
+ *
+ * - The *name* comes from the file. `.../commands/opsx/<id>.md` is namespaced
+ *   by its directory, so the tool registers `opsx:<id>` (Claude Code, Gemini,
+ *   Crush, ...). `.../commands/opsx-<id>.md` names the command with the
+ *   filename, so the tool registers `opsx-<id>` (Cursor, GitHub Copilot,
+ *   OpenCode, ...).
+ * - The *prefix* is the tool's own and cannot be derived. Almost every tool
+ *   uses `/`; Amazon Q loads these files into its prompt library, which is
+ *   invoked with `@` (`@opsx-propose`), so its adapter declares that prefix.
+ *
+ * Deriving the name from `getFilePath` keeps generated cross-references and
+ * onboarding hints in step with the files OpenSpec actually writes. A
+ * hand-maintained list drifted before: only OpenCode was rewritten when the
+ * hyphen form was introduced (#727), and Cursor still advertised `/opsx:`
+ * commands its palette never registered (#1307). Carrying the prefix as
+ * adapter metadata rather than inferring it keeps the one tool that does not
+ * use a slash from being advertised as if it did.
+ */
+import path from 'path';
+/** The form these docs, command bodies, and skill templates are authored in. */
+export const CANONICAL_INVOCATION = { style: 'namespaced', prefix: '/' };
+/**
+ * Classifies a generated command file by the name the tool will answer to.
+ *
+ * The test is the filename, not the directory: an `opsx-` prefix means the
+ * filename is the command. Every other shape is treated as namespaced, which
+ * is what all seven `opsx/<id>.*` adapters need. An adapter that neither
+ * prefixes the filename nor nests under `opsx/` would land here too — none
+ * does, and the registry-wide test in invocation.test.ts fails if one appears.
+ *
+ * @param commandFilePath - Path returned by an adapter's `getFilePath`
+ * @returns 'flat' when the filename carries the `opsx-` prefix, otherwise
+ *          'namespaced'
+ */
+export function getInvocationStyleForPath(commandFilePath) {
+    return path.basename(commandFilePath).startsWith('opsx-') ? 'flat' : 'namespaced';
+}
+/**
+ * Resolves how a tool's generated commands are invoked: the name from the
+ * files its adapter writes, the prefix from the adapter's own declaration.
+ *
+ * @param adapter - The tool-specific command adapter
+ * @returns The invocation shared by every command that adapter generates
+ */
+export function getInvocationForAdapter(adapter) {
+    return {
+        // Any command id works: every adapter applies one naming rule to all of them.
+        style: getInvocationStyleForPath(adapter.getFilePath('explore')),
+        prefix: adapter.invocationPrefix ?? CANONICAL_INVOCATION.prefix,
+    };
+}
+/**
+ * Spells one command the way the tool registers it.
+ *
+ * @param invocation - The tool's invocation, from getInvocationForAdapter()
+ * @param commandId - The command identifier (e.g. 'apply')
+ * @returns What the user types, e.g. `/opsx:apply`, `/opsx-apply`, `@opsx-apply`
+ */
+export function formatCommandInvocation(invocation, commandId) {
+    const separator = invocation.style === 'namespaced' ? ':' : '-';
+    return `${invocation.prefix}opsx${separator}${commandId}`;
+}
+/**
+ * Whether a tool's invocation differs from the canonical `/opsx:<id>` that
+ * command bodies and skill templates are authored in — that is, whether
+ * generated text has to be rewritten for that tool at all.
+ */
+export function needsInvocationRewrite(invocation) {
+    return (invocation.style !== CANONICAL_INVOCATION.style ||
+        invocation.prefix !== CANONICAL_INVOCATION.prefix);
+}
+//# sourceMappingURL=invocation.js.map

package/dist/core/command-generation/registry.js

@@ -10,7 +10,7 @@ import { auggieAdapter } from './adapters/auggie.js';
 import { bobAdapter } from './adapters/bob.js';
 import { claudeAdapter } from './adapters/claude.js';
 import { clineAdapter } from './adapters/cline.js';
-import { codexAdapter } from './adapters/codex.js';
+import { devinAdapter } from './adapters/devin.js';
 import { codebuddyAdapter } from './adapters/codebuddy.js';
 import { continueAdapter } from './adapters/continue.js';
 import { costrictAdapter } from './adapters/costrict.js';
@@ -31,7 +31,7 @@ import { lingmaAdapter } from './adapters/lingma.js';
 import { qwenAdapter } from './adapters/qwen.js';
 import { roocodeAdapter } from './adapters/roocode.js';
 import { traeAdapter } from './adapters/trae.js';
-import { windsurfAdapter } from './adapters/windsurf.js';
+import { zcodeAdapter } from './adapters/zcode.js';
 /**
  * Registry for looking up tool command adapters.
  */
@@ -45,7 +45,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(bobAdapter);
         CommandAdapterRegistry.register(claudeAdapter);
         CommandAdapterRegistry.register(clineAdapter);
-        CommandAdapterRegistry.register(codexAdapter);
+        CommandAdapterRegistry.register(devinAdapter);
         CommandAdapterRegistry.register(codebuddyAdapter);
         CommandAdapterRegistry.register(continueAdapter);
         CommandAdapterRegistry.register(costrictAdapter);
@@ -66,7 +66,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(qwenAdapter);
         CommandAdapterRegistry.register(roocodeAdapter);
         CommandAdapterRegistry.register(traeAdapter);
-        CommandAdapterRegistry.register(windsurfAdapter);
+        CommandAdapterRegistry.register(zcodeAdapter);
     }
     /**
      * Register a tool command adapter.

package/dist/core/command-generation/types.d.ts

@@ -34,9 +34,16 @@ export interface ToolCommandAdapter {
      * Returns the file path for a command.
      * @param commandId - The command identifier (e.g., 'explore')
      * @returns Path from project root (e.g., '.claude/commands/opsx/explore.md').
-     *          May be absolute for tools with global-scoped prompts (e.g., Codex).
+     *          May be absolute for tools with global-scoped command files.
      */
     getFilePath(commandId: string): string;
+    /**
+     * What the user types before the command name, when it is not the default
+     * `/`. Amazon Q loads these files into its prompt library, which is invoked
+     * with `@` (`@opsx-propose`), so its adapter sets '@'. The name itself is
+     * still derived from getFilePath — see invocation.ts.
+     */
+    invocationPrefix?: string;
     /**
      * Formats the complete file content including frontmatter.
      * @param content - The tool-agnostic command content
@@ -48,7 +55,7 @@ export interface ToolCommandAdapter {
  * Result of generating a command file.
  */
 export interface GeneratedCommand {
-    /** File path from project root, or absolute for global-scoped tools */
+    /** File path from project root, or absolute for global-scoped command files */
     path: string;
     /** Complete file content (frontmatter + body) */
     fileContent: string;

package/dist/core/command-generation/yaml.d.ts

@@ -9,14 +9,28 @@
 /**
  * Escapes a string value for safe YAML output.
  *
- * Quotes the value with double quotes when it contains characters that
- * carry special meaning in YAML (or leading/trailing whitespace), and
- * escapes the characters that are not representable verbatim inside a
- * double-quoted scalar: backslash, double quote, line feed and carriage
- * return. Values without special characters are returned unquoted.
+ * Always emits a double-quoted scalar. Quoting unconditionally keeps the
+ * value a string no matter what it holds: an unquoted `true`, `null` or
+ * `123` would round-trip as a boolean, null or number, and an unquoted
+ * value opening with a block indicator (`|`, `>`) or containing `: `
+ * is not valid YAML at all.
+ *
+ * Inside the quotes it escapes everything that cannot appear verbatim in a
+ * double-quoted scalar: backslash, double quote, line feed, carriage
+ * return, and the non-printable characters YAML's `c-printable` production
+ * excludes (C0 controls, DEL and C1 controls). Lenient parsers accept a raw
+ * control byte, but strict ones reject the document outright, so escaping
+ * them here keeps the generated file portable across every tool's parser.
  *
  * @param value - The raw string to embed in YAML frontmatter.
- * @returns The value, double-quoted and escaped when necessary.
+ * @returns The value as an escaped, double-quoted YAML scalar.
  */
 export declare function escapeYamlValue(value: string): string;
+/**
+ * Formats a tags array as a YAML array with proper escaping.
+ *
+ * @param tags - Array of tag strings.
+ * @returns Formatted YAML array string, e.g. '[tag1, tag2]'.
+ */
+export declare function formatTagsArray(tags: string[]): string;
 //# sourceMappingURL=yaml.d.ts.map

package/dist/core/command-generation/yaml.js

@@ -9,30 +9,40 @@
 /**
  * Escapes a string value for safe YAML output.
  *
- * Quotes the value with double quotes when it contains characters that
- * carry special meaning in YAML (or leading/trailing whitespace), and
- * escapes the characters that are not representable verbatim inside a
- * double-quoted scalar: backslash, double quote, line feed and carriage
- * return. Values without special characters are returned unquoted.
+ * Always emits a double-quoted scalar. Quoting unconditionally keeps the
+ * value a string no matter what it holds: an unquoted `true`, `null` or
+ * `123` would round-trip as a boolean, null or number, and an unquoted
+ * value opening with a block indicator (`|`, `>`) or containing `: `
+ * is not valid YAML at all.
+ *
+ * Inside the quotes it escapes everything that cannot appear verbatim in a
+ * double-quoted scalar: backslash, double quote, line feed, carriage
+ * return, and the non-printable characters YAML's `c-printable` production
+ * excludes (C0 controls, DEL and C1 controls). Lenient parsers accept a raw
+ * control byte, but strict ones reject the document outright, so escaping
+ * them here keeps the generated file portable across every tool's parser.
  *
  * @param value - The raw string to embed in YAML frontmatter.
- * @returns The value, double-quoted and escaped when necessary.
+ * @returns The value as an escaped, double-quoted YAML scalar.
  */
 export function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape characters that are not safe to emit
-        // verbatim inside a double-quoted YAML scalar. Carriage returns must be
-        // escaped too: a literal CR inside double quotes is subject to YAML line
-        // folding/normalization and would silently corrupt the round-tripped value.
-        const escaped = value
-            .replace(/\\/g, '\\\\')
-            .replace(/"/g, '\\"')
-            .replace(/\n/g, '\\n')
-            .replace(/\r/g, '\\r');
-        return `"${escaped}"`;
-    }
-    return value;
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        // Remaining non-printables have no dedicated escape; emit them as \xHH.
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
+    return `"${escaped}"`;
+}
+/**
+ * Formats a tags array as a YAML array with proper escaping.
+ *
+ * @param tags - Array of tag strings.
+ * @returns Formatted YAML array string, e.g. '[tag1, tag2]'.
+ */
+export function formatTagsArray(tags) {
+    const escapedTags = tags.map((tag) => escapeYamlValue(tag));
+    return `[${escapedTags.join(', ')}]`;
 }
 //# sourceMappingURL=yaml.js.map

package/dist/core/command-surface.d.ts

@@ -0,0 +1,15 @@
+import { type CommandInvocation } from './command-generation/invocation.js';
+import type { Delivery } from './global-config.js';
+export type CommandSurfaceCapability = 'adapter-backed' | 'skills-invocable' | 'none';
+/**
+ * How the tool spells its OpenSpec commands: the name from the command files
+ * its adapter writes, the prefix the adapter declares. Returns undefined for
+ * tools with no command adapter, which have no command names to spell.
+ */
+export declare function resolveCommandInvocation(toolId: string): CommandInvocation | undefined;
+export declare function resolveCommandSurfaceCapability(toolId: string): CommandSurfaceCapability;
+export declare function shouldGenerateSkillsForTool(toolId: string, delivery: Delivery): boolean;
+export declare function shouldRemoveSkillsForTool(toolId: string, delivery: Delivery): boolean;
+export declare function shouldGenerateCommandsForTool(toolId: string, delivery: Delivery): boolean;
+export declare function shouldReconcileCommandFilesForTool(toolId: string, delivery: Delivery): boolean;
+//# sourceMappingURL=command-surface.d.ts.map

package/dist/core/command-surface.js

@@ -0,0 +1,33 @@
+import { CommandAdapterRegistry } from './command-generation/index.js';
+import { getInvocationForAdapter } from './command-generation/invocation.js';
+/**
+ * How the tool spells its OpenSpec commands: the name from the command files
+ * its adapter writes, the prefix the adapter declares. Returns undefined for
+ * tools with no command adapter, which have no command names to spell.
+ */
+export function resolveCommandInvocation(toolId) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    return adapter ? getInvocationForAdapter(adapter) : undefined;
+}
+export function resolveCommandSurfaceCapability(toolId) {
+    if (CommandAdapterRegistry.has(toolId)) {
+        return 'adapter-backed';
+    }
+    if (toolId === 'codex') {
+        return 'skills-invocable';
+    }
+    return 'none';
+}
+export function shouldGenerateSkillsForTool(toolId, delivery) {
+    return delivery !== 'commands' || resolveCommandSurfaceCapability(toolId) === 'skills-invocable';
+}
+export function shouldRemoveSkillsForTool(toolId, delivery) {
+    return delivery === 'commands' && resolveCommandSurfaceCapability(toolId) !== 'skills-invocable';
+}
+export function shouldGenerateCommandsForTool(toolId, delivery) {
+    return delivery !== 'skills' && resolveCommandSurfaceCapability(toolId) === 'adapter-backed';
+}
+export function shouldReconcileCommandFilesForTool(toolId, delivery) {
+    return delivery === 'skills' && resolveCommandSurfaceCapability(toolId) === 'adapter-backed';
+}
+//# sourceMappingURL=command-surface.js.map

package/dist/core/completions/command-registry.js

@@ -22,6 +22,18 @@ export const COMMAND_REGISTRY = [
                 takesValue: true,
                 values: ['core', 'custom'],
             },
+            {
+                name: 'no-animation',
+                description: 'Show a static welcome screen instead of the animated one',
+            },
+            {
+                name: 'copilot-cloud',
+                description: 'Generate GitHub Copilot cloud coding-agent files (opt-in; default: prompt)',
+            },
+            {
+                name: 'no-copilot-cloud',
+                description: 'Skip generating GitHub Copilot cloud coding-agent files',
+            },
         ],
     },
     {
@@ -62,7 +74,9 @@ export const COMMAND_REGISTRY = [
     {
         name: 'view',
         description: 'Display an interactive dashboard of specs and changes',
-        flags: [],
+        flags: [
+            COMMON_FLAGS.store,
+        ],
     },
     {
         name: 'validate',
@@ -177,7 +191,7 @@ export const COMMAND_REGISTRY = [
     },
     {
         name: 'instructions',
-        description: 'Output enriched instructions for creating an artifact or applying tasks',
+        description: 'Output enriched instructions for artifacts, apply, or archive',
         acceptsPositional: true,
         positionals: [{ name: 'artifact', optional: true }],
         flags: [

package/dist/core/completions/generators/powershell-generator.js

@@ -164,6 +164,20 @@ Register-ArgumentCompleter -CommandName openspec -ScriptBlock $openspecCompleter
         return lines;
     }
     generateIndexedPositionalCompletion(positionals, flags, firstPositionalTokenIndex, indent) {
+        const caseLines = [];
+        for (const [index, positional] of positionals.entries()) {
+            const completion = this.generatePositionalCompletion(positional.type, indent + '    ');
+            if (completion.length === 0)
+                continue;
+            caseLines.push(`${indent}    ${index} {`);
+            caseLines.push(...completion);
+            caseLines.push(`${indent}    }`);
+        }
+        // A switch with no clauses is a PowerShell parse error, so when no
+        // positional produces completions skip the whole block (it would only
+        // feed the empty switch anyway).
+        if (caseLines.length === 0)
+            return [];
         const lines = [];
         const valueFlags = this.generateValueFlags(flags);
         if (valueFlags.length > 0) {
@@ -192,14 +206,7 @@ Register-ArgumentCompleter -CommandName openspec -ScriptBlock $openspecCompleter
         lines.push(`${indent}}`);
         lines.push('');
         lines.push(`${indent}switch ($positionalIndex) {`);
-        for (const [index, positional] of positionals.entries()) {
-            const completion = this.generatePositionalCompletion(positional.type, indent + '    ');
-            if (completion.length === 0)
-                continue;
-            lines.push(`${indent}    ${index} {`);
-            lines.push(...completion);
-            lines.push(`${indent}    }`);
-        }
+        lines.push(...caseLines);
         lines.push(`${indent}}`);
         return lines;
     }

package/dist/core/completions/installers/zsh-installer.d.ts

@@ -16,6 +16,15 @@ export declare class ZshInstaller {
      * @returns true if Oh My Zsh is detected via $ZSH env var or directory exists
      */
     isOhMyZshInstalled(): Promise<boolean>;
+    /**
+     * Oh My Zsh exports its root as $ZSH; honor a custom location, or the
+     * completion lands in a ~/.oh-my-zsh tree that nothing ever loads.
+     */
+    private ohMyZshRoot;
+    /**
+     * The custom dir is separately relocatable via $ZSH_CUSTOM.
+     */
+    private ohMyZshCustomDir;
     /**
      * Get the appropriate installation path for the completion script
      *

package/dist/core/completions/installers/zsh-installer.js

@@ -29,15 +29,27 @@ export class ZshInstaller {
             return true;
         }
         // Fall back to checking for ~/.oh-my-zsh directory
-        const ohMyZshPath = path.join(this.homeDir, '.oh-my-zsh');
         try {
-            const stat = await fs.stat(ohMyZshPath);
+            const stat = await fs.stat(this.ohMyZshRoot());
             return stat.isDirectory();
         }
         catch {
             return false;
         }
     }
+    /**
+     * Oh My Zsh exports its root as $ZSH; honor a custom location, or the
+     * completion lands in a ~/.oh-my-zsh tree that nothing ever loads.
+     */
+    ohMyZshRoot() {
+        return process.env.ZSH || path.join(this.homeDir, '.oh-my-zsh');
+    }
+    /**
+     * The custom dir is separately relocatable via $ZSH_CUSTOM.
+     */
+    ohMyZshCustomDir() {
+        return process.env.ZSH_CUSTOM || path.join(this.ohMyZshRoot(), 'custom');
+    }
     /**
      * Get the appropriate installation path for the completion script
      *
@@ -48,7 +60,7 @@ export class ZshInstaller {
         if (isOhMyZsh) {
             // Oh My Zsh custom completions directory
             return {
-                path: path.join(this.homeDir, '.oh-my-zsh', 'custom', 'completions', '_openspec'),
+                path: path.join(this.ohMyZshCustomDir(), 'completions', '_openspec'),
                 isOhMyZsh: true,
             };
         }
@@ -292,10 +304,14 @@ export class ZshInstaller {
      * @returns Array of guidance strings, or undefined if not needed
      */
     generateOhMyZshFpathGuidance(completionsDir) {
+        // One fpath entry per line, matched as a literal: a relocated $ZSH_CUSTOM
+        // need not contain "custom/completions", and the path may hold characters
+        // grep would otherwise read as a pattern. Single-quoted for the shell.
+        const quotedDir = `'${completionsDir.replace(/'/g, `'\\''`)}'`;
         return [
             'Note: Oh My Zsh typically auto-loads completions from custom/completions.',
             `Verify that ${completionsDir} is in your fpath by running:`,
-            '  echo $fpath | grep "custom/completions"',
+            `  printf '%s\\n' $fpath | grep -F ${quotedDir}`,
             '',
             'If not found, completions may not work. Restart your shell to ensure changes take effect.',
         ];

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

@@ -2,7 +2,7 @@ import type { ProjectConfig } from './project-config.js';
 /**
  * Serialize config to YAML string with helpful comments.
  *
- * @param config - Partial config object (schema required, context/rules optional)
+ * @param config - Partial config object (schema required, other fields optional)
  * @returns YAML string ready to write to file
  */
 export declare function serializeConfig(config: Partial<ProjectConfig>): string;

package/dist/core/config-prompts.js

@@ -1,7 +1,7 @@
 /**
  * Serialize config to YAML string with helpful comments.
  *
- * @param config - Partial config object (schema required, context/rules optional)
+ * @param config - Partial config object (schema required, other fields optional)
  * @returns YAML string ready to write to file
  */
 export function serializeConfig(config) {
@@ -29,6 +29,19 @@ export function serializeConfig(config) {
     lines.push('#       - Always include a "Non-goals" section');
     lines.push('#     tasks:');
     lines.push('#       - Break tasks into chunks of max 2 hours');
+    lines.push('');
+    // Operation guidance section with comments
+    lines.push('# Per-operation guidance (optional)');
+    lines.push('# Add advisory guidance for how apply and archive work should be conducted.');
+    lines.push('# This is separate from artifact rules above.');
+    lines.push('# Example:');
+    lines.push('#   operations:');
+    lines.push('#     apply:');
+    lines.push('#       guidance:');
+    lines.push('#         - Keep test summaries concise');
+    lines.push('#     archive:');
+    lines.push('#       guidance:');
+    lines.push('#         - Summarize the archive outcome before finishing');
     return lines.join('\n') + '\n';
 }
 //# sourceMappingURL=config-prompts.js.map

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

@@ -11,16 +11,25 @@ export declare const GlobalConfigSchema: z.ZodObject<{
     }>>>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         commands: "commands";
-        skills: "skills";
         both: "both";
+        skills: "skills";
     }>>>;
     workflows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    defaultStore: z.ZodOptional<z.ZodString>;
+    telemetry: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
 }, z.core.$loose>;
 export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
 /**
  * Default configuration values.
  */
 export declare const DEFAULT_CONFIG: GlobalConfigType;
+/**
+ * True when a dot-notation key path contains a prototype-reaching segment.
+ * Callers that bypass key validation (e.g. --allow-unknown) still must not bypass this.
+ */
+export declare function hasUnsafeKeySegment(path: string): boolean;
 /**
  * Validate a config key path for CLI set operations.
  * Unknown top-level keys are rejected unless explicitly allowed by the caller.