freeharness 0.4.1 → 0.4.3

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/spec-discovery.js

@@ -1,6 +1,8 @@
 import { promises as fs } from 'fs';
+import * as fssync from 'fs';
 import path from 'path';
 import { FileSystemUtils } from '../engine/file-system.js';
+import { parseDeltaSpec } from './parsers/requirement-blocks.js';
 function assertDiscoveredSpecPath(specsRoot, capabilityDir, specFile) {
     try {
         FileSystemUtils.assertPathWithin(specsRoot, specFile);
@@ -112,3 +114,116 @@ export async function hasAnyFileUnder(dirPath) {
     }
     return false;
 }
+/** Async driver of walkUnreadDeltaFiles. */
+export async function findUnreadDeltaFiles(specsRoot) {
+    const walker = walkUnreadDeltaFiles(specsRoot);
+    let step = walker.next();
+    while (!step.done) {
+        const request = step.value;
+        let reply;
+        try {
+            switch (request.op) {
+                case 'readdir':
+                    reply = await fs.readdir(request.path, { withFileTypes: true });
+                    break;
+                case 'stat':
+                    reply = await fs.stat(request.path);
+                    break;
+                case 'read':
+                    reply = await fs.readFile(request.path, 'utf-8');
+                    break;
+            }
+        }
+        catch (err) {
+            step = walker.throw(err);
+            continue;
+        }
+        step = walker.next(reply);
+    }
+    return step.value;
+}
+/** Sync driver of walkUnreadDeltaFiles, for the instructions shim. */
+export function findUnreadDeltaFilesSync(specsRoot) {
+    const walker = walkUnreadDeltaFiles(specsRoot);
+    let step = walker.next();
+    while (!step.done) {
+        const request = step.value;
+        let reply;
+        try {
+            switch (request.op) {
+                case 'readdir':
+                    reply = fssync.readdirSync(request.path, { withFileTypes: true });
+                    break;
+                case 'stat':
+                    reply = fssync.statSync(request.path);
+                    break;
+                case 'read':
+                    reply = fssync.readFileSync(request.path, 'utf-8');
+                    break;
+            }
+        }
+        catch (err) {
+            step = walker.throw(err);
+            continue;
+        }
+        step = walker.next(reply);
+    }
+    return step.value;
+}
+/**
+ * Markdown files under a change's specs/ with delta sections that are not a
+ * capability's `spec.md` (`specs/user-auth.md`, or `specs/user-auth/delta.md`
+ * beside or instead of its spec.md). discoverSpecFiles, and so validate and
+ * archive, never reads them, while the artifact graph's specs/ markdown glob
+ * does: status and apply report the specs as written and archive has nothing
+ * to merge. A root `spec.md` has its own check; a note without delta sections
+ * is not reported. Like discoverSpecFiles, the walk skips dot entries and
+ * dangling links and never follows a symlinked directory. A missing root
+ * yields []; other read failures throw. Sorted by path. Filesystem calls are
+ * yielded to the async and sync drivers.
+ */
+function* walkUnreadDeltaFiles(specsRoot) {
+    const results = [];
+    function* walk(dir, segments) {
+        let entries;
+        try {
+            entries = (yield { op: 'readdir', path: dir });
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                yield* walk(path.join(dir, entry.name), [...segments, entry.name]);
+                continue;
+            }
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            if (entry.name === 'spec.md' || !entry.name.toLowerCase().endsWith('.md'))
+                continue;
+            const filePath = path.join(dir, entry.name);
+            let content;
+            try {
+                if (entry.isSymbolicLink() && !(yield { op: 'stat', path: filePath }).isFile())
+                    continue;
+                content = (yield { op: 'read', path: filePath });
+            }
+            catch (err) {
+                if (err?.code === 'ENOENT')
+                    continue;
+                throw err;
+            }
+            if (!Object.values(parseDeltaSpec(content).sectionPresence).some(Boolean))
+                continue;
+            const capability = segments.length > 0 ? segments.join('/') : entry.name.slice(0, -'.md'.length);
+            results.push({ path: [...segments, entry.name].join('/'), expected: `${capability}/spec.md` });
+        }
+    }
+    yield* walk(specsRoot, []);
+    return results.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/task-lines.d.ts

@@ -1,5 +1,5 @@
 export interface ParsedTask {
-    /** Checkbox state: `[x]`/`[X]` is done, anything else is not. */
+    /** Checkbox state: `[x]`/`[X]` is done, every other marker (and none) is not. */
     done: boolean;
     /** Task text after the checkbox, trimmed (may be empty). */
     description: string;
@@ -17,8 +17,8 @@ export type TaskAnnotationKey = (typeof TASK_ANNOTATION_KEYS)[number];
  * A task resolved outside this change: `superseded`/`moved` name another
  * change id, `external` carries free-form reference text. `kind` is the raw
  * first token of the `Disposition:` value, so a value outside the three
- * documented kinds still parses (a reader such as `validate --strict` reports
- * it, rather than the parser silently dropping the line).
+ * documented kinds still parses and `validate --strict` can report it instead
+ * of the line vanishing.
  */
 export interface TaskDisposition {
     kind: string;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/task-lines.js

@@ -4,16 +4,20 @@
 // the single dependency `task-numbering.ts` has on task-progress. The rest of
 // task-progress (schema/artifact-graph-driven task-file resolution, progress
 // counting, unreadable-file tracking) is out of the change-validation slice and
-// is deliberately NOT vendored. The regex and semantics below are faithful to
-// upstream so task-numbering behaves identically.
+// is deliberately NOT vendored. The semantics below are faithful to upstream so
+// task-numbering behaves identically.
 /**
- * A Markdown task line: a `-`/`*` bullet carrying a `[ ]` or `[x]` checkbox.
- *
- * Leading whitespace is allowed so nested sub-tasks count like their parents.
- * Deliberately unanchored at the end: `.` does not match `\r`, so writing the
- * description group as `(.*)$` would reject every line of a CRLF tasks.md.
+ * A Markdown task line: a checkbox list item under any CommonMark marker (`-`,
+ * `*`, `+`, or an ordered `1.`/`1)` of up to nine digits; #1862), nested or not.
+ * The box holds at most one non-bracket token (`[~]`, `[]`, `[ x]` all count,
+ * #1773); only `x`/`X` reads as done, so an unknown marker counts as open
+ * instead of vanishing. A `(` or `[` right after the box marks a link
+ * (`- [A](url)`), never a task, except after a whitespace-only box:
+ * `- [ ](...)` is open work. Unlike upstream, no two `\s*` runs flank an
+ * optional token, so matching stays linear. No end anchor: `.` does not match
+ * the `\r` of a CRLF file.
  */
-const TASK_LINE_PATTERN = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
+const TASK_LINE_PATTERN = /^\s*(?:[-*+]|\d{1,9}[.)])\s*\[(?:\s*([^\]\s])\s*\](?![([])|\](?![([])|\s+\])\s*(.*)/;
 /**
  * Parses every task line in a tasks file, in document order. Every line matching
  * the pattern counts, wherever it sits (inside a code fence, HTML comment, or an
@@ -24,18 +28,17 @@ export function parseTaskLines(content) {
     for (const line of content.split('\n')) {
         const match = line.match(TASK_LINE_PATTERN);
         if (match) {
-            tasks.push({ done: match[1].toLowerCase() === 'x', description: match[2].trim() });
+            tasks.push({ done: (match[1] ?? '').toLowerCase() === 'x', description: match[2].trim() });
         }
     }
     return tasks;
 }
 // ---------------------------------------------------------------------------
-// FreeHarness V4-P4 (4.5): per-task annotation lines. Not in upstream.
+// FreeHarness: per-task annotation lines. Not in upstream.
 //
-// The FreeHarness tasks template allows optional lines under a task that name
-// how to verify it, which interfaces it touches, its write boundary, its
-// dependencies and, when the task is resolved outside this change, its
-// disposition:
+// The FreeHarness tasks template allows optional lines under a task: its verify
+// command, interfaces, write boundary, dependencies and, when the task is
+// resolved outside this change, its disposition:
 //
 //   - [ ] 2.1 Implement the parser
 //     Verify: node --test test/parser.test.ts
@@ -44,10 +47,8 @@ export function parseTaskLines(content) {
 //     Depends: 1.2
 //     Disposition: moved other-change
 //
-// They carry no checkbox, so `parseTaskLines` above never counts them; this
-// section only makes the convention explicit (one place defines the keys) and
-// attaches the annotations to the task they follow for readers such as the
-// converge hook and the subagent-driven-development briefs.
+// They carry no checkbox, so `parseTaskLines` never counts them; this section
+// defines the keys once and attaches each annotation to the task it follows.
 // ---------------------------------------------------------------------------
 /** The annotation keys the tasks template documents. */
 export const TASK_ANNOTATION_KEYS = ['Verify', 'Interfaces', 'Boundary', 'Depends', 'Disposition'];
@@ -80,7 +81,7 @@ export function parseAnnotatedTaskLines(content) {
         const task = line.match(TASK_LINE_PATTERN);
         if (task) {
             current = {
-                done: task[1].toLowerCase() === 'x',
+                done: (task[1] ?? '').toLowerCase() === 'x',
                 description: task[2].trim(),
                 line: i + 1,
                 annotations: {},
@@ -98,7 +99,6 @@ export function parseAnnotatedTaskLines(content) {
                 current.disposition = parseDisposition(value);
             continue;
         }
-        // A blank line or any other prose ends the annotation run.
         current = undefined;
     }
     return tasks;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/validator.d.ts

@@ -90,5 +90,11 @@ export declare class Validator {
      */
     private buildMissingShallOrMustMessage;
     private countScenarios;
+    /**
+     * Why a requirement with a visible scenario header still has no scenario:
+     * the header has no body, and the spec path archive validates against does
+     * not count it. Empty when the block has no bare scenario header.
+     */
+    private emptyScenarioHint;
     private formatSectionList;
 }

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/validator.js

@@ -4,11 +4,11 @@ import { SpecSchema, ChangeSchema } from './schemas/index.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
 import { ChangeParser } from './parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from './parsers/requirement-blocks.js';
-import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from './parsers/requirement-text.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, } from './parsers/requirement-blocks.js';
+import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, } from './parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { FileSystemUtils } from '../engine/file-system.js';
-import { discoverSpecFiles } from './spec-discovery.js';
+import { discoverSpecFiles, findUnreadDeltaFiles } from './spec-discovery.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
 import { findPurposePlaceholderIssue } from './purpose-placeholder.js';
 import { findSpecUpdates, buildUpdatedSpec } from '../apply/specs-apply.js';
@@ -164,6 +164,38 @@ export class Validator {
                             : `Header "### ${stray.header}" in ${stray.section} is not a "### Requirement:" header and is ignored by validation. Use "### Requirement: ${stray.header}" if it should be validated as a requirement.`,
                     });
                 }
+                // A well-formed requirement outside every delta section, ignored by
+                // the reader. WARNING, not ERROR: a handful of pre-format archived
+                // changes still carry this shape, and the fix is to move the block.
+                for (const orphan of plan.orphanedRequirements) {
+                    const where = orphan.section ? `under "## ${orphan.section}"` : 'above the first "## " section';
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        line: orphan.line,
+                        message: `Requirement "${orphan.name}" is ${where}, which is not a delta section, so it is ignored. Move it under "## ADDED Requirements", "## MODIFIED Requirements", "## REMOVED Requirements", or "## RENAMED Requirements".`,
+                    });
+                }
+                // Archive carries requirement blocks only, by design. Warn so text
+                // written elsewhere is moved rather than lost without notice.
+                for (const lost of plan.unappliedContent) {
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        line: lost.line,
+                        message: `${describeUnappliedContent(lost, true)} is not carried into the main spec by archive. Move it into a requirement, or into proposal.md or design.md.`,
+                    });
+                }
+                // A `TO:` line that never formed a pair, reported here so the author
+                // learns at authoring time rather than at archive.
+                for (const unpaired of plan.unpairedRenames) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: entryPath,
+                        line: unpaired.line,
+                        message: `RENAMED TO: "${unpaired.name}" has no matching FROM: line. Write each rename as a FROM: line followed immediately by its TO: line.`,
+                    });
+                }
                 const sectionNames = [];
                 if (plan.sectionPresence.added)
                     sectionNames.push('## ADDED Requirements');
