@fission-ai/openspec 1.13.2 → 1.14.0

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

@@ -136,4 +136,10 @@ export declare function findMissingCurrentScenarios(current: RequirementBlock, i
  * the counts a reader sees cannot differ between the two commands.
  */
 export declare function describeScenarioBalance(diff: ScenarioNameDiff): string;
+/**
+ * scenarioNameAt for header text whose leading `####` is already gone, as the
+ * section parser (MarkdownParser) holds it, so `show --json` names a scenario
+ * exactly as the MODIFIED loss check does.
+ */
+export declare function scenarioNameFromHeaderText(headerText: string): string;
 //# sourceMappingURL=requirement-blocks.d.ts.map

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

@@ -471,8 +471,15 @@ function scenarioHeaderAt(lines, mask, index) {
  * ATX-closed, one not) are not mistaken for a dropped scenario.
  */
 function scenarioNameAt(line) {
-    return line
-        .replace(SCENARIO_HEADER, '')
+    return scenarioNameFromHeaderText(line.replace(SCENARIO_HEADER, ''));
+}
+/**
+ * scenarioNameAt for header text whose leading `####` is already gone, as the
+ * section parser (MarkdownParser) holds it, so `show --json` names a scenario
+ * exactly as the MODIFIED loss check does.
+ */
+export function scenarioNameFromHeaderText(headerText) {
+    return headerText
         // Optional ATX closing sequence. CommonMark only treats a trailing `#` run
         // as a close when it is preceded by a space or tab — not any Unicode space —
         // so this uses `[ \t]`, not `\s`. A looser `\s` could strip a `#` run after

package/dist/core/project-config.js

@@ -181,6 +181,50 @@ function parseDeclarationList(raw) {
     return byId.size > 0 ? [...byId.values()] : undefined;
 }
 export const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit, shared with the references index
+/**
+ * Build the warning for an artifact whose `rules:` list is not an array of
+ * strings. Names the offending index and what YAML actually produced there, so
+ * a config that silently loses an entire rule set can be fixed without
+ * bisecting the list by hand. A bare `-` item containing an unquoted ": " is the
+ * common cause: YAML reads it as a mapping, so the hint points at quoting.
+ */
+function describeRulesShapeError(artifactId, rules) {
+    const base = `Rules for '${artifactId}' must be an array of strings, ignoring this artifact's rules`;
+    if (!Array.isArray(rules)) {
+        return `${base}. rules.${artifactId} is ${describeYamlType(rules)}`;
+    }
+    const bad = rules
+        .map((rule, index) => ({ rule, index }))
+        .filter(({ rule }) => typeof rule !== 'string');
+    if (bad.length === 0) {
+        return base;
+    }
+    // Name every offending index with its own shape, so a mixed list does not
+    // have to be re-bisected one item at a time.
+    const details = bad
+        .map(({ rule, index }) => `rules.${artifactId}[${index}] is ${describeYamlType(rule)}`)
+        .join('; ');
+    // A bare `-` item with an unquoted ": " is the common cause: YAML reads it as
+    // a mapping. Say so rather than leaving the reader to work out the quoting.
+    const hasMapping = bad.some(({ rule }) => rule !== null && typeof rule === 'object' && !Array.isArray(rule));
+    const hint = hasMapping
+        ? ' — an unquoted ": " makes YAML read the item as a key/value pair; quote the whole scalar to keep it a string.'
+        : '';
+    return `${base}. ${details}${hint}`;
+}
+/** Name a YAML value's shape in a warning, e.g. "a mapping" or "a number". */
+function describeYamlType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'a nested list';
+    const type = typeof value;
+    if (type === 'object')
+        return 'a mapping';
+    if (type === 'number' || type === 'boolean')
+        return `a ${type}`;
+    return `a ${type}`;
+}
 /**
  * Read and parse openspec/config.yaml from project root.
  * Uses resilient parsing - validates each field independently using Zod safeParse.
@@ -265,7 +309,7 @@ export function readProjectConfig(projectRoot) {
                         }
                     }
                     else {
-                        console.warn(`Rules for '${artifactId}' must be an array of strings, ignoring this artifact's rules`);
+                        console.warn(describeRulesShapeError(artifactId, rules));
                     }
                 }
                 if (hasValidRules) {

package/dist/core/references.js

@@ -191,7 +191,9 @@ export function renderReferencedStoresSection(entries) {
  * let hostile content forge instruction lines (slice 6.1 hardening).
  */
 export function sanitizeInline(value, maxLength = 300) {
-    const flattened = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+    const flattened = value
+        .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u206f]+/g, ' ')
+        .trim();
     return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
 }
 /**

package/dist/core/root-selection.d.ts

@@ -94,6 +94,12 @@ export declare function toRootOutput(root: ResolvedOpenSpecRoot): RootOutput;
 export declare function isStoreSelectedRoot(root: ResolvedOpenSpecRoot): root is ResolvedOpenSpecRoot & {
     storeId: string;
 };
+/**
+ * The project on the current path whose `store:` pointer names `storeId`,
+ * as a canonical path (the root walk resolves aliases). Null when the
+ * nearest root is a real planning root or points at a different store.
+ */
+export declare function findDeclaringProjectRoot(storeId: string, startPath?: string): string | null;
 /**
  * Human-mode verification signal for a selected store. Written to stderr so
  * raw-Markdown and agent-consumed stdout payloads stay clean.

package/dist/core/root-selection.js

@@ -309,6 +309,22 @@ export function toRootOutput(root) {
 export function isStoreSelectedRoot(root) {
     return root.storeId !== undefined;
 }
+/**
+ * The project on the current path whose `store:` pointer names `storeId`,
+ * as a canonical path (the root walk resolves aliases). Null when the
+ * nearest root is a real planning root or points at a different store.
+ */
+export function findDeclaringProjectRoot(storeId, startPath = process.cwd()) {
+    const nearestRoot = findQualifyingRootSync(startPath);
+    if (!nearestRoot) {
+        return null;
+    }
+    const { hasPlanningShape, pointer } = classifyOpenSpecDir(nearestRoot);
+    if (hasPlanningShape || pointer.value !== storeId) {
+        return null;
+    }
+    return nearestRoot;
+}
 /**
  * Human-mode verification signal for a selected store. Written to stderr so
  * raw-Markdown and agent-consumed stdout payloads stay clean.

package/dist/core/schemas/base.schema.d.ts

@@ -1,10 +1,13 @@
 import { z } from 'zod';
 export declare const ScenarioSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
     rawText: z.ZodString;
 }, z.core.$strip>;
 export declare const RequirementSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
     text: z.ZodString;
     scenarios: z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         rawText: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/core/schemas/base.schema.js

@@ -1,9 +1,15 @@
 import { z } from 'zod';
 import { VALIDATION_MESSAGES } from '../validation/constants.js';
 export const ScenarioSchema = z.object({
+    // Header text without `####`, the closing `#` run, and the `Scenario:`
+    // prefix. Optional so objects built outside the parser still validate.
+    name: z.string().optional(),
     rawText: z.string().min(1, VALIDATION_MESSAGES.SCENARIO_EMPTY),
 });
 export const RequirementSchema = z.object({
+    // Header text without `###` and the `Requirement:` prefix: the name archive
+    // matches MODIFIED, REMOVED and RENAMED entries against.
+    name: z.string().optional(),
     // 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

package/dist/core/schemas/change.schema.d.ts

@@ -15,14 +15,18 @@ export declare const DeltaSchema: z.ZodObject<{
     }>;
     description: z.ZodString;
     requirement: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
         scenarios: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             rawText: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
         scenarios: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             rawText: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
@@ -45,14 +49,18 @@ export declare const ChangeSchema: z.ZodObject<{
         }>;
         description: z.ZodString;
         requirement: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             text: z.ZodString;
             scenarios: z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
                 rawText: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         requirements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             text: z.ZodString;
             scenarios: z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
                 rawText: z.ZodString;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;

package/dist/core/schemas/spec.schema.d.ts

@@ -3,8 +3,10 @@ export declare const SpecSchema: z.ZodObject<{
     name: z.ZodString;
     overview: z.ZodString;
     requirements: z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
         scenarios: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
             rawText: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/dist/core/templates/workflows/apply-change.js

@@ -56,7 +56,7 @@ ${PROJECT_ROOT_GUARD}
    This returns:
    - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
    - Progress (total, complete, remaining)
-   - Task list with status
+   - Task list with status, source path, and source line
    - Dynamic instruction based on current state
    - Optional \`context\`: current required project instruction input from the selected root
    - Optional \`operationGuidance\`: current advisory guidance for apply
@@ -108,7 +108,9 @@ ${PROJECT_ROOT_GUARD}
    - Show which task is being worked on
    - Make the code changes required
    - Keep changes minimal and focused
-   - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\`
+   - Before editing, confirm the checkbox at the returned \`sourcePath\` and \`line\` still matches the task description; if it does not, rerun the apply instructions and use the refreshed location
+   - Mark the task complete at its returned \`sourcePath\` and \`line\`: \`- [ ]\` → \`- [x]\`
+   - Rerun the apply instructions and confirm that task is now done and progress changed
    - Continue to next task
 
    **Pause if:**
@@ -188,6 +190,7 @@ What would you like to do?
 - When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
 - Only mark a task \`- [x]\` when its specified behavior is fully implemented, not when it is partially done or deferred
 - Use contextFiles from CLI output, don't assume specific file names
+- Use each task's sourcePath and line to update its exact checkbox
 - Do not use context or operation guidance as proof that a task is complete
 - Apply relevant project context; report conflicts with controlling workflow inputs
 - Consider every guidance entry; explain any inapplicable or conflicting advice

package/dist/core/templates/workflows/archive-change.js

@@ -140,12 +140,23 @@ ${PROJECT_ROOT_GUARD}
    form of main specs produced by this merge; do not use them as archive guidance,
    change CLI behavior, or copy the rule text into any output file.
 
-   Then run the \`openspec-sync-specs\` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching \`specs\` instructions again. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
+   Then ${optionalWorkflow('sync', 'run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge)', 'perform the delta-to-main-spec merge inline yourself (agent-driven intelligent merge)')} for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching \`specs\` instructions again. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
+
+   If the sync reports any stop or blocking condition, treat the sync as failed.
+   Stop the archive immediately. Do not perform the post-sync content comparison and do not move its \`changeRoot\`.
+   Nothing has moved, so the user can fix the blocking condition or re-run the sync.
+
+   After the sync writes each main spec, verify its structure against the canonical sync contract:
+   - A new main spec starts with a \`# <capability> Specification\` title. An existing main spec keeps its title exactly as it is.
+   - Preserve existing \`## Purpose\` sections completely untouched for established main specs.
+   - For a new main spec, copy the delta \`## Purpose\` verbatim. Warn only if the purpose text is shorter than standard validation expects. Do not regenerate or rewrite existing authored purpose. If no usable \`## Purpose\` is provided, use the existing TBD Purpose behavior and warning.
+   - Verify that no delta-style section headers (\`## ADDED Requirements\`, \`## MODIFIED Requirements\`, \`## REMOVED Requirements\`, \`## RENAMED Requirements\`) remain in the main spec, adhering strictly to the sync workflow formatting rules.
+   - Requirement blocks the sync wrote or changed use \`### Requirement:\` headings, and their scenarios use \`#### Scenario:\` headings, under the spec's \`## Requirements\` section. Leave content the delta does not mention exactly as it is.
 
    Then re-run the comparison from the top of this step, including the explicitly retired, missing-spec case, against every capability that has a delta spec in \`artifactPaths.specs.existingOutputPaths\` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
    - ADDED requirements present
    - MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
-   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
    - RENAMED requirements present under the new name and absent under the old one
 
    If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and \`changeRoot\` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
@@ -195,7 +206,7 @@ ${PROJECT_ROOT_GUARD}
 - Don't block archive on warnings - just inform and confirm
 - Preserve .openspec.yaml when moving to archive (it moves with the directory)
 - Show clear summary of what happened
-- If sync is requested, run the \`openspec-sync-specs\` workflow inline (agent-driven)
+- If sync is requested, ${optionalWorkflow('sync', 'run the `openspec-sync-specs` workflow inline (agent-driven)', 'perform the delta-to-main-spec merge inline (agent-driven)')}
 - Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving \`changeRoot\`
 - If delta specs exist, always run the sync assessment and show the combined summary before prompting
 - Apply relevant runtime context and report conflicts; operation guidance remains advisory
@@ -342,10 +353,21 @@ ${PROJECT_ROOT_GUARD}
 
    Then ${SYNC_INLINE_HANDOFF} for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching \`specs\` instructions again. Do not delegate it to a background task — step 5 would move \`changeRoot\` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
 
+   If the sync reports any stop or blocking condition, treat the sync as failed.
+   Stop the archive immediately. Do not perform the post-sync content comparison and do not move its \`changeRoot\`.
+   Nothing has moved, so the user can fix the blocking condition or re-run the sync.
+
+   After the sync writes each main spec, verify its structure against the canonical sync contract:
+   - A new main spec starts with a \`# <capability> Specification\` title. An existing main spec keeps its title exactly as it is.
+   - Preserve existing \`## Purpose\` sections completely untouched for established main specs.
+   - For a new main spec, copy the delta \`## Purpose\` verbatim. Warn only if the purpose text is shorter than standard validation expects. Do not regenerate or rewrite existing authored purpose. If no usable \`## Purpose\` is provided, use the existing TBD Purpose behavior and warning.
+   - Verify that no delta-style section headers (\`## ADDED Requirements\`, \`## MODIFIED Requirements\`, \`## REMOVED Requirements\`, \`## RENAMED Requirements\`) remain in the main spec, adhering strictly to the sync workflow formatting rules.
+   - Requirement blocks the sync wrote or changed use \`### Requirement:\` headings, and their scenarios use \`#### Scenario:\` headings, under the spec's \`## Requirements\` section. Leave content the delta does not mention exactly as it is.
+
    Then re-run the comparison from the top of this step, including the explicitly retired, missing-spec case, against every capability that has a delta spec in \`artifactPaths.specs.existingOutputPaths\` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
    - ADDED requirements present
    - MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
-   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+   - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
    - RENAMED requirements present under the new name and absent under the old one
 
    If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and \`changeRoot\` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.

package/dist/core/templates/workflows/bulk-archive-change.js

@@ -202,6 +202,8 @@ ${PROJECT_ROOT_GUARD}
 
    a. **Sync included delta specs**:
       - ${optionalWorkflow('sync', 'Run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge)', 'Perform the delta-to-main-spec merge inline yourself (agent-driven intelligent merge)')} only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
+      - If the sync reports any stop or blocking condition, treat the sync as failed. Stop processing that change immediately. Before continuing to the next change, record this change's outcome as Failed in the batch results, including the sync blocking/error condition.
+      - Do not perform the post-sync content comparison and do not move its \`changeRoot\`; leave the change intact.
       - For conflicts, apply in resolved order.
       - Pass that change's fetched specs-rule snapshot into inline sync; inline
         sync must reuse it without fetching instructions again
@@ -216,7 +218,7 @@ ${PROJECT_ROOT_GUARD}
       - Verify that main specs are updated:
         - ADDED requirements present
         - MODIFIED requirements carrying scenario and description changes named in the delta, with their other scenarios intact
-        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
         - RENAMED requirements present under the new name and absent under the old one
       - Do not verify delta specs in \`excludedDeltas\`; they are intentionally left unsynced.
       - If sync failed or any capability does not match verification, report what differs and fail/skip moving that change's \`changeRoot\` — do not archive that change. \`changeRoot\` remains intact.
@@ -567,6 +569,8 @@ ${PROJECT_ROOT_GUARD}
 
    a. **Sync included delta specs**:
       - ${SYNC_INLINE_HANDOFF} only for changes with entries in \`includedDeltas\`, passing only the included delta paths and explicitly instructing it to ignore that change's \`excludedDeltas\`. Wait for it to finish.
+      - If the sync reports any stop or blocking condition, treat the sync as failed. Stop processing that change immediately. Before continuing to the next change, record this change's outcome as Failed in the batch results, including the sync blocking/error condition.
+      - Do not perform the post-sync content comparison and do not move its \`changeRoot\`; leave the change intact.
       - For conflicts, apply in resolved order.
       - Pass that change's fetched specs-rule snapshot into inline sync; inline
         sync must reuse it without fetching instructions again
@@ -581,7 +585,7 @@ ${PROJECT_ROOT_GUARD}
       - Verify that main specs are updated:
         - ADDED requirements present
         - MODIFIED requirements carrying scenario and description changes named in the delta, with their other scenarios intact
-        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
+        - REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving \`## Requirements\` empty), its main spec deleted rather than left empty.
         - RENAMED requirements present under the new name and absent under the old one
       - Do not verify delta specs in \`excludedDeltas\`; they are intentionally left unsynced.
       - If sync failed or any capability does not match verification, report what differs and fail/skip moving that change's \`changeRoot\` — do not archive that change. \`changeRoot\` remains intact.

package/dist/core/validation/constants.d.ts

@@ -29,7 +29,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
     readonly PURPOSE_TOO_BRIEF: "Purpose section is too brief (less than 50 characters)";
     readonly PURPOSE_IS_PLACEHOLDER: string;
-    readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
+    readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Move examples and edge cases into scenarios, or split it into separate requirements that each state one behavior.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";
     readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set \"skip_specs: true\" in the change's .openspec.yaml instead. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";

package/dist/core/validation/constants.js

@@ -43,7 +43,7 @@ export const VALIDATION_MESSAGES = {
         'writes for a new capability, or a `TBD`/`TODO` marker left in its place). Replace it with what this ' +
         'capability is for, editing the main spec directly: a `## Purpose` in a delta is read only when the ' +
         'capability is created, so it cannot replace this one.',
-    REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
+    REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Move examples and edge cases into scenarios, or split it into separate requirements that each state one behavior.`,
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
     // Guidance snippets (appended to primary messages for remediation)

package/dist/core/validation/validator.js

@@ -10,7 +10,7 @@ import { extractRequirementBody as extractRequirementBodyShared, containsShallOr
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
-import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
+import { METADATA_FILENAME, formatUnknownChangeMetadataKeysMessage, readSkipSpecsMarker, readUnknownChangeMetadataKeys, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
 import { findMissingTaskCheckboxIssues } from './task-checkboxes.js';
@@ -416,6 +416,14 @@ export class Validator {
         if (marker.invalidReason) {
             issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
         }
+        const unknownMetadataKeys = readUnknownChangeMetadataKeys(changeDir);
+        if (unknownMetadataKeys.length > 0) {
+            issues.push({
+                level: 'WARNING',
+                path: METADATA_FILENAME,
+                message: formatUnknownChangeMetadataKeysMessage(unknownMetadataKeys),
+            });
+        }
         // ANY file under specs/ contradicts the marker - not just parsed deltas.
         // Headerless or stray files would be silently dropped at archive time (and
         // some still satisfy the artifact graph's specs/**  glob) while the change

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

@@ -14,9 +14,19 @@ export declare function registryUrl(): string | null;
  * otherwise. Prereleases sort below their release (1.7.0-beta.1 < 1.7.0).
  */
 export declare function compareVersions(a: string, b: string): number;
