freeharness 0.4.1 → 0.4.2

package/node_modules/@freeharness/sdd/dist/vendor/openspec/apply/specs-apply.js

@@ -7,13 +7,14 @@
 import { promises as fs } from 'fs';
 import { randomUUID } from 'crypto';
 import path from 'path';
-import { extractRequirementsSection, findMissingCurrentScenarios, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from '../validation/parsers/requirement-blocks.js';
+import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from '../validation/parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from '../validation/parsers/spec-structure.js';
 import { buildCodeFenceMask } from '../validation/parsers/code-fence.js';
 import { MarkdownParser } from '../validation/parsers/markdown-parser.js';
 import { MIN_PURPOSE_LENGTH, PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX, } from '../validation/constants.js';
 import { discoverSpecFiles } from '../validation/spec-discovery.js';
 import { FileSystemUtils } from '../engine/file-system.js';
+import { matchLineEnding } from './line-endings.js';
 function isLexicallyWithin(allowedDirectory, targetPath) {
     const relative = path.relative(path.resolve(allowedDirectory), path.resolve(targetPath));
     return (relative === '' ||
@@ -21,7 +22,7 @@ function isLexicallyWithin(allowedDirectory, targetPath) {
             !relative.startsWith(`..${path.sep}`) &&
             !path.isAbsolute(relative)));
 }
-function resolveTrustedSpecPath(specsRoot, specPath) {
+function resolveTrustedSpecPath(specsRoot, specPath, projectRoot) {
     if (!isLexicallyWithin(specsRoot, specPath)) {
         throw new Error(`Path is outside the allowed directory: ${specPath}`);
     }
@@ -41,6 +42,12 @@ function resolveTrustedSpecPath(specsRoot, specPath) {
         // Freeze their canonical location as the trust root so later swaps are
         // rejected while a nested spec.md link still cannot escape.
         const root = FileSystemUtils.canonicalizeExistingPath(path.dirname(specPath));
+        // An external capability link is supported; name the real write target
+        // instead of silently writing outside the project while reporting the
+        // in-project path.
+        if (projectRoot && !isLexicallyWithin(FileSystemUtils.canonicalizeExistingPath(projectRoot), root)) {
+            process.emitWarning(`Capability '${path.basename(path.dirname(specPath))}' links outside the project; writing to ${root}`, 'OpenSpecExternalSpecWrite');
+        }
         const file = path.join(root, path.basename(specPath));
         FileSystemUtils.assertPathWithin(root, file);
         return { root, file };
@@ -68,7 +75,8 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
     for (const { id, specFile } of discovered) {
         const targetFile = path.join(mainSpecsDir, ...id.split('/'), 'spec.md');
         const source = resolveTrustedSpecPath(changeSpecsDir, specFile);
-        const target = resolveTrustedSpecPath(mainSpecsDir, targetFile);
+        // mainSpecsDir is always <project root>/openspec/specs.
+        const target = resolveTrustedSpecPath(mainSpecsDir, targetFile, path.dirname(path.dirname(mainSpecsDir)));
         // Check if target exists
         let exists = false;
         try {
@@ -110,6 +118,27 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // Parse deltas from the change spec file
     const plan = parseDeltaSpec(changeContent);
     const specName = update.id;
+    // Without this refusal a TO: with no pending FROM: pairs with whichever
+    // FROM: comes next, renaming a requirement the author never named. Refuse
+    // rather than guess. (A FROM: without its TO: stays the FreeHarness
+    // advisory note reported by validate; not blocking here.)
+    if (plan.unpairedRenames.length > 0) {
+        const first = plan.unpairedRenames[0];
+        throw new Error(`${specName} validation failed - RENAMED entry on line ${first.line} has no matching FROM: for header "### Requirement: ${first.name}". ` +
+            `Write each rename as a FROM: line followed immediately by its TO: line.`);
+    }
+    // A well-formed requirement outside every delta section is not applied.
+    // Say so here too: archive is the last point the author can still notice.
+    for (const orphan of plan.orphanedRequirements) {
+        const where = orphan.section ? `under "## ${orphan.section}"` : 'above the first "## " section';
+        warn(`${specName} - requirement "${orphan.name}" (line ${orphan.line}) is ${where}, ` +
+            `which is not a delta section, so it was not applied. ` +
+            `Move it under ADDED/MODIFIED/REMOVED/RENAMED Requirements.`);
+    }
+    // Archive carries requirement blocks only; name any other text it leaves behind.
+    for (const lost of plan.unappliedContent) {
+        warn(`${specName} - ${describeUnappliedContent(lost)} (line ${lost.line}) is not carried into the main spec.`);
+    }
     // Pre-validate duplicates within sections
     const addedNames = new Set();
     for (const add of plan.added) {
@@ -165,12 +194,11 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     for (const { from, to } of plan.renamed) {
         const fromNorm = normalizeRequirementName(from);
         const toNorm = normalizeRequirementName(to);
-        // A REMOVED naming the FROM side contradicts the rename. This used to
-        // fail incidentally at apply time (the rename consumed the old header,
-        // so REMOVED hit "not found"); now that a missing REMOVED target is a
-        // no-op, the conflict must be rejected explicitly. Compared folded, so
-        // a case/whitespace variant cannot slip past the guard and degrade
-        // into a warned no-op.
+        // A REMOVED naming the FROM side contradicts the rename. A missing
+        // REMOVED target is a no-op, so without this explicit rejection the
+        // rename consumes the old header and the REMOVED silently does nothing.
+        // Compared folded, so a case/whitespace variant cannot slip past the
+        // guard and degrade into a warned no-op.
         const removedFoldMatch = [...removedNamesSet].find((r) => foldRequirementName(r) === foldRequirementName(fromNorm));
         if (removedFoldMatch !== undefined) {
             throw new Error(`${specName} validation failed - requirement present in multiple sections (RENAMED and REMOVED) for header "### Requirement: ${from}"` +
@@ -293,6 +321,13 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (nameToBlock.has(to)) {
             throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`);
         }
+        // A target differing from another requirement only in case/whitespace
+        // would leave two copies; the source itself is exempt so a case-only
+        // rename stays allowed.
+        const targetNearMiss = [...nameToBlock.keys()].find((k) => k !== from && foldRequirementName(k) === foldRequirementName(to));
+        if (targetNearMiss !== undefined) {
+            throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - "### Requirement: ${nameToBlock.get(targetNearMiss).name}" already exists and differs only in case or spacing; choose a distinct name`);
+        }
         const block = nameToBlock.get(from);
         const newHeader = `### Requirement: ${to}`;
         const rawLines = block.raw.split('\n');
@@ -352,9 +387,9 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }
-        const missingScenarios = findMissingCurrentScenarios(currentBlock, mod);
-        if (missingScenarios.length > 0) {
-            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${missingScenarios.map(name => `"${name}"`).join(', ')}. Refresh the change spec before archiving to avoid dropping scenarios.`);
+        const scenarioDiff = diffScenarioNames(currentBlock, mod);
+        if (scenarioDiff.missing.length > 0) {
+            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${scenarioDiff.missing.map(name => `"${name}"`).join(', ')}. ${describeScenarioBalance(scenarioDiff)} Refresh the change spec before archiving to avoid dropping scenarios.`);
         }
         // Identical content means the modification was already synced to the
         // baseline (early-sync pattern) — count only real replacements, so a
@@ -379,6 +414,14 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             }
             throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`);
         }
+        // A name differing from an existing requirement only in case/whitespace is
+        // that requirement written again. Compared against the spec as it stands
+        // after the earlier operations, so a variant this delta removed or
+        // renamed away is fine.
+        const nearMiss = [...nameToBlock.keys()].find((k) => foldRequirementName(k) === foldRequirementName(key));
+        if (nearMiss !== undefined) {
+            throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - "### Requirement: ${nameToBlock.get(nearMiss).name}" already exists and differs only in case or spacing; use MODIFIED with that exact header to change it, or choose a distinct name`);
+        }
         nameToBlock.set(key, add);
         addedApplied++;
     }
@@ -865,11 +908,20 @@ export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
     // Create target directory if needed
     const targetDir = path.dirname(update.target);
     await fs.mkdir(targetDir, { recursive: true });
+    // `rebuilt` is always LF; match the target's own convention on write, or a
+    // CRLF checkout sees the whole spec change. Only ENOENT means "no file to
+    // match"; any other read error propagates rather than reading as absent.
+    const previous = await fs.readFile(update.target, 'utf-8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    const toWrite = previous === undefined ? rebuilt : matchLineEnding(rebuilt, previous);
     await options.beforeMutate?.();
     // Preserve the established in-place write semantics: symlink referents,
     // hard-linked specs, ACLs, extended attributes, and filesystems without hard
     // links must continue to behave as they did before capability retirement.
-    await fs.writeFile(update.target, rebuilt);
+    await fs.writeFile(update.target, toWrite);
     if (options.silent)
         return;
     const specName = update.id;
@@ -886,15 +938,36 @@ export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
 /** Blank out `<!-- ... -->` spans, preserving line count so indices stay aligned. */
 function maskHtmlComments(content) {
     const blank = (text) => text.replace(/[^\n]/g, ' ');
-    // `--!>` is a comment terminator as well as `-->`.
-    const masked = content.replace(/<!--[\s\S]*?--!?>/g, blank);
-    // A comment that is never closed runs to end of file, so everything after it
-    // is commented out too. Without this an unterminated `<!--` above a
-    // `## Purpose` left the commented-out header looking real (#1413).
-    const unterminated = masked.indexOf('<!--');
-    if (unterminated === -1)
-        return masked;
-    return masked.slice(0, unterminated) + blank(masked.slice(unterminated));
+    // Linear scan: every character is visited once. A `/<!--[\s\S]*?--!?>/g`
+    // replace re-scans to end of file from every `<!--`, which is quadratic on a
+    // spec dense in comment openers.
+    let out = '';
+    let index = 0;
+    for (;;) {
+        const open = content.indexOf('<!--', index);
+        if (open === -1)
+            return out + content.slice(index);
+        out += content.slice(index, open);
+        // `--!>` is a comment terminator as well as `-->`.
+        let close = -1;
+        for (let i = open + 4; i < content.length; i++) {
+            if (content.startsWith('-->', i)) {
+                close = i + 3;
+                break;
+            }
+            if (content.startsWith('--!>', i)) {
+                close = i + 4;
+                break;
+            }
+        }
+        // A comment that is never closed runs to end of file, so everything after
+        // it is commented out too. Without this an unterminated `<!--` above a
+        // `## Purpose` left the commented-out header looking real (#1413).
+        if (close === -1)
+            return out + blank(content.slice(open));
+        out += blank(content.slice(open, close));
+        index = close;
+    }
 }
 /**
  * Read the body of a `## Purpose` section, ignoring markdown that only appears

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/change-status-policy.d.ts

@@ -23,4 +23,10 @@ export interface ActionContextInput {
     artifactIds: string[];
 }
 export declare function buildActionContext(input: ActionContextInput): ActionContext;
+/** One next action, in both forms, so text and JSON name the same step. */
+export interface ChangeNextStep {
+    command: string;
+    sentence: string;
+}
+export declare function resolveNextStep(input: ChangeNextStepsInput): ChangeNextStep | undefined;
 export declare function buildNextSteps(input: ChangeNextStepsInput): string[];

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/change-status-policy.js

@@ -19,14 +19,22 @@ export function buildActionContext(input) {
         ],
     };
 }
-export function buildNextSteps(input) {
+export function resolveNextStep(input) {
     const readyArtifact = input.artifactStatuses.find((artifact) => artifact.status === 'ready');
-    const steps = [];
     if (readyArtifact) {
-        steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}" --json before writing that artifact.`);
+        const command = `openspec instructions ${readyArtifact.id} --change "${input.changeName}" --json`;
+        return { command, sentence: `Run ${command} before writing that artifact.` };
     }
-    else if (input.allArtifactsComplete) {
-        steps.push(`All planning artifacts are complete. Run openspec instructions apply --change "${input.changeName}" --json to inspect implementation progress.`);
+    if (input.allArtifactsComplete) {
+        const command = `openspec instructions apply --change "${input.changeName}" --json`;
+        return {
+            command,
+            sentence: `All planning artifacts are complete. Run ${command} to inspect implementation progress.`,
+        };
     }
-    return steps;
+    return undefined;
+}
+export function buildNextSteps(input) {
+    const step = resolveNextStep(input);
+    return step ? [step.sentence] : [];
 }

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/index.d.ts

@@ -8,4 +8,4 @@ export { artifactOutputExists, isGlobPattern, resolveArtifactOutputPath, resolve
 export { readChangeMetadata, resolveSchemaForChange, writeChangeMetadata, ChangeMetadataSchema, ChangeMetadataError, METADATA_FILENAME, type ChangeMetadata, } from './change-metadata.js';
 export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, SKIP_SPECS_INSTRUCTIONS_WARNING, type ChangeContext, type LoadChangeContextOptions, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, type ArtifactPathSummary, } from './instruction-loader.js';
 export { getTaskProgressForChange, parseTaskLines, countTasksFromContent, formatTaskStatus, type TaskProgress, type ParsedTask, } from './task-progress.js';
-export { buildActionContext, buildNextSteps, type ActionContext, } from './change-status-policy.js';
+export { buildActionContext, buildNextSteps, resolveNextStep, type ActionContext, type ChangeNextStep, } from './change-status-policy.js';

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/index.js

@@ -18,4 +18,4 @@ export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStat
 // Task progress (list)
 export { getTaskProgressForChange, parseTaskLines, countTasksFromContent, formatTaskStatus, } from './task-progress.js';
 // Change-status policy
-export { buildActionContext, buildNextSteps, } from './change-status-policy.js';
+export { buildActionContext, buildNextSteps, resolveNextStep, } from './change-status-policy.js';

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/outputs.d.ts

@@ -1,6 +1,6 @@
-/**
- * Checks if a path contains glob pattern characters.
- */
+/** True when a `{...}` group has a comma (alternation) or `..` (range): `{api,ui}` is a glob, `{draft}` alone is literal. */
+export declare function hasBraceExpansion(pattern: string): boolean;
+/** Checks if a path is a glob: wildcards, a brace expansion, or an extglob (`@(...)`, `!(...)`, ...). */
 export declare function isGlobPattern(pattern: string): boolean;
 /**
  * Resolves an artifact's `generates` value to an absolute path under the change

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/outputs.js

@@ -13,11 +13,31 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { FileSystemUtils } from './file-system.js';
-/**
- * Checks if a path contains glob pattern characters.
- */
+const EXTGLOB_RE = /[!*+?@]\([^(]*\)/u;
+const BRACE_EXPANSION_SEPARATORS_RE = /,|\.\./u;
+/** True when a `{...}` group has a comma (alternation) or `..` (range): `{api,ui}` is a glob, `{draft}` alone is literal. */
+export function hasBraceExpansion(pattern) {
+    const openings = [];
+    for (let index = 0; index < pattern.length; index += 1) {
+        if (pattern[index] === '{')
+            openings.push(index);
+        if (pattern[index] !== '}')
+            continue;
+        const opening = openings.pop();
+        if (opening !== undefined && BRACE_EXPANSION_SEPARATORS_RE.test(pattern.slice(opening, index))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Checks if a path is a glob: wildcards, a brace expansion, or an extglob (`@(...)`, `!(...)`, ...). */
 export function isGlobPattern(pattern) {
-    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+    const normalized = FileSystemUtils.toPosixPath(pattern);
+    return (normalized.includes('*') ||
+        normalized.includes('?') ||
+        normalized.includes('[') ||
+        EXTGLOB_RE.test(normalized) ||
+        hasBraceExpansion(normalized));
 }
 /**
  * Resolves an artifact's `generates` value to an absolute path under the change

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/task-progress.js

@@ -11,17 +11,14 @@ import * as path from 'node:path';
 import { resolveSchema } from './resolver.js';
 import { resolveArtifactOutputs } from './outputs.js';
 import { resolveSchemaForChange } from './change-metadata.js';
-/**
- * A Markdown task line: a `-`/`*` bullet carrying a `[ ]` or `[x]` checkbox.
- * Leading whitespace is allowed so nested sub-tasks count like their parents.
- */
-const TASK_LINE_PATTERN = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
+/** The task-line pattern of validation/task-lines.ts, which documents it; keep the two identical. */
+const TASK_LINE_PATTERN = /^\s*(?:[-*+]|\d{1,9}[.)])\s*\[(?:\s*([^\]\s])\s*\](?![([])|\](?![([])|\s+\])\s*(.*)/;
 export function parseTaskLines(content) {
     const tasks = [];
     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;
@@ -49,7 +46,7 @@ function parseTasksWithDisposition(content) {
     for (const line of content.split('\n')) {
         const task = line.match(TASK_LINE_PATTERN);
         if (task) {
-            current = { done: task[1].toLowerCase() === 'x', description: task[2].trim(), dispositioned: false };
+            current = { done: (task[1] ?? '').toLowerCase() === 'x', description: task[2].trim(), dispositioned: false };
             tasks.push(current);
             continue;
         }

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/types.js

@@ -3,6 +3,7 @@
 // No behavioural changes. Part of the schema-validation slice.
 import * as path from 'node:path';
 import { z } from 'zod';
+import { hasBraceExpansion } from './outputs.js';
 function relativePathSchema(fieldName) {
     return z
         .string()
@@ -21,13 +22,24 @@ function relativePathSchema(fieldName) {
     });
 }
 // Artifact definition schema
-export const ArtifactSchema = z.object({
+export const ArtifactSchema = z
+    .object({
     id: z.string().min(1, { error: 'Artifact ID is required' }),
     generates: relativePathSchema('generates field'),
     description: z.string(),
     template: relativePathSchema('template field'),
     instruction: z.string().optional(),
     requires: z.array(z.string()).default([]),
+})
+    // Refined at the object level so the message can name the artifact id.
+    .superRefine((artifact, ctx) => {
+    if (hasBraceExpansion(artifact.generates)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['generates'],
+            message: `artifact "${artifact.id}" generates pattern "${artifact.generates}": brace expansion is not supported (the matcher would never match it)`,
+        });
+    }
 });
 // Apply phase configuration for schema-aware apply instructions
 export const ApplyPhaseSchema = z.object({

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

@@ -1,4 +1,11 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROJECT_ROOT_GUARD } from './project-root.js';
+/**
+ * `continue` is not among FreeHarness's six emitted workflows, so the
+ * blocked-state handoff below always renders the CLI fallback rather than
+ * naming a skill that was never generated.
+ */
+const BLOCKED_STATE_HANDOFF = 'run `openspec status --change "<name>" --json`, select the next `ready` artifact (not `skipped` or `blocked`), and use `openspec instructions "<artifact-id>" --change "<name>" --json` for its rules and template. Keep the selected `--store <id>` on both commands.';
 /**
  * The apply workflow instructions, authored once and rendered by both the
  * skill and command surfaces. The surfaces are intentionally distinct, but
@@ -13,6 +20,8 @@ export function getApplyInstructions() {
 
 ${STORE_SELECTION_GUIDANCE}
 
+${PROJECT_ROOT_GUARD}
+
 **Input**: Optionally specify a change name (e.g., \`/opsx:apply 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 +53,17 @@ ${STORE_SELECTION_GUIDANCE}
    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 \`/opsx:continue\` (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: ${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"\`: 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 +105,9 @@ ${STORE_SELECTION_GUIDANCE}
    - 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 +122,7 @@ ${STORE_SELECTION_GUIDANCE}
    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 +153,7 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! You can archive this change with \`/opsx:archive\`.
+All tracked tasks are complete. Review or verify the change as appropriate before archiving. You can archive this change with \`/opsx:archive\`.
 \`\`\`
 
 **Output On Pause (Issue Encountered)**
@@ -173,6 +187,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