@@ -215,7 +247,11 @@ export class Validator {
                     }
                     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` });
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `ADDED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}`,
+                        });
                     }
                 }
                 // Validate MODIFIED
@@ -247,7 +283,11 @@ export class Validator {
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario` });
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `MODIFIED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}`,
+                        });
                     }
                 }
                 // Run archive's scenario-loss check here too, so the change fails at
@@ -349,6 +389,16 @@ export class Validator {
                 throw error;
             }
         }
+        // Same drop for delta sections in a file the merge path never reads
+        // (specs/<capability>.md), though the specs/**/*.md glob counts it written.
+        const unreadDeltaFiles = await findUnreadDeltaFiles(specsDir);
+        for (const file of unreadDeltaFiles) {
+            issues.push({
+                level: 'ERROR',
+                path: file.path,
+                message: `Delta spec found at specs/${file.path}. Delta specs must be a spec.md inside a capability folder — this file is ignored when the change is applied or archived. Move its requirements into specs/${file.expected}.`,
+            });
+        }
         for (const { path: specPath, sections } of emptySectionSpecs) {
             issues.push({
                 level: 'ERROR',
@@ -363,11 +413,11 @@ export class Validator {
                 message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
             });
         }
-        // The root-level error already names the file and the fix; adding "No
-        // deltas found" on top would contradict it, since the deltas are sitting in
-        // the file just reported. (skip_specs marker handling is intentionally not
-        // vendored in this slice — see the file header.)
-        if (totalDeltas === 0 && !hasRootLevelSpec) {
+        // The root-level and unread-file errors already name the file and the fix;
+        // adding "No deltas found" on top would contradict them, since the deltas
+        // are sitting in the files just reported. (skip_specs marker handling is
+        // intentionally not vendored in this slice — see the file header.)
+        if (totalDeltas === 0 && !hasRootLevelSpec && unreadDeltaFiles.length === 0) {
             issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
         }
         if (options.projectRoot) {
@@ -473,15 +523,16 @@ export class Validator {
             const current = currentBlockFor(key);
             if (!current)
                 continue;
-            const missing = findMissingCurrentScenarios(current, block);
-            if (missing.length === 0)
+            const diff = diffScenarioNames(current, block);
+            if (diff.missing.length === 0)
                 continue;
             issues.push({
                 level: 'ERROR',
                 path: entryPath,
                 message: `MODIFIED "${block.name}" omits scenario(s) the current spec still has: ` +
-                    `${missing.map(name => `"${name}"`).join(', ')}. ` +
-                    'Copy them into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
+                    `${diff.missing.map(name => `"${name}"`).join(', ')}. ` +
+                    `${describeScenarioBalance(diff)} ` +
+                    'Copy the omitted scenarios into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
             });
         }
         return issues;
@@ -744,6 +795,16 @@ export class Validator {
         // example is not a real scenario. Drop the header line (index 0).
         return countScenariosShared(blockRaw.split('\n').slice(1));
     }
+    /**
+     * Why a requirement with a visible scenario header still has no scenario:
+     * the header has no body, and the spec path archive validates against does
+     * not count it. Empty when the block has no bare scenario header.
+     */
+    emptyScenarioHint(blockRaw) {
+        if (countEmptyScenarios(blockRaw.split('\n').slice(1)) === 0)
+            return '';
+        return ' (a scenario header with no body under it does not count; add its steps, e.g. "- **WHEN** ..." and "- **THEN** ...")';
+    }
     formatSectionList(sections) {
         if (sections.length === 0)
             return '';

package/node_modules/@freeharness/sdd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freeharness/sdd",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": true,
   "type": "module",
   "description": "Vendored, store-free slice of OpenSpec (schema validation + project init) that runs with no global openspec on PATH.",

package/node_modules/@freeharness/sdd/vendor/openspec/assets/schema.upstream.yaml

@@ -13,7 +13,7 @@ artifacts:
       - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
       - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
       - **Capabilities**: Identify which specs will be created or modified:
-        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
         - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
       - **Impact**: Affected code, APIs, dependencies, or systems.
 
@@ -77,6 +77,17 @@ artifacts:
       - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
       - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
 
+      Write the spec files one at a time, so the user sees progress and an
+      interrupted run keeps the files it already wrote:
+      - Before writing anything, compare the capabilities the proposal lists
+        with the `specs/<capability-path>/spec.md` files that already exist,
+        and start with the first capability that has no file. Do not rewrite
+        an existing file unless the user asks you to.
+      - Before each file, say in one line which capability you are writing.
+      - Write each file as soon as you have drafted it. Do not plan every file
+        before writing the first.
+      - Stop when every capability the proposal lists has its file.
+
       There must be at least one spec file unless the change's `.openspec.yaml`
       sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
       rejects a zero-delta change without that marker. If the proposal lists no
@@ -94,8 +105,9 @@ artifacts:
       - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
+      - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
 
-      New capabilities only: start the delta spec with a `## Purpose` section -
+      New capabilities only: the delta spec's first section is `## Purpose` -
       one or two sentences (50+ characters, or `openspec validate --strict`
       reports it as too brief) describing what the capability is for. Archive
       copies it into the main spec it creates; without it the new main spec is
@@ -120,8 +132,10 @@ artifacts:
       Common pitfall: Using MODIFIED with partial content loses detail at archive time.
       If adding new concerns without changing existing behavior, use ADDED instead.
 
-      Example (a new capability, so it opens with `## Purpose`):
+      Example (a new capability, so its first section is `## Purpose`):
       ```
+      # Spec Delta
+
       ## Purpose
 
       Lets users take their data out of the product in a portable format.
@@ -192,22 +206,39 @@ artifacts:
       would change what gets built, resolve them with the user first - do not
       bake an unstated assumption into the task list.
 
-      **IMPORTANT: Follow the template below exactly.** The apply phase parses
-      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+      **IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses
+      checkbox format to track progress. A box holding only `x` counts as done,
+      upper or lower case and with any spacing, so `- [ x]` is done too. Every
+      other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
+      unfinished. A line with no checkbox is not tracked at all.
 
       Guidelines:
-      - Group related tasks under ## numbered headings
-      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Group related tracked tasks under ## numbered headings
+      - Each tracked task MUST be a checkbox: `- [ ] X.Y Task description`
       - Tasks should be small enough to complete in one session
       - Order tasks by dependency (what must be done first?)
+      - Track implementation and verification work that can be completed before
+        archive. If the requested workflow includes archive or work that requires
+        this change to be archived, preserve those steps as plain bullets in an
+        optional `## Workflow follow-up` section at the end of tasks.md. These
+        bullets are reference information outside tracked task progress.
       - Each task MUST state how to verify completion (a test, command,
         observable behavior, or delivered artifact). Put the verification in
         that task's checkbox description. Use a separate verification task only
         when it checks broader integration or system behavior that spans
         multiple implementation tasks.
+      - Each task group MUST land the tests and documentation its own work
+        calls for. Do NOT collect testing or documentation into a final group -
+        when a late group first exercises work from an early one, the failures
+        cascade back through every group in between and force rework. A group
+        whose work calls for neither, such as scaffolding or dependency setup,
+        carries neither. A final group is for integration checks only, not for
+        the tests and docs an earlier group owed.
 
       Example:
       ```
+      # Tasks
+
       ## 1. Setup
 
       - [ ] 1.1 Create new module structure and verify expected files are present
@@ -217,6 +248,15 @@ artifacts:
 
       - [ ] 2.1 Implement data export function and verify the export test passes
       - [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
+      - [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
+      ```
+
+      When applicable, append workflow follow-up as plain bullets, for example:
+      ```
+      ## Workflow follow-up
+
+      - Archive the change after the project's review requirements are satisfied.
+      - Verify the archived result.
       ```
 
       Reference specs for what needs to be built, design for how to build it.

package/node_modules/@freeharness/sdd/vendor/openspec/assets/skills/openspec-apply-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openspec-apply-change
-description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement".
 allowed-tools: Bash(openspec:*)
 license: MIT
 compatibility: Requires openspec CLI.
@@ -13,6 +13,17 @@ Implement tasks from an OpenSpec change.
 
 **Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
 
+**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
+
+One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
+
+Otherwise, with no root, what happens next depends on how this workflow was reached:
+
+- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
+- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
+
+In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
+
 **Input**: Optionally specify a change name (e.g., `/openspec-apply-change add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -44,14 +55,17 @@ Implement tasks from an OpenSpec change.
    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
+   - `missingArtifacts` (when present): required artifact ids with no output
 
    **Handle states:**
-   - If `state: "blocked"` (missing artifacts): show message, suggest using `/openspec-continue-change` (if it is not installed, run `openspec status --change "<name>" --json` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json` for how to create it)
-   - If `state: "all_done"`: congratulate, suggest archive
+   - If `state: "blocked"`: show the message and pause implementation.
+     - If `missingArtifacts` is non-empty: suggest using `/openspec-continue-change` to create them.
+     - 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"`: 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
@@ -93,7 +107,9 @@ Implement tasks from an OpenSpec change.
    - 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:**
@@ -108,7 +124,7 @@ Implement tasks from an OpenSpec change.
    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**
@@ -139,7 +155,8 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! You can archive this change with `/openspec-archive-change`.
+All tracked tasks are complete. Review or verify the change as appropriate
+before archiving. You can archive this change with `/openspec-archive-change`.
 ```
 
 **Output On Pause (Issue Encountered)**
@@ -173,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