+export type CliUpdateStatus = 'available' | 'current' | 'disabled' | 'offline';
+export interface CliUpdateCheck {
+    status: CliUpdateStatus;
+    latest: string | null;
+}
+/**
+ * Checks the registry while preserving enough detail for callers to explain
+ * why no newer version was reported. Never throws.
+ */
+export declare function checkForCliUpdate(): Promise<CliUpdateCheck>;
 /**
  * Returns the published version when the installed CLI is behind it, otherwise
- * null. Never throws and never blocks for longer than the request timeout.
+ * null. Kept as the compatibility surface used by `openspec update`.
  */
 export declare function getAvailableCliUpdate(): Promise<string | null>;
 /**
@@ -69,11 +79,23 @@ export declare function isNpmGlobalInstall(installDir: string | null, roots?: st
  */
 export declare function isSourceCheckout(installDir: string | null): boolean;
 export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
+export type InstallScope = 'global' | 'project' | 'temporary' | 'source';
+export interface CliInstallInfo {
+    location: string | null;
+    packageManager: PackageManager | null;
+    scope: InstallScope | null;
+}
 /**
  * The package manager that owns this copy, so the printed command is one the
  * user's setup will actually honor.
  */
 export declare function detectPackageManager(installDir: string | null): PackageManager;
