freeharness 0.4.1 → 0.4.2

package/node_modules/@freeharness/sdd/dist/vendor/openspec/generation/templates/workflows/sync-specs.js

@@ -1,14 +1,17 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
 export function getSyncSpecsSkillTemplate() {
     return {
         name: 'openspec-sync-specs',
-        description: 'Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.',
+        description: 'Sync delta specs from an OpenSpec change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.',
         instructions: `Sync delta specs from a change to main specs.
 
 This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 \`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve the full path from each delta spec when resolving its main spec.
 
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
@@ -89,6 +92,13 @@ ${STORE_SELECTION_GUIDANCE}
 
    b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` (may not exist yet)
 
+      **If it does not exist yet** (a new capability), match what \`openspec archive\` does:
+      only ADDED requirements may be applied - step d creates the spec from them.
+      MODIFIED and RENAMED have no requirement to act on, so stop the sync for that
+      capability and report that its main spec does not exist and only ADDED is allowed
+      for a new spec; never invent the missing requirement. REMOVED has nothing to
+      remove - skip it and warn.
+
    c. **Apply changes intelligently**:
 
       **ADDED Requirements:**
@@ -136,6 +146,14 @@ ${STORE_SELECTION_GUIDANCE}
         (this is what \`openspec archive\` does; it warns and moves on)
 
    d. **Create new main spec** if capability doesn't exist yet:
+      - Only when the delta has ADDED requirements to put in it and no MODIFIED or
+        RENAMED requirements blocked this capability in step b. Otherwise create nothing
+        and leave the specs directory untouched. For a REMOVED-only delta, if the change's
+        \`.openspec.yaml\` declares \`retire_capabilities: true\`, report it as already retired
+        and continue without recreating the spec. Without that marker, report the sync as blocked:
+        \`openspec archive\` rejects it with \`Spec must have at least one requirement\`.
+        An empty delta has no operations to sync; report it as blocked too.
+        Never write an empty \`## Requirements\` section.
       - Create \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`
       - Add Purpose section: copy the delta's \`## Purpose\` body verbatim when it has one
         (this is what \`openspec archive\` does); only write a brief TBD placeholder when it does not
@@ -270,6 +288,8 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 \`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve the full path from each delta spec when resolving its main spec.
 
 **Input**: Optionally specify a change name after \`/opsx:sync\` (e.g., \`/opsx:sync add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
@@ -350,6 +370,13 @@ ${STORE_SELECTION_GUIDANCE}
 
    b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` (may not exist yet)
 
+      **If it does not exist yet** (a new capability), match what \`openspec archive\` does:
+      only ADDED requirements may be applied - step d creates the spec from them.
+      MODIFIED and RENAMED have no requirement to act on, so stop the sync for that
+      capability and report that its main spec does not exist and only ADDED is allowed
+      for a new spec; never invent the missing requirement. REMOVED has nothing to
+      remove - skip it and warn.
+
    c. **Apply changes intelligently**:
 
       **ADDED Requirements:**
@@ -397,6 +424,14 @@ ${STORE_SELECTION_GUIDANCE}
         (this is what \`openspec archive\` does; it warns and moves on)
 
    d. **Create new main spec** if capability doesn't exist yet:
+      - Only when the delta has ADDED requirements to put in it and no MODIFIED or
+        RENAMED requirements blocked this capability in step b. Otherwise create nothing
+        and leave the specs directory untouched. For a REMOVED-only delta, if the change's
+        \`.openspec.yaml\` declares \`retire_capabilities: true\`, report it as already retired
+        and continue without recreating the spec. Without that marker, report the sync as blocked:
+        \`openspec archive\` rejects it with \`Spec must have at least one requirement\`.
+        An empty delta has no operations to sync; report it as blocked too.
+        Never write an empty \`## Requirements\` section.
       - Create \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`
       - Add Purpose section: copy the delta's \`## Purpose\` body verbatim when it has one
         (this is what \`openspec archive\` does); only write a brief TBD placeholder when it does not

package/node_modules/@freeharness/sdd/dist/vendor/openspec/generation/templates/workflows/update-change.js

@@ -1,4 +1,21 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * Passages that would hand off to \`/opsx:continue\` or \`/opsx:new\`. Neither
+ * workflow is among FreeHarness's six emitted workflows, so each always
+ * renders the CLI fallback rather than naming a skill that was never
+ * generated.
+ */
+const CONTINUE_SCOPE_NOTE = 'This workflow revises artifacts that already exist; it never creates missing ones. When an artifact is missing, `openspec status --change "<name>" --json` names the next one and `openspec instructions "<artifact-id>" --change "<name>" --json` explains how to write it.';
+const CONTINUE_CREATE_THEM = 'point the user to `openspec instructions "<artifact-id>" --change "<name>" --json` for how to create them';
+const CONTINUE_NEXT_STEP = 'run `openspec status --change "<name>" --json` for the next artifact and point the user to `openspec instructions "<artifact-id>" --change "<name>" --json` for how to create it';
+const CONTINUE_DEFERRED = 'Anything deferred because it does not exist yet (artifacts with no files and status `ready` or `blocked`, never `skipped` artifacts)';
+const CONTINUE_FRONTIER = 'creating them is a separate step, outside this workflow';
+const INTENT_CHANGE_GUARDRAIL = 'ask for a distinct unused change name and recommend `openspec new change "<new-change-name>"` instead (the "Update vs. Start Fresh" heuristic)';
+/** \`apply\` and \`archive\` are both shipped, so their handoffs always name the slash command. */
+const APPLY_DELTA_HANDOFF = 'suggest `/opsx:apply` to carry the delta into code';
+const APPLY_GUARDRAIL = 'stop and point to `/opsx:apply`';
+const ARCHIVE_HANDOFF = 'suggest `/opsx:archive`';
 export function getUpdateChangeSkillTemplate() {
     return {
         name: 'openspec-update-change',
@@ -7,9 +24,11 @@ export function getUpdateChangeSkillTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-\`/opsx:continue\` is an optional workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+${CONTINUE_SCOPE_NOTE}
 
 **Steps**
 
@@ -22,7 +41,6 @@ ${STORE_SELECTION_GUIDANCE}
 
    When prompting, present the top 3-4 most recently modified changes as options, showing:
    - Change name
-   - Schema (from \`schema\` field if present, otherwise "spec-driven")
    - Status (e.g., "0/5 tasks", "complete", "no tasks")
    - How recently it was modified (from \`lastModified\` field)
 
@@ -42,7 +60,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
 
-   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`), plus any confirmed concrete path allowed under a partly populated glob artifact (step 4). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
 
 3. **Understand the request**
    - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
@@ -50,13 +68,20 @@ ${STORE_SELECTION_GUIDANCE}
 
 4. **Read and reconcile**
    - Read the artifact(s) the request touches and the change's other existing artifacts.
-   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
+   - Draft the requested edit in the conversation, not in files. Work out exactly what it changes; step 5 owns every write. Then check every other existing artifact against the drafted edit - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
    - Note everything that is now inconsistent, missing, or contradictory.
-   - Revise only files that already exist (\`existingOutputPaths\`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to \`/opsx:continue\` to create them.
-   - If the change is already coherent, say so and make no edits.
+   - Propose revisions to files that already exist (\`existingOutputPaths\`). If an artifact has no existing output files and status \`ready\` or \`blocked\`, note it and ${CONTINUE_CREATE_THEM}. Leave \`skipped\` artifacts untouched; do not treat them as missing or defer them to the continue workflow.
+   - A glob artifact (e.g. \`specs/**/*.md\`) is marked \`done\` after at least one file matches, and the continue workflow only handles \`ready\` artifacts. When reconciliation identifies a missing file for a glob artifact whose \`existingOutputPaths\` is non-empty:
+     1. Run \`openspec instructions "<artifact-id>" --change "<name>" --json\` and use its \`instruction\` and \`template\`. Treat \`context\` and \`rules\` as constraints; do not copy them into the file. If instructions report \`skipped: true\`, do not create the file. Read current dependency files from disk; if a required non-skipped dependency is missing, stop and ask the user to restore it first.
+     2. Choose a concrete path inside \`changeRoot\` that matches \`artifactPaths.<id>.outputPath\` and does not already exist. Verify it remains inside \`changeRoot\` after resolving any symlinked parent directories. The glob \`resolvedOutputPath\` is not a valid target.
+     3. Include the new file in step 5's proposed revisions and create it only after the user confirms.
+     4. After confirmation, immediately before creation, refresh status and instructions. Verify the artifact is still in scope, not skipped, and partially populated; repeat the concrete-path checks above.
+     5. Use a create operation that fails if the target already exists. If \`instruction\` delegates creation to another skill or command, invoke it only if it can honor the confirmed path and these guardrails; otherwise stop. If any check fails or the confirmed draft is no longer valid, stop and reconcile with the user rather than replacing existing content or choosing a different path.
+   - If the change is already coherent, say so and propose no revisions.
 
 5. **Confirm and apply, one artifact at a time**
-   - Show each proposed revision and why. Write only after the user confirms.
+   - This step performs every artifact write in this workflow; no earlier step edits an artifact.
+   - Show each proposed revision and why - including the requested edit drafted in step 4. Write only after the user confirms.
    - If the user rejects a revision, do not write it - leave that artifact unchanged.
    - When a substantial rewrite is needed, get that artifact's rules and template first:
      \`\`\`bash
@@ -64,24 +89,25 @@ ${STORE_SELECTION_GUIDANCE}
      \`\`\`
 
 6. **Point to the next step (guidance only - NEVER act on it)**
-   - Artifacts still missing -> suggest \`/opsx:continue\` to create them.
-   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest \`/opsx:apply\` to carry the delta into code.
-   - Everything done and implemented -> suggest \`/opsx:archive\`.
+   - Artifacts with empty \`existingOutputPaths\` and status \`ready\` or \`blocked\` -> ${CONTINUE_NEXT_STEP}.
+   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; ${APPLY_DELTA_HANDOFF}.
+   - Everything done and implemented -> ${ARCHIVE_HANDOFF}.
 
 **Output**
 
 After each invocation, show:
 - Which artifacts were revised (and which proposed revisions were rejected)
-- Anything deferred to \`/opsx:continue\` (not-yet-created artifacts or files)
+- Any file created under a glob artifact that was already partially populated
+- ${CONTINUE_DEFERRED}
 - Where the change stands and the recommended next command
 
 **Guardrails**
-- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to \`/opsx:apply\`.
+- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, ${APPLY_GUARDRAIL}.
 - Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names.
-- Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
-- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
+- Edit only the concrete files in \`existingOutputPaths\`, plus any confirmed concrete path allowed under a partly populated glob artifact (step 4); never write to a glob \`resolvedOutputPath\`.
+- Do not advance the build frontier: if an artifact has empty \`existingOutputPaths\` and status \`ready\` or \`blocked\`, ${CONTINUE_FRONTIER}. Leave \`skipped\` artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose \`existingOutputPaths\` is non-empty.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, first verify whether the optional \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`,
+- If the request changes the change's *intent* rather than refining it, ${INTENT_CHANGE_GUARDRAIL}.`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -97,9 +123,11 @@ export function getOpsxUpdateCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name after \`/opsx:update\` (e.g., \`/opsx:update add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-\`/opsx:continue\` is an optional workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+${CONTINUE_SCOPE_NOTE}
 
 **Steps**
 
@@ -112,7 +140,6 @@ ${STORE_SELECTION_GUIDANCE}
 
    When prompting, present the top 3-4 most recently modified changes as options, showing:
    - Change name
-   - Schema (from \`schema\` field if present, otherwise "spec-driven")
    - Status (e.g., "0/5 tasks", "complete", "no tasks")
    - How recently it was modified (from \`lastModified\` field)
 
@@ -132,7 +159,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
 
-   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
+   The files to edit are \`artifactPaths.<id>.existingOutputPaths\` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. \`specs/**/*.md\`), plus any confirmed concrete path allowed under a partly populated glob artifact (step 4). Do NOT write to \`resolvedOutputPath\`: for a glob artifact it is still the glob pattern, not a real file.
 
 3. **Understand the request**
    - If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
@@ -140,13 +167,20 @@ ${STORE_SELECTION_GUIDANCE}
 
 4. **Read and reconcile**
    - Read the artifact(s) the request touches and the change's other existing artifacts.
-   - Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
+   - Draft the requested edit in the conversation, not in files. Work out exactly what it changes; step 5 owns every write. Then check every other existing artifact against the drafted edit - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
    - Note everything that is now inconsistent, missing, or contradictory.
-   - Revise only files that already exist (\`existingOutputPaths\`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to \`/opsx:continue\` to create them.
-   - If the change is already coherent, say so and make no edits.
+   - Propose revisions to files that already exist (\`existingOutputPaths\`). If an artifact has no existing output files and status \`ready\` or \`blocked\`, note it and ${CONTINUE_CREATE_THEM}. Leave \`skipped\` artifacts untouched; do not treat them as missing or defer them to the continue workflow.
+   - A glob artifact (e.g. \`specs/**/*.md\`) is marked \`done\` after at least one file matches, and the continue workflow only handles \`ready\` artifacts. When reconciliation identifies a missing file for a glob artifact whose \`existingOutputPaths\` is non-empty:
+     1. Run \`openspec instructions "<artifact-id>" --change "<name>" --json\` and use its \`instruction\` and \`template\`. Treat \`context\` and \`rules\` as constraints; do not copy them into the file. If instructions report \`skipped: true\`, do not create the file. Read current dependency files from disk; if a required non-skipped dependency is missing, stop and ask the user to restore it first.
+     2. Choose a concrete path inside \`changeRoot\` that matches \`artifactPaths.<id>.outputPath\` and does not already exist. Verify it remains inside \`changeRoot\` after resolving any symlinked parent directories. The glob \`resolvedOutputPath\` is not a valid target.
+     3. Include the new file in step 5's proposed revisions and create it only after the user confirms.
+     4. After confirmation, immediately before creation, refresh status and instructions. Verify the artifact is still in scope, not skipped, and partially populated; repeat the concrete-path checks above.
+     5. Use a create operation that fails if the target already exists. If \`instruction\` delegates creation to another skill or command, invoke it only if it can honor the confirmed path and these guardrails; otherwise stop. If any check fails or the confirmed draft is no longer valid, stop and reconcile with the user rather than replacing existing content or choosing a different path.
+   - If the change is already coherent, say so and propose no revisions.
 
 5. **Confirm and apply, one artifact at a time**
-   - Show each proposed revision and why. Write only after the user confirms.
+   - This step performs every artifact write in this workflow; no earlier step edits an artifact.
+   - Show each proposed revision and why - including the requested edit drafted in step 4. Write only after the user confirms.
    - If the user rejects a revision, do not write it - leave that artifact unchanged.
    - When a substantial rewrite is needed, get that artifact's rules and template first:
      \`\`\`bash
@@ -154,23 +188,24 @@ ${STORE_SELECTION_GUIDANCE}
      \`\`\`
 
 6. **Point to the next step (guidance only - NEVER act on it)**
-   - Artifacts still missing -> suggest \`/opsx:continue\` to create them.
-   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest \`/opsx:apply\` to carry the delta into code.
-   - Everything done and implemented -> suggest \`/opsx:archive\`.
+   - Artifacts with empty \`existingOutputPaths\` and status \`ready\` or \`blocked\` -> ${CONTINUE_NEXT_STEP}.
+   - Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; ${APPLY_DELTA_HANDOFF}.
+   - Everything done and implemented -> ${ARCHIVE_HANDOFF}.
 
 **Output**
 
 After each invocation, show:
 - Which artifacts were revised (and which proposed revisions were rejected)
-- Anything deferred to \`/opsx:continue\` (not-yet-created artifacts or files)
+- Any file created under a glob artifact that was already partially populated
+- ${CONTINUE_DEFERRED}
 - Where the change stands and the recommended next command
 
 **Guardrails**
-- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to \`/opsx:apply\`.
+- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, ${APPLY_GUARDRAIL}.
 - Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names.
-- Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
-- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
+- Edit only the concrete files in \`existingOutputPaths\`, plus any confirmed concrete path allowed under a partly populated glob artifact (step 4); never write to a glob \`resolvedOutputPath\`.
+- Do not advance the build frontier: if an artifact has empty \`existingOutputPaths\` and status \`ready\` or \`blocked\`, ${CONTINUE_FRONTIER}. Leave \`skipped\` artifacts untouched. The only new-file scope is a confirmed concrete path under a glob artifact whose \`existingOutputPaths\` is non-empty.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, first verify whether the optional \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`
+- If the request changes the change's *intent* rather than refining it, ${INTENT_CHANGE_GUARDRAIL}.`
     };
 }

package/node_modules/@freeharness/sdd/dist/vendor/openspec/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/node_modules/@freeharness/sdd/dist/vendor/openspec/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/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/change-parser.d.ts

@@ -6,22 +6,17 @@ export declare class ChangeParser extends MarkdownParser {
     parseChangeWithDeltas(name: string): Promise<Change>;
     private parseDeltaSpecs;
     /**
-     * Read requirements from a delta section, ignoring headers that are not
-     * `### Requirement: <name>`.
-     *
-     * A delta section often carries divider headers such as
-     * `### Documentation Requirements`. The base parser treats every child header
-     * as a requirement, which invented a scenario-less requirement that does not
-     * exist (#498): archive warned about a missing scenario, and `show --json`
-     * reported an extra delta. The delta reader already skips these headers and
-     * notes them, so this keeps the two readers in agreement.
-     *
-     * Overriding here rather than in MarkdownParser keeps main spec parsing —
-     * `view`, `list`, `spec --json`, spec validation — untouched.
+     * Reads requirements from a delta section, ignoring headers that are not
+     * `### Requirement: <name>` - a divider like `### Documentation
+     * Requirements` would otherwise be read as a scenario-less requirement,
+     * which the delta reader already skips and notes. Overriding here rather
+     * than in MarkdownParser keeps main spec parsing untouched.
      */
     protected parseRequirements(section: Section): Requirement[];
+    /** The deltas in one spec file, read by parseDeltaSpec - the same reader archive applies. */
     private parseSpecDeltas;
-    private parseRenames;
+    /** One Requirement per block, via the same section parser and header filter as before. */
+    private toRequirements;
     private parseSectionsFromContent;
     private getContentUntilNextHeaderFromLines;
 }

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/change-parser.js

@@ -1,8 +1,14 @@
 import { MarkdownParser } from './markdown-parser.js';
 import { buildCodeFenceMask } from './requirement-text.js';
+import { parseDeltaSpec } from './requirement-blocks.js';
 import path from 'path';
 import { promises as fs } from 'fs';
 import { discoverSpecFiles } from '../spec-discovery.js';
+/** A header-only block for a REMOVED entry written in the bullet form. */
+function removedNameBlock(name) {
+    const headerLine = `### Requirement: ${name}`;
+    return { headerLine, name, raw: headerLine };
+}
 export class ChangeParser extends MarkdownParser {
     changeDir;
     constructor(content, changeDir) {
@@ -19,13 +25,14 @@ export class ChangeParser extends MarkdownParser {
         if (!whatChanges) {
             throw new Error('Change must have a What Changes section');
         }
-        // Parse deltas from the What Changes section (simple format)
-        const simpleDeltas = this.parseDeltas(whatChanges);
-        // Check if there are spec files with delta format
-        const specsDir = path.join(this.changeDir, 'specs');
-        const deltaDeltas = await this.parseDeltaSpecs(specsDir);
-        // Combine both types of deltas, preferring delta format if available
-        const deltas = deltaDeltas.length > 0 ? deltaDeltas : simpleDeltas;
+        // A spec file with a delta section is the only source of structured
+        // deltas, even when the section applies to nothing - else a bullet-form
+        // REMOVED fell through to the prose fallback below as an invented
+        // MODIFIED. The prose is used only when no spec file has a delta section:
+        // no spec files, or a legacy change with full future-state specs.
+        const specFiles = await discoverSpecFiles(path.join(this.changeDir, 'specs'));
+        const { deltas: specDeltas, hasDeltaSections } = await this.parseDeltaSpecs(specFiles);
+        const deltas = hasDeltaSections ? specDeltas : this.parseDeltas(whatChanges);
         return {
             name,
             why: why.trim(),
@@ -37,37 +44,32 @@ export class ChangeParser extends MarkdownParser {
             },
         };
     }
-    async parseDeltaSpecs(specsDir) {
+    // specFiles comes from discoverSpecFiles, which walks specs/ recursively so
+    // nested layouts like specs/<area>/<capability>/spec.md are parsed too.
+    async parseDeltaSpecs(specFiles) {
         const deltas = [];
-        // Discover delta specs recursively so nested layouts like
-        // specs/<area>/<capability>/spec.md are parsed too (#1353)
-        const specFiles = await discoverSpecFiles(specsDir);
+        let hasDeltaSections = false;
         for (const { id, specFile } of specFiles) {
             try {
                 const content = await fs.readFile(specFile, 'utf-8');
-                const specDeltas = this.parseSpecDeltas(id, content);
-                deltas.push(...specDeltas);
+                const plan = parseDeltaSpec(content);
+                if (Object.values(plan.sectionPresence).some(Boolean))
+                    hasDeltaSections = true;
+                deltas.push(...this.parseSpecDeltas(id, plan));
             }
             catch (error) {
                 // Spec file might not be readable, which is okay
                 continue;
             }
         }
-        return deltas;
+        return { deltas, hasDeltaSections };
     }
     /**
-     * Read requirements from a delta section, ignoring headers that are not
-     * `### Requirement: <name>`.
-     *
-     * A delta section often carries divider headers such as
-     * `### Documentation Requirements`. The base parser treats every child header
-     * as a requirement, which invented a scenario-less requirement that does not
-     * exist (#498): archive warned about a missing scenario, and `show --json`
-     * reported an extra delta. The delta reader already skips these headers and
-     * notes them, so this keeps the two readers in agreement.
-     *
-     * Overriding here rather than in MarkdownParser keeps main spec parsing —
-     * `view`, `list`, `spec --json`, spec validation — untouched.
+     * Reads requirements from a delta section, ignoring headers that are not
+     * `### Requirement: <name>` - a divider like `### Documentation
+     * Requirements` would otherwise be read as a scenario-less requirement,
+     * which the delta reader already skips and notes. Overriding here rather
+     * than in MarkdownParser keeps main spec parsing untouched.
      */
     parseRequirements(section) {
         return super.parseRequirements({
@@ -75,89 +77,64 @@ export class ChangeParser extends MarkdownParser {
             children: section.children.filter((child) => /^Requirement:\s*\S/i.test(child.title.trim())),
         });
     }
-    parseSpecDeltas(specName, content) {
+    /** The deltas in one spec file, read by parseDeltaSpec - the same reader archive applies. */
+    parseSpecDeltas(specName, plan) {
         const deltas = [];
-        const sections = this.parseSectionsFromContent(content);
-        // Parse ADDED requirements
-        const addedSection = this.findSection(sections, 'ADDED Requirements');
-        if (addedSection) {
-            const requirements = this.parseRequirements(addedSection);
-            requirements.forEach(req => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'ADDED',
-                    description: `Add requirement: ${req.text}`,
-                    // Provide both single and plural forms for compatibility
-                    requirement: req,
-                    requirements: [req],
-                });
+        // Single and plural requirement fields are both filled for compatibility.
+        this.toRequirements(plan.added).forEach(req => {
+            deltas.push({
+                spec: specName,
+                operation: 'ADDED',
+                description: `Add requirement: ${req.text}`,
+                requirement: req,
+                requirements: [req],
             });
-        }
-        // Parse MODIFIED requirements
-        const modifiedSection = this.findSection(sections, 'MODIFIED Requirements');
-        if (modifiedSection) {
-            const requirements = this.parseRequirements(modifiedSection);
-            requirements.forEach(req => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'MODIFIED',
-                    description: `Modify requirement: ${req.text}`,
-                    requirement: req,
-                    requirements: [req],
-                });
+        });
+        this.toRequirements(plan.modified).forEach(req => {
+            deltas.push({
+                spec: specName,
+                operation: 'MODIFIED',
+                description: `Modify requirement: ${req.text}`,
+                requirement: req,
+                requirements: [req],
             });
-        }
-        // Parse REMOVED requirements
-        const removedSection = this.findSection(sections, 'REMOVED Requirements');
-        if (removedSection) {
-            const requirements = this.parseRequirements(removedSection);
-            requirements.forEach(req => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'REMOVED',
-                    description: `Remove requirement: ${req.text}`,
-                    requirement: req,
-                    requirements: [req],
-                });
+        });
+        // A bullet-form REMOVED entry carries only a name, read here as a
+        // header-form removal with no body.
+        const removedBlocks = [...plan.removedBlocks];
+        const removed = plan.removed.map((name) => {
+            const index = removedBlocks.findIndex((block) => block.name === name);
+            return index === -1 ? removedNameBlock(name) : removedBlocks.splice(index, 1)[0];
+        });
+        this.toRequirements(removed).forEach(req => {
+            deltas.push({
+                spec: specName,
+                operation: 'REMOVED',
+                description: `Remove requirement: ${req.text}`,
+                requirement: req,
+                requirements: [req],
             });
-        }
-        // Parse RENAMED requirements
-        const renamedSection = this.findSection(sections, 'RENAMED Requirements');
-        if (renamedSection) {
-            const renames = this.parseRenames(renamedSection.content);
-            renames.forEach(rename => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'RENAMED',
-                    description: `Rename requirement from "${rename.from}" to "${rename.to}"`,
-                    rename,
-                });
+        });
+        plan.renamed.forEach(rename => {
+            deltas.push({
+                spec: specName,
+                operation: 'RENAMED',
+                description: `Rename requirement from "${rename.from}" to "${rename.to}"`,
+                rename,
             });
-        }
+        });
         return deltas;
     }
-    parseRenames(content) {
-        const renames = [];
-        const lines = ChangeParser.normalizeContent(content).split('\n');
-        let currentRename = {};
-        for (const line of lines) {
-            const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
-            const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
-            if (fromMatch) {
-                currentRename.from = fromMatch[1].trim();
-            }
-            else if (toMatch) {
-                currentRename.to = toMatch[1].trim();
-                if (currentRename.from && currentRename.to) {
-                    renames.push({
-                        from: currentRename.from,
-                        to: currentRename.to,
-                    });
-                    currentRename = {};
-                }
-            }
-        }
-        return renames;
+    /** One Requirement per block, via the same section parser and header filter as before. */
+    toRequirements(blocks) {
+        return blocks.flatMap((block) => {
+            const [headerLine, ...body] = block.raw.split('\n');
+            // The delta reader also accepts `###Requirement:` with no space, which
+            // the section parser below would not see as a header.
+            const title = headerLine.replace(/^###\s*/, '').trim();
+            const [section] = this.parseSectionsFromContent([`### ${title}`, ...body].join('\n'));
+            return this.parseRequirements({ level: 2, title: '', content: '', children: [section] });
+        });
     }
     parseSectionsFromContent(content) {
         const normalizedContent = ChangeParser.normalizeContent(content);

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/markdown-parser.js

@@ -1,10 +1,4 @@
-import { buildCodeFenceMask, extractRequirementText } from './requirement-text.js';
-/**
- * EARS scenario title: `Scenario: WHEN <event> THE SYSTEM SHALL <behavior>`
- * (also WHILE/WHERE/IF ... SHALL). Case-insensitive; the title is the text
- * after `#### ` so it still starts with `Scenario:`.
- */
-const EARS_SCENARIO_TITLE = /^Scenario:\s*(?:WHEN|WHILE|WHERE|IF)\b[\s\S]*\b(?:SHALL|MUST)\b/i;
+import { buildCodeFenceMask, extractRequirementText, hasScenarioBody, EARS_SCENARIO_TITLE } from './requirement-text.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -136,8 +130,9 @@ export class MarkdownParser {
     parseScenarios(requirementSection) {
         const scenarios = [];
         for (const scenarioSection of requirementSection.children) {
-            // Store the raw text content of the scenario section
-            if (scenarioSection.content.trim()) {
+            // Store the raw text content of the scenario section. A header with no
+            // body is not a scenario; the delta counter applies the same rule.
+            if (hasScenarioBody(scenarioSection.content)) {
                 scenarios.push({
                     rawText: scenarioSection.content
                 });