@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/commands/workflow/instructions.js

@@ -7,31 +7,89 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, formatChangeStatus, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputPath, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
-import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, isStoreSelectedRoot, } from '../../core/root-selection.js';
+import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
 import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedStoresSection, } from '../../core/references.js';
 import { readRegistrySnapshot } from '../../core/store/registry.js';
-import { readProjectConfig } from '../../core/project-config.js';
-import { checkComprehensionGate, ComprehensionPassError, computeSpecStats, recordComprehensionPass, resolveComprehensionConfig, } from '../../core/comprehension/index.js';
-import { maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, incrementComprehensionAttempt, incrementComprehensionFailureCount, trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, } from '../../telemetry/index.js';
-import { normalizeEditor, resolveWorkflowInputAsync, } from '../../telemetry/input.js';
+import { loadOperationInputs, readProjectConfig, } from '../../core/project-config.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
-function buildArtifactPresence(contextFiles, pendingTaskCount) {
-    return {
-        hasPlan: (contextFiles.plan?.length ?? 0) > 0,
-        hasProposal: (contextFiles.proposal?.length ?? 0) > 0,
-        hasDesign: (contextFiles.design?.length ?? 0) > 0,
-        hasSpecs: (contextFiles.specs?.length ?? 0) > 0,
-        hasTasks: pendingTaskCount > 0 || (contextFiles.tasks?.length ?? 0) > 0,
+import { parseTaskLines } from '../../utils/task-progress.js';
+import { fingerprintArtifacts, isPassRecordValid } from '../../comprehension-quiz/fingerprint.js';
+// -----------------------------------------------------------------------------
+// Comprehension Quiz Check
+// -----------------------------------------------------------------------------
+/**
+ * Check comprehension quiz status for a change
+ * @param changeName - Name of the change
+ * @param changeDir - Directory of the change
+ * @param contextFiles - Context files mapping
+ * @returns Comprehension status object
+ */
+async function checkComprehensionStatus(changeName, changeDir, contextFiles) {
+    // Get all artifact file paths
+    const artifactPaths = [];
+    for (const files of Object.values(contextFiles)) {
+        artifactPaths.push(...files);
+    }
+    // Generate current fingerprint
+    const currentFingerprint = await fingerprintArtifacts(artifactPaths);
+    // Check if pass record is valid
+    const passValid = await isPassRecordValid(changeName, currentFingerprint);
+    // Calculate question allocation based on spec-driven schema defaults
+    const totalSize = artifactPaths.reduce((sum, filePath) => {
+        try {
+            return sum + fs.statSync(filePath).size;
+        }
+        catch {
+            return sum;
+        }
+    }, 0);
+    const questionCount = totalSize < 2048 ? 5 : totalSize < 10240 ? 7 : 10;
+    const questionAllocation = {
+        plan: Math.round(questionCount * 0.5),
+        specs: Math.round(questionCount * 0.2),
+        design: Math.round(questionCount * 0.1),
+        proposal: Math.round(questionCount * 0.1),
+        tasks: Math.round(questionCount * 0.1),
     };
-}
-function resolvePlanPath(contextFiles, changeDir) {
-    if (contextFiles.plan?.[0]) {
-        return contextFiles.plan[0];
+    // Count requirements and scenarios from specs
+    const specFiles = contextFiles.specs || [];
+    let requirementCount = 0;
+    let scenarioCount = 0;
+    for (const specFile of specFiles) {
+        try {
+            const content = await fs.promises.readFile(specFile, 'utf-8');
+            requirementCount += (content.match(/### Requirement:/g) || []).length;
+            scenarioCount += (content.match(/#### Scenario:/g) || []).length;
+        }
+        catch {
+            // Skip files that can't be read
+        }
+    }
+    // Count pending tasks
+    const tasksFile = contextFiles.tasks?.[0];
+    let pendingTaskCount = 0;
+    if (tasksFile) {
+        try {
+            const content = await fs.promises.readFile(tasksFile, 'utf-8');
+            pendingTaskCount = (content.match(/- \[ \]/g) || []).length;
+        }
+        catch {
+            // Skip if can't read
+        }
     }
-    const fallback = path.join(changeDir, 'plan.md');
-    return fs.existsSync(fallback) ? fallback : null;
+    return {
+        required: true,
+        passed: passValid,
+        thresholdPercent: 80,
+        questionCount,
+        questionAllocation,
+        optionsPerQuestion: 3,
+        requirementCount,
+        scenarioCount,
+        pendingTaskCount,
+    };
 }
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
@@ -74,10 +132,12 @@ export async function instructionsCommand(artifactId, options) {
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
+        const { projectConfig, references } = await loadRootConfigContext(root);
         // loadChangeContext will auto-detect schema from metadata if not provided
         const context = loadChangeContext(projectRoot, changeName, options.schema, {
             changeDir: getChangeDir(planningHome, changeName),
             planningHome,
+            projectConfig,
         });
         if (!artifactId) {
             spinner?.stop();
@@ -90,32 +150,11 @@ export async function instructionsCommand(artifactId, options) {
             const validIds = context.graph.getAllArtifacts().map((a) => a.id);
             throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
         }
-        const { projectConfig, references } = await loadRootConfigContext(root);
         const instructions = generateInstructions(context, artifactId, projectRoot, {
             projectConfig,
             references,
         });
         const isBlocked = instructions.dependencies.some((d) => !d.done);
-        const artifactOutputs = resolveArtifactOutputs(context.changeDir, artifact.generates);
-        await trackArtifactInstructions({
-            changeDir: context.changeDir,
-            changeName,
-            artifactId,
-            artifactWasDone: artifactOutputs.length > 0,
-            artifactPaths: artifactOutputs,
-        });
-        const contextFiles = {};
-        for (const a of context.graph.getAllArtifacts()) {
-            const outputs = resolveArtifactOutputs(context.changeDir, a.generates);
-            if (outputs.length > 0) {
-                contextFiles[a.id] = outputs;
-            }
-        }
-        await trackArtifactContentChanges({
-            changeDir: context.changeDir,
-            changeName,
-            contextFiles,
-        });
         spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify({ ...instructions, root: toRootOutput(root) }, null, 2));
@@ -133,6 +172,17 @@ export function printInstructionsText(instructions, isBlocked) {
     // Opening tag
     console.log(`<artifact id="${artifactId}" change="${changeName}" schema="${schemaName}">`);
     console.log();
+    // Artifacts skipped via skip_specs get no creation directive: emitting the
+    // task/template anyway would prompt an agent to write spec files that
+    // validate then rejects as conflicting with the marker.
+    if (instructions.skipped) {
+        console.log('<warning>');
+        console.log(instructions.warning ?? 'This artifact is skipped (skip_specs is set in .openspec.yaml).');
+        console.log('</warning>');
+        console.log();
+        console.log('</artifact>');
+        return;
+    }
     // Warning for blocked artifacts
     if (isBlocked) {
         const missing = dependencies.filter((d) => !d.done).map((d) => d.id);
@@ -174,9 +224,18 @@ export function printInstructionsText(instructions, isBlocked) {
     // Dependencies (files to read for context)
     if (dependencies.length > 0) {
         console.log('<dependencies>');
-        console.log('Read these files for context before creating this artifact:');
+        console.log('Read the current contents of these files before creating this artifact (re-read them from disk even if you saw them earlier - they may have been edited):');
         console.log();
         for (const dep of dependencies) {
+            // A dependency satisfied via skip_specs has no files by design: telling
+            // the agent to read them (or calling them "done") would send it hunting
+            // for spec files that must not exist.
+            if (dep.skipped) {
+                console.log(`<dependency id="${dep.id}" status="skipped">`);
+                console.log(`  <description>Skipped: the change declares skip_specs, so this artifact has no files to read.</description>`);
+                console.log('</dependency>');
+                continue;
+            }
             const status = dep.done ? 'done' : 'missing';
             const fullPath = path.join(changeDir, dep.path);
             console.log(`<dependency id="${dep.id}" status="${status}">`);
@@ -224,49 +283,29 @@ export function printInstructionsText(instructions, isBlocked) {
 // Apply Instructions Command
 // -----------------------------------------------------------------------------
 /**
- * Parses tasks.md content and extracts task items with their completion status.
+ * Turns parsed task lines into the listed task items.
+ *
+ * A checkbox with no text after it is left out of the list: this is work for an
+ * agent to act on and tick off, and a bare `- [ ]` gives it nothing to match.
+ * It still counts toward progress, which is taken from every parsed line, so
+ * this list can be shorter than the totals beside it but never disagrees with
+ * `openspec list` or archive about how much work is left. An empty list is also
+ * what puts apply in its "nothing to work on" state, so a file of nothing but
+ * text-less checkboxes asks to be rewritten instead of being called done.
  */
-function parseTasksFile(content) {
+function toTaskItems(parsed) {
     const tasks = [];
-    const lines = content.split('\n');
-    let taskIndex = 0;
-    for (const line of lines) {
-        // Match checkbox patterns: - [ ] or - [x] or - [X]
-        const checkboxMatch = line.match(/^[-*]\s*\[([ xX])\]\s*(.+)\s*$/);
-        if (checkboxMatch) {
-            taskIndex++;
-            const done = checkboxMatch[1].toLowerCase() === 'x';
-            const description = checkboxMatch[2].trim();
-            tasks.push({
-                id: `${taskIndex}`,
-                description,
-                done,
-            });
-        }
+    for (const task of parsed) {
+        if (task.description.length === 0)
+            continue;
+        tasks.push({
+            id: `${tasks.length + 1}`,
+            description: task.description,
+            done: task.done,
+        });
     }
     return tasks;
 }
-function resolveComprehensionQuestionCount(optionCount, specPaths, projectConfig, pendingTaskCount, artifactPresence) {
-    if (optionCount !== undefined && optionCount > 0) {
-        return optionCount;
-    }
-    const config = resolveComprehensionConfig(projectConfig);
-    return computeSpecStats(specPaths, config, pendingTaskCount, artifactPresence).questionCount;
-}
-async function emitComprehensionAttemptAfterPass(params) {
-    await trackComprehensionAttempt({
-        changeDir: params.changeDir,
-        changeName: params.changeName,
-        attempt: params.attempt,
-        scorePercent: params.scorePercent,
-        thresholdPercent: params.thresholdPercent,
-        questionCount: params.questionCount,
-        passed: true,
-        failureCountBefore: params.failureCountBefore,
-        nextMilestone: params.applyReadyEmitted ? 'apply_ready' : undefined,
-        contextFiles: params.contextFiles,
-    });
-}
 /**
  * Generates apply instructions for implementing tasks from a change.
  * Schema-aware: reads apply phase configuration from schema to determine
@@ -279,6 +318,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     const context = loadChangeContext(projectRoot, changeName, schemaName, {
         changeDir: getChangeDir(planningHome, changeName),
         planningHome,
+        projectConfig: options.projectConfig,
     });
     const changeDir = context.changeDir;
     // Get the full schema to access the apply phase configuration
@@ -289,9 +329,15 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
     const tracksFile = applyConfig?.tracks ?? null;
     const schemaInstruction = applyConfig?.instruction ?? null;
-    // Check which required artifacts are missing
+    const operationInputs = loadOperationInputs(options.projectConfig ?? null, 'apply');
+    // Check which required artifacts are missing. Artifacts the change skips
+    // via skip_specs count as present - their files must not exist, and
+    // status already reports them complete, so apply cannot block on them.
     const missingArtifacts = [];
     for (const artifactId of requiredArtifactIds) {
+        if (context.skippedArtifacts?.has(artifactId)) {
+            continue;
+        }
         const artifact = schema.artifacts.find((a) => a.id === artifactId);
         if (artifact && resolveArtifactOutputs(changeDir, artifact.generates).length === 0) {
             missingArtifacts.push(artifactId);
@@ -306,38 +352,47 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         }
     }
     // Parse tasks if tracking file exists
-    let tasks = [];
+    let parsedTasks = [];
     let tracksFileExists = false;
     if (tracksFile) {
-        const tracksPath = path.join(changeDir, tracksFile);
+        const tracksPath = resolveArtifactOutputPath(changeDir, tracksFile);
         tracksFileExists = fs.existsSync(tracksPath);
         if (tracksFileExists) {
             const tasksContent = await fs.promises.readFile(tracksPath, 'utf-8');
-            tasks = parseTasksFile(tasksContent);
+            parsedTasks = parseTaskLines(tasksContent);
         }
     }
-    // Calculate progress
-    const total = tasks.length;
-    const complete = tasks.filter((t) => t.done).length;
+    const tasks = toTaskItems(parsedTasks);
+    // Calculate progress over every checkbox in the file, listed or not, so these
+    // numbers match `openspec list` and archive's incomplete-task check.
+    const total = parsedTasks.length;
+    const complete = parsedTasks.filter((task) => task.done).length;
     const remaining = total - complete;
     // Determine state and instruction
     let state;
     let instruction;
+    // Check comprehension quiz status first
+    const comprehensionStatus = await checkComprehensionStatus(changeName, changeDir, contextFiles);
     if (missingArtifacts.length > 0) {
         state = 'blocked';
         instruction = `Cannot apply this change yet. Missing artifacts: ${missingArtifacts.join(', ')}.\nUse the openspec-continue-change skill to create the missing artifacts first.`;
     }
+    else if (comprehensionStatus.required && !comprehensionStatus.passed) {
+        state = 'comprehension_blocked';
+        instruction = 'Complete the comprehension quiz in /opsx:apply before implementation (score ≥ 80% on proposal, design, specs, plan, and tasks; plan receives the majority of questions per questionAllocation).';
+    }
     else if (tracksFile && !tracksFileExists) {
         // Tracking file configured but doesn't exist yet
         const tracksFilename = path.basename(tracksFile);
         state = 'blocked';
         instruction = `The ${tracksFilename} file is missing and must be created.\nUse openspec-continue-change to generate the tracking file.`;
     }
-    else if (tracksFile && tracksFileExists && total === 0) {
-        // Tracking file exists but contains no tasks
+    else if (tracksFile && tracksFileExists && tasks.length === 0) {
+        // Tracking file exists but lists nothing an agent can work on: either no
+        // checkboxes at all, or only checkboxes with no text after them.
         const tracksFilename = path.basename(tracksFile);
         state = 'blocked';
-        instruction = `The ${tracksFilename} file exists but contains no tasks.\nAdd tasks to ${tracksFilename} or regenerate it with openspec-continue-change.`;
+        instruction = `The ${tracksFilename} file exists but contains no tasks to work on.\nAdd tasks to ${tracksFilename} or regenerate it with openspec-continue-change.`;
     }
     else if (tracksFile && remaining === 0 && total > 0) {
         state = 'all_done';
@@ -352,58 +407,6 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         state = 'ready';
         instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';
     }
-    let missingComprehension;
-    let comprehension;
-    let applyReadyEmitted = false;
-    await trackArtifactContentChanges({ changeDir, changeName, contextFiles });
-    await maybeEmitProposalReady({
-        changeDir,
-        changeName,
-        schema: context.schemaName,
-        missingArtifacts,
-        artifactCount: schema.artifacts.length,
-        contextFiles,
-    });
-    if (state === 'ready') {
-        const specPaths = contextFiles.specs ?? [];
-        const tasksPath = tracksFile && tracksFileExists ? path.join(changeDir, tracksFile) : null;
-        const planPath = resolvePlanPath(contextFiles, changeDir);
-        const pendingTaskCount = tasks.filter((task) => !task.done).length;
-        const artifactPresence = buildArtifactPresence(contextFiles, pendingTaskCount);
-        const gate = checkComprehensionGate(changeDir, specPaths, options.projectConfig ?? readProjectConfig(projectRoot), { tasksPath, planPath, pendingTaskCount, artifactPresence });
-        if (gate.active && !gate.passed && gate.info) {
-            state = 'blocked';
-            missingComprehension = true;
-            comprehension = gate.info;
-            instruction = `Complete the comprehension quiz in /opsx:apply before implementation (score ≥ ${gate.info.thresholdPercent}% on proposal, design, specs, plan, and tasks; plan receives the majority of questions per questionAllocation).`;
-        }
-        else if (gate.active && gate.info) {
-            comprehension = gate.info;
-        }
-        applyReadyEmitted = await maybeEmitApplyReady({
-            changeDir,
-            changeName,
-            state,
-            contextFiles,
-        });
-        if (gate.active && gate.info) {
-            await trackComprehensionGateChecked({
-                changeDir,
-                changeName,
-                passed: gate.passed,
-                gateInfo: gate.info,
-                state: gate.passed ? 'ready' : 'blocked',
-                contextFiles,
-            });
-            if (!gate.passed && gate.info.bestScorePercent !== undefined) {
-                await trackComprehensionRetakeRequired({
-                    changeDir,
-                    changeName,
-                    gateInfo: gate.info,
-                });
-            }
-        }
-    }
     return {
         changeName,
         changeDir,
@@ -413,11 +416,11 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         tasks,
         state,
         missingArtifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
-        missingComprehension,
-        comprehension,
         instruction,
-        applyReadyEmitted,
+        comprehension: comprehensionStatus,
+        applyReadyEmitted: comprehensionStatus.passed,
         ...(references !== undefined ? { references } : {}),
+        ...operationInputs,
     };
 }
 export async function applyInstructionsCommand(options) {
@@ -435,119 +438,9 @@ export async function applyInstructionsCommand(options) {
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
+        // One parsed config snapshot supplies schema fallback, references, context,
+        // and operation guidance for this command.
         const { projectConfig, references } = await loadRootConfigContext(root);
-        if (options.recordComprehensionPass) {
-            if (options.score === undefined) {
-                spinner?.stop();
-                throw new Error('--score is required with --record-comprehension-pass');
-            }
-            const context = loadChangeContext(projectRoot, changeName, options.schema, {
-                changeDir: getChangeDir(planningHome, changeName),
-                planningHome,
-            });
-            const changeDir = context.changeDir;
-            const schema = resolveSchema(context.schemaName, projectRoot);
-            const specPaths = [];
-            const specsArtifact = schema.artifacts.find((a) => a.id === 'specs');
-            if (specsArtifact) {
-                specPaths.push(...resolveArtifactOutputs(changeDir, specsArtifact.generates));
-            }
-            const tracksFile = schema.apply?.tracks ?? null;
-            const tasksPath = tracksFile ? path.join(changeDir, tracksFile) : null;
-            const planPath = fs.existsSync(path.join(changeDir, 'plan.md'))
-                ? path.join(changeDir, 'plan.md')
-                : null;
-            const pendingTaskCount = tasksPath && fs.existsSync(tasksPath)
-                ? parseTasksFile(fs.readFileSync(tasksPath, 'utf-8')).filter((t) => !t.done).length
-                : 0;
-            const contextFilesForPresence = {};
-            for (const artifact of schema.artifacts) {
-                const outputs = resolveArtifactOutputs(changeDir, artifact.generates);
-                if (outputs.length > 0) {
-                    contextFilesForPresence[artifact.id] = outputs;
-                }
-            }
-            const artifactPresence = buildArtifactPresence(contextFilesForPresence, pendingTaskCount);
-            const questionCount = resolveComprehensionQuestionCount(options.questionCount, specPaths, projectConfig, pendingTaskCount, artifactPresence);
-            const { attempt, failureCountBefore } = await incrementComprehensionAttempt(changeDir);
-            try {
-                const record = recordComprehensionPass({
-                    changeDir,
-                    specPaths,
-                    tasksPath,
-                    planPath,
-                    projectConfig,
-                    scorePercent: options.score,
-                    attempt,
-                    questionCount,
-                    pendingTaskCount,
-                    artifactPresence,
-                });
-                spinner?.stop();
-                const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
-                    planningHome,
-                    references,
-                    projectConfig,
-                });
-                await emitComprehensionAttemptAfterPass({
-                    changeDir,
-                    changeName,
-                    attempt: record.attempt,
-                    failureCountBefore,
-                    scorePercent: record.score_percent,
-                    thresholdPercent: record.threshold_percent,
-                    questionCount: record.question_count,
-                    contextFiles: instructions.contextFiles,
-                    applyReadyEmitted: instructions.applyReadyEmitted ?? false,
-                });
-                if (options.json) {
-                    console.log(JSON.stringify({
-                        recorded: true,
-                        comprehensionPass: record,
-                        ...instructions,
-                        root: toRootOutput(root),
-                    }, null, 2));
-                    return;
-                }
-                console.log(`Comprehension pass recorded (${record.score_percent}%).`);
-                printApplyInstructionsText(instructions);
-                return;
-            }
-            catch (error) {
-                spinner?.stop();
-                if (error instanceof ComprehensionPassError) {
-                    await incrementComprehensionFailureCount(changeDir);
-                    await trackComprehensionAttempt({
-                        changeDir,
-                        changeName,
-                        attempt,
-                        scorePercent: options.score,
-                        thresholdPercent: error.threshold,
-                        questionCount,
-                        passed: false,
-                        failureCountBefore,
-                        contextFiles: contextFilesForPresence,
-                    });
-                    if (options.json) {
-                        console.log(JSON.stringify({
-                            recorded: false,
-                            status: [
-                                {
-                                    severity: 'error',
-                                    code: 'comprehension_score_below_threshold',
-                                    message: error.message,
-                                },
-                            ],
-                            root: toRootOutput(root),
-                        }, null, 2));
-                        process.exitCode = 1;
-                        return;
-                    }
-                }
-                throw error;
-            }
-        }
-        // generateApplyInstructions uses loadChangeContext which auto-detects schema
         const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
             planningHome,
             references,
@@ -566,7 +459,7 @@ export async function applyInstructionsCommand(options) {
     }
 }
 export function printApplyInstructionsText(instructions) {
-    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, missingComprehension, comprehension, instruction, } = instructions;
+    const { changeName, schemaName, contextFiles, progress, tasks, state, missingArtifacts, instruction } = instructions;
     console.log(`## Apply: ${changeName}`);
     console.log(`Schema: ${schemaName}`);
     console.log();
@@ -582,24 +475,6 @@ export function printApplyInstructionsText(instructions) {
         console.log('Use the openspec-continue-change skill to create these first.');
         console.log();
     }
-    if (state === 'blocked' && missingComprehension && comprehension) {
-        console.log('### ⚠️ Comprehension Required');
-        console.log();
-        console.log(`Pass the comprehension quiz (score ≥ ${comprehension.thresholdPercent}%) before implementation.`);
-        console.log(`Questions: ${comprehension.questionCount} (${comprehension.optionsPerQuestion} options each)`);
-        const allocationParts = Object.entries(comprehension.questionAllocation)
-            .filter(([, count]) => (count ?? 0) > 0)
-            .map(([category, count]) => `${category}×${count}`);
-        if (allocationParts.length > 0) {
-            console.log(`Allocation: ${allocationParts.join(', ')}`);
-        }
-        console.log(`Specs: ${comprehension.requirementCount} requirements, ${comprehension.scenarioCount} scenarios; Tasks: ${comprehension.pendingTaskCount} pending`);
-        if (comprehension.bestScorePercent !== undefined) {
-            console.log(`Previous score: ${comprehension.bestScorePercent}% (artifacts changed — retake required)`);
-        }
-        console.log('Complete the quiz via /opsx:apply.');
-        console.log();
-    }
     // Context files (dynamically from schema)
     const contextFileEntries = Object.entries(contextFiles);
     if (contextFileEntries.length > 0) {
@@ -634,125 +509,57 @@ export function printApplyInstructionsText(instructions) {
     // Instruction
     console.log('### Instruction');
     console.log(instruction);
+    console.log();
+    printOperationInputsText(instructions);
 }
-// -----------------------------------------------------------------------------
-// Modify Instructions Command (pre-apply artifact revision)
-// -----------------------------------------------------------------------------
-function buildModifyInstruction(sourceArtifact, downstreamArtifacts, modifyInput) {
-    const downstreamLine = downstreamArtifacts.length > 0
-        ? `Downstream artifacts to refresh: ${downstreamArtifacts.join(', ')}.`
-        : 'No downstream artifacts depend on this source.';
-    const requestLine = modifyInput
-        ? `User modify request: ${modifyInput}`
-        : 'Apply the user modify request from the conversation.';
-    return [
-        `Revise the "${sourceArtifact}" artifact for this change (pre-apply only).`,
-        requestLine,
-        downstreamLine,
-        'For each artifact in artifactsToUpdate (in order): run openspec instructions <id> --change <name> --json, read upstream dependencies, apply a surgical edit aligned with the modify request, and write to resolvedOutputPath.',
-        'When proposal capabilities change, add/remove/rename specs under specs/ accordingly.',
-        'After all updates, run openspec status --change <name> --json, then hand off to /opsx:apply.',
-    ].join('\n');
+export function generateArchiveInstructions(changeName, projectConfig) {
+    return {
+        changeName,
+        ...loadOperationInputs(projectConfig, 'archive'),
+    };
 }
-export async function modifyInstructionsCommand(options) {
+export async function archiveInstructionsCommand(options) {
     const root = await resolveRootForCommand(options, { json: options.json });
     if (!root) {
         return;
     }
-    const spinner = options.json ? undefined : ora('Generating modify instructions...').start();
+    const spinner = options.json ? undefined : ora('Loading archive inputs...').start();
     try {
-        const planningHome = toPlanningHome(root);
-        const projectRoot = root.path;
-        const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
-        if (options.schema) {
-            validateSchemaExists(options.schema, projectRoot);
-        }
-        const sourceArtifact = options.artifact?.trim();
-        if (!sourceArtifact) {
-            spinner?.stop();
-            throw new Error('Missing required option --artifact. Specify the artifact to modify (e.g., design, proposal, tasks).');
-        }
-        const modifyInput = await resolveWorkflowInputAsync({
-            workflowInput: options.workflowInput,
-            workflowInputFile: options.workflowInputFile,
-        });
-        const editor = normalizeEditor(options.editor);
-        const context = loadChangeContext(projectRoot, changeName, options.schema, {
-            changeDir: getChangeDir(planningHome, changeName),
-            planningHome,
-        });
-        const artifact = context.graph.getArtifact(sourceArtifact);
-        if (!artifact) {
-            spinner?.stop();
-            const validIds = context.graph.getAllArtifacts().map((a) => a.id);
-            throw new Error(`Artifact '${sourceArtifact}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
-        }
-        const applyInstructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
-            planningHome,
-        });
-        if (applyInstructions.progress.complete > 0) {
-            spinner?.stop();
-            throw new Error(`Apply has already started (${applyInstructions.progress.complete}/${applyInstructions.progress.total} tasks complete). /opsx:modify is pre-apply only. Edit artifacts manually or start a new change.`);
-        }
-        if (applyInstructions.missingArtifacts && applyInstructions.missingArtifacts.length > 0) {
-            spinner?.stop();
-            throw new Error(`Change is not ready to modify. Missing artifacts: ${applyInstructions.missingArtifacts.join(', ')}. Use /opsx:continue or /opsx:propose to create them first.`);
-        }
-        const sourceOutputs = resolveArtifactOutputs(context.changeDir, artifact.generates);
-        if (sourceOutputs.length === 0) {
-            spinner?.stop();
-            throw new Error(`Artifact '${sourceArtifact}' does not exist yet. Use /opsx:continue to create it first.`);
-        }
-        const downstreamArtifacts = context.graph.getTransitiveDependents(sourceArtifact);
-        const artifactsToUpdate = [sourceArtifact, ...downstreamArtifacts];
-        const status = formatChangeStatus(context, isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
-        await trackArtifactModifyRequested({
-            changeDir: context.changeDir,
-            changeName,
-            schema: context.schemaName,
-            sourceArtifactId: sourceArtifact,
-            downstreamArtifactIds: downstreamArtifacts,
-            artifactsToUpdate,
-            modifyInput,
-            editor,
-        });
-        const payload = {
-            changeName,
-            schemaName: context.schemaName,
-            sourceArtifact,
-            ...(modifyInput ? { modifyInput } : {}),
-            downstreamArtifacts,
-            artifactsToUpdate,
-            changeRoot: context.changeDir,
-            artifactPaths: status.artifactPaths,
-            phase: 'pre_apply',
-            instruction: buildModifyInstruction(sourceArtifact, downstreamArtifacts, modifyInput),
-        };
+        const changeName = await validateChangeExists(options.change, root.path, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
+        const projectConfig = readProjectConfig(root.path);
+        const instructions = generateArchiveInstructions(changeName, projectConfig);
         spinner?.stop();
         if (options.json) {
-            console.log(JSON.stringify({ ...payload, root: toRootOutput(root) }, null, 2));
+            console.log(JSON.stringify({ ...instructions, root: toRootOutput(root) }, null, 2));
             return;
         }
-        printModifyInstructionsText(payload);
+        printArchiveInstructionsText(instructions);
     }
     catch (error) {
         spinner?.stop();
         throw error;
     }
 }
-export function printModifyInstructionsText(instructions) {
-    console.log(`## Modify: ${instructions.changeName}`);
-    console.log(`Schema: ${instructions.schemaName}`);
-    console.log(`Phase: ${instructions.phase}`);
+export function printArchiveInstructionsText(instructions) {
+    console.log(`## Archive Inputs: ${instructions.changeName}`);
     console.log();
-    console.log(`Source artifact: ${instructions.sourceArtifact}`);
-    if (instructions.modifyInput) {
-        console.log(`Modify request: ${instructions.modifyInput}`);
+    printOperationInputsText(instructions);
+}
+function printOperationInputsText(inputs) {
+    if (inputs.context) {
+        console.log('### Project Context (required instruction input)');
+        console.log(inputs.context);
+        console.log();
+    }
+    if (inputs.operationGuidance && inputs.operationGuidance.length > 0) {
+        console.log('### Operation Guidance (advisory)');
+        for (const guidance of inputs.operationGuidance) {
+            console.log(`- ${guidance}`);
+        }
+        console.log();
+    }
+    if (!inputs.context && !inputs.operationGuidance) {
+        console.log('No project context or operation guidance configured.');
     }
-    console.log(`Downstream: ${instructions.downstreamArtifacts.length > 0 ? instructions.downstreamArtifacts.join(', ') : '(none)'}`);
-    console.log(`Artifacts to update: ${instructions.artifactsToUpdate.join(', ')}`);
-    console.log();
-    console.log('### Instruction');
-    console.log(instructions.instruction);
 }
 //# sourceMappingURL=instructions.js.map