+/** Describes the running copy without guessing when its owner is ambiguous. */
+export declare function getCliInstallInfo(installDir?: string | null, projectPath?: string): CliInstallInfo;
+/** Returns a safe update command only for an install with known global ownership. */
+export declare function getCliUpdateCommand(install: CliInstallInfo): string | null;
+/** Builds the concise human-readable form of the version report. */
+export declare function buildVersionReportLines(version: string, install: CliInstallInfo, update?: CliUpdateCheck, command?: string | null): string[];
 /**
  * Builds the hint, with the upgrade command chosen for how this copy of the CLI
  * was installed. Pure so every branch is assertable.

package/dist/core/version-check.js

@@ -6,6 +6,7 @@ import { createRequire } from 'module';
 import chalk from 'chalk';
 import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 import { getGlobalConfig, isGlobalConfigUnreadable } from './global-config.js';
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
@@ -268,22 +269,34 @@ function fetchLatestVersion() {
     });
 }
 /**
- * Returns the published version when the installed CLI is behind it, otherwise
- * null. Never throws and never blocks for longer than the request timeout.
+ * Checks the registry while preserving enough detail for callers to explain
+ * why no newer version was reported. Never throws.
  */
-export async function getAvailableCliUpdate() {
-    if (!isCheckEnabled())
-        return null;
+export async function checkForCliUpdate() {
+    if (!isCheckEnabled() || registryUrl() === null) {
+        return { status: 'disabled', latest: null };
+    }
     try {
         const latest = await fetchLatestVersion();
         if (!latest)
-            return null;
-        return compareVersions(latest, OPENSPEC_VERSION) > 0 ? latest : null;
+            return { status: 'offline', latest: null };
+        return {
+            status: compareVersions(latest, OPENSPEC_VERSION) > 0 ? 'available' : 'current',
+            latest,
+        };
     }
     catch {
-        return null;
+        return { status: 'offline', latest: null };
     }
 }
+/**
+ * Returns the published version when the installed CLI is behind it, otherwise
+ * null. Kept as the compatibility surface used by `openspec update`.
+ */
+export async function getAvailableCliUpdate() {
+    const result = await checkForCliUpdate();
+    return result.status === 'available' ? result.latest : null;
+}
 /**
  * Directory the running CLI was loaded from, or null when it cannot be
  * resolved. Shown in the upgrade hint so anyone who upgraded but still runs an
@@ -312,8 +325,8 @@ export function isProjectLocalInstall(installDir, projectPath = '.') {
     // Windows paths differ in case and drive-letter casing between sources.
     const normalize = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
     try {
-        let dir = path.resolve(projectPath);
-        const target = normalize(installDir);
+        let dir = FileSystemUtils.canonicalizeExistingPath(projectPath);
+        const target = normalize(FileSystemUtils.canonicalizeExistingPath(installDir));
         for (;;) {
             if (target.startsWith(normalize(path.join(dir, 'node_modules') + path.sep))) {
                 return true;
@@ -443,32 +456,29 @@ export function isSourceCheckout(installDir) {
         return false;
     }
 }
-/**
- * The package manager that owns this copy, so the printed command is one the
- * user's setup will actually honor.
- */
-export function detectPackageManager(installDir) {
-    // Lowercased because the Windows directories are capitalized and undotted:
-    // %LOCALAPPDATA%\\Volta, \\Yarn\\Data, \\pnpm-cache.
+function detectKnownPackageManager(installDir) {
     const segments = (installDir ?? '').split(/[\\/]/).map((segment) => segment.toLowerCase());
     const has = (...names) => names.some((name) => segments.includes(name));
-    // The undotted spelling exists for Windows (%LOCALAPPDATA%\Volta), whose
-    // layout nests tools\image; require both segments so a user or project
-    // directory merely named "volta" (even one with its own "tools" dir) does
-    // not steal the install.
     if (has('.volta') || (has('volta') && has('tools') && has('image')))
         return 'volta';
-    if (has('.bun'))
+    if (has('.bun', '_bunx', 'bun-cache'))
         return 'bun';
-    // These two need a corroborating segment: a directory merely named "pnpm" or
-    // "yarn" (a user's home, a project) is not a global install of one.
-    if (has('.pnpm-global', 'pnpm-cache'))
+    if (has('_npx'))
+        return 'npm';
+    if (has('.pnpm', '.pnpm-global', 'pnpm-cache'))
         return 'pnpm';
     if (has('pnpm') && has('global', 'dlx', 'store'))
         return 'pnpm';
     if (has('.yarn') || (has('yarn') && has('global')))
         return 'yarn';
-    return 'npm';
+    return null;
+}
+/**
+ * The package manager that owns this copy, so the printed command is one the
+ * user's setup will actually honor.
+ */
+export function detectPackageManager(installDir) {
+    return detectKnownPackageManager(installDir) ?? 'npm';
 }
 const GLOBAL_UPGRADE_COMMANDS = {
     npm: `npm install -g ${PACKAGE_NAME}@latest`,
@@ -477,6 +487,82 @@ const GLOBAL_UPGRADE_COMMANDS = {
     yarn: `yarn global add ${PACKAGE_NAME}@latest`,
     volta: `volta install ${PACKAGE_NAME}@latest`,
 };
+function detectGlobalPackageManager(installDir) {
+    if (isNpmGlobalInstall(installDir))
+        return 'npm';
+    if (!installDir)
+        return null;
+    const segments = installDir.split(/[\\/]/).map((segment) => segment.toLowerCase());
+    const has = (...names) => names.some((name) => segments.includes(name));
+    const hasSequence = (...names) => segments.some((_, index) => names.every((name, offset) => segments[index + offset] === name));
+    if (hasSequence('.volta', 'tools', 'image') || hasSequence('volta', 'tools', 'image')) {
+        return 'volta';
+    }
+    if (has('.pnpm-global') || hasSequence('pnpm', 'global'))
+        return 'pnpm';
+    if (hasSequence('yarn', 'global') || hasSequence('yarn', 'data', 'global'))
+        return 'yarn';
+    if (hasSequence('.bun', 'install', 'global'))
+        return 'bun';
+    return null;
+}
+/** Describes the running copy without guessing when its owner is ambiguous. */
+export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.') {
+    if (!installDir) {
+        return { location: null, packageManager: null, scope: null };
+    }
+    if (isSourceCheckout(installDir)) {
+        return { location: installDir, packageManager: null, scope: 'source' };
+    }
+    if (isEphemeralRunnerInstall(installDir)) {
+        return {
+            location: installDir,
+            packageManager: detectKnownPackageManager(installDir),
+            scope: 'temporary',
+        };
+    }
+    if (isProjectLocalInstall(installDir, projectPath)) {
+        return {
+            location: installDir,
+            packageManager: detectKnownPackageManager(installDir),
+            scope: 'project',
+        };
+    }
+    const packageManager = detectGlobalPackageManager(installDir);
+    return {
+        location: installDir,
+        packageManager,
+        scope: packageManager ? 'global' : null,
+    };
+}
+/** Returns a safe update command only for an install with known global ownership. */
+export function getCliUpdateCommand(install) {
+    if (install.scope !== 'global' || install.packageManager === null)
+        return null;
+    return GLOBAL_UPGRADE_COMMANDS[install.packageManager];
+}
+/** Builds the concise human-readable form of the version report. */
+export function buildVersionReportLines(version, install, update, command = null) {
+    const details = [install.packageManager, install.scope].filter(Boolean).join(', ');
+    const lines = [`OpenSpec ${version}${details ? ` (${details})` : ''}`];
+    if (!update)
+        return lines;
+    if (update.status === 'available') {
+        lines.push(`Update available: ${update.latest}`);
+        if (command)
+            lines.push(`  ${command}`);
+    }
+    else if (update.status === 'current') {
+        lines.push('OpenSpec is up to date.');
+    }
+    else if (update.status === 'disabled') {
+        lines.push('Update check disabled.');
+    }
+    else {
+        lines.push('Could not check for updates.');
+    }
+    return lines;
+}
 /**
  * Builds the hint, with the upgrade command chosen for how this copy of the CLI
  * was installed. Pure so every branch is assertable.