@fission-ai/openspec 1.13.2 → 1.14.1

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
@@ -66,7 +66,7 @@ ${PROJECT_ROOT_GUARD}
    - If \`state: "blocked"\`: show the message and pause implementation.
      - If \`missingArtifacts\` is non-empty: ${BLOCKED_STATE_HANDOFF}
      - Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked.
-   - If \`state: "all_done"\`: congratulate, suggest archive
+   - If \`state: "all_done"\`: report that all tracked tasks are complete and suggest review or verification as appropriate before archiving
    - Otherwise: proceed to implementation
 
    Treat \`context\` as a required prompt-level input. Read and consider it, and
@@ -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:**
@@ -123,7 +125,7 @@ ${PROJECT_ROOT_GUARD}
    Display:
    - Tasks completed this session
    - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
+   - If all done: report that tracked tasks are complete and suggest review or verification as appropriate before archiving
    - If paused: explain why and wait for guidance
 
 **Output During Implementation**
@@ -154,7 +156,8 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! ${ARCHIVE_HANDOFF}
+All tracked tasks are complete. Review or verify the change as appropriate
+before archiving. ${ARCHIVE_HANDOFF}
 \`\`\`
 
 **Output On Pause (Issue Encountered)**
@@ -188,6 +191,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/templates/workflows/continue-change.js

@@ -7,6 +7,15 @@ import { PROJECT_ROOT_GUARD } from './project-root.js';
  * optional-workflow.ts).
  */
 const PLANNING_COMPLETE_HANDOFF = optionalWorkflow('apply', 'You can now implement this change with `/opsx:apply`.', 'You can now implement this change - `openspec instructions apply --change "<name>" --json` returns the tasks and how to work them.') + ' ' + optionalWorkflow('archive', 'Once implementation and any tracked work are complete, archive it with `/opsx:archive`.', 'Once implementation and any tracked work are complete, archive it with `openspec archive "<name>"`.');
+/**
+ * A glob artifact reads `done` once one matching file exists, so a run
+ * interrupted while writing several files leaves it `done` with files missing,
+ * and the next run would move on without reading its instruction again (#2034).
+ */
+const PARTIAL_ARTIFACT_CHECK = `**Before anything else, finish a partly written artifact**:
+   - An artifact whose output is a glob pattern (e.g. \`specs/**/*.md\`) reads \`done\` as soon as one matching file exists, so a run interrupted while writing its files leaves it \`done\` with some still missing
+   - For each such \`done\` artifact, first get its instructions and read any completed dependencies needed to determine the expected files. Then compare those files with \`artifactPaths.<id>.existingOutputPaths\`. For spec-driven's \`specs\`, read the proposal and check for one \`specs/<capability-path>/spec.md\` per capability it lists; resolve each expected path against \`changeRoot\` before comparing path identity
+   - If any are missing, write only the missing files, and STOP - that counts as this invocation's ONE artifact. If you cannot tell whether a file was left out on purpose, ask the user`;
 export function getContinueChangeSkillTemplate() {
     return {
         name: 'openspec-continue-change',
@@ -51,6 +60,10 @@ ${PROJECT_ROOT_GUARD}
 
    ---
 
+   ${PARTIAL_ARTIFACT_CHECK}
+
+   ---
+
    **If all planning artifacts are complete (\`isPlanningComplete: true\`, or legacy \`isComplete: true\`)**:
    - Congratulate the user
    - Show final status including the schema used
@@ -169,6 +182,10 @@ ${PROJECT_ROOT_GUARD}
 
    ---
 
+   ${PARTIAL_ARTIFACT_CHECK}
+
+   ---
+
    **If all planning artifacts are complete (\`isPlanningComplete: true\`, or legacy \`isComplete: true\`)**:
    - Congratulate the user
    - Show final status including the schema used

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

@@ -76,9 +76,9 @@ ${PROJECT_ROOT_GUARD}
      - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
 
    **Spec Coverage**:
-   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact, report the spec-dependent checks as not applicable.
-   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema. If \`contextFiles.specs\` is absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
-   - If delta specs exist in \`contextFiles.specs\`:
+   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact (no artifact whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`), report the spec-dependent checks as not applicable.
+   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema, so do not assume an id such as \`specs\`. The spec artifacts are those whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`; read their files from \`contextFiles.<id>\`. If those spec files are absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
+   - If delta specs exist in those spec files:
      - Extract all requirements (marked with "### Requirement:", or listed as \`FROM:\`/\`TO:\` pairs under \`## RENAMED Requirements\`) and note the delta section each one sits under: \`## ADDED\`, \`## MODIFIED\`, \`## REMOVED\`, or \`## RENAMED Requirements\`. The section decides what the check looks for.
      - For each ADDED or MODIFIED requirement (for MODIFIED, check the text in the delta, not the old wording):
        - Search codebase for keywords related to the requirement
@@ -127,14 +127,14 @@ ${PROJECT_ROOT_GUARD}
 7. **Verify Coherence**
 
    **Design Adherence**:
-   - If the schema defines no design artifact, report **Design Adherence** as not applicable.
-   - If \`contextFiles.design\` exists:
+   - If the schema defines no design artifact (no artifact with id \`design\`, and none whose \`artifactPaths.<id>.outputPath\` is or ends in \`design.md\`), report **Design Adherence** as not applicable.
+   - If the design artifact's \`contextFiles.<id>\` file exists:
      - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
      - Verify implementation follows those decisions
      - If contradiction detected:
        - Add WARNING: "Design decision not followed: <decision>"
        - Recommendation: "Update implementation or revise design.md to match reality"
-   - Otherwise, if \`contextFiles.design\` is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
+   - Otherwise, if the design artifact's \`contextFiles.<id>\` file is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
 
    **Code Pattern Consistency**:
    - If implementation changes cannot be identified, mark **Code Pattern Consistency** as not verified and explain the missing evidence.
@@ -285,9 +285,9 @@ ${PROJECT_ROOT_GUARD}
      - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
 
    **Spec Coverage**:
-   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact, report the spec-dependent checks as not applicable.
-   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema. If \`contextFiles.specs\` is absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
-   - If delta specs exist in \`contextFiles.specs\`:
+   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact (no artifact whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`), report the spec-dependent checks as not applicable.
+   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema, so do not assume an id such as \`specs\`. The spec artifacts are those whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`; read their files from \`contextFiles.<id>\`. If those spec files are absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
+   - If delta specs exist in those spec files:
      - Extract all requirements (marked with "### Requirement:", or listed as \`FROM:\`/\`TO:\` pairs under \`## RENAMED Requirements\`) and note the delta section each one sits under: \`## ADDED\`, \`## MODIFIED\`, \`## REMOVED\`, or \`## RENAMED Requirements\`. The section decides what the check looks for.
      - For each ADDED or MODIFIED requirement (for MODIFIED, check the text in the delta, not the old wording):
        - Search codebase for keywords related to the requirement
@@ -336,14 +336,14 @@ ${PROJECT_ROOT_GUARD}
 7. **Verify Coherence**
 
    **Design Adherence**:
-   - If the schema defines no design artifact, report **Design Adherence** as not applicable.
-   - If \`contextFiles.design\` exists:
+   - If the schema defines no design artifact (no artifact with id \`design\`, and none whose \`artifactPaths.<id>.outputPath\` is or ends in \`design.md\`), report **Design Adherence** as not applicable.
+   - If the design artifact's \`contextFiles.<id>\` file exists:
      - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
      - Verify implementation follows those decisions
      - If contradiction detected:
        - Add WARNING: "Design decision not followed: <decision>"
        - Recommendation: "Update implementation or revise design.md to match reality"
-   - Otherwise, if \`contextFiles.design\` is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
+   - Otherwise, if the design artifact's \`contextFiles.<id>\` file is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
 
    **Code Pattern Consistency**:
    - If implementation changes cannot be identified, mark **Code Pattern Consistency** as not verified and explain the missing evidence.

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';
@@ -252,6 +252,17 @@ export class Validator {
                             message: this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name, true),
                         });
                     }
+                    // Same limit the main spec enforces after archive (#1976), so
+                    // `validate <change> --strict` catches a new overlong requirement
+                    // before it lands. MODIFIED is left alone: its text is the existing
+                    // requirement, which the specs instruction says to keep whole.
+                    if (requirementText && requirementText.length > MAX_REQUIREMENT_TEXT_LENGTH) {
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: `ADDED "${block.name}": ${VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG}`,
+                        });
+                    }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}` });
@@ -416,6 +427,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
@@ -703,7 +722,7 @@ export class Validator {
         spec.requirements.forEach((req, index) => {
             if (req.text.length > MAX_REQUIREMENT_TEXT_LENGTH) {
                 issues.push({
-                    level: 'INFO',
+                    level: 'WARNING',
                     path: `requirements[${index}]`,
                     message: VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG,
                 });

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.