@codewalla_india/openspec 1.0.4 → 1.0.5

package/dist/commands/workflow/instructions.js

@@ -15,6 +15,22 @@ import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { readProjectConfig } from '../../core/project-config.js';
 import { checkComprehensionGate, ComprehensionPassError, recordComprehensionPass, } from '../../core/comprehension/index.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,
+    };
+}
+function resolvePlanPath(contextFiles, changeDir) {
+    if (contextFiles.plan?.[0]) {
+        return contextFiles.plan[0];
+    }
+    const fallback = path.join(changeDir, 'plan.md');
+    return fs.existsSync(fallback) ? fallback : null;
+}
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
@@ -298,13 +314,15 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     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 gate = checkComprehensionGate(changeDir, specPaths, options.projectConfig ?? readProjectConfig(projectRoot), { tasksPath, pendingTaskCount });
+        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, and tasks).`;
+            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;
@@ -359,15 +377,32 @@ export async function applyInstructionsCommand(options) {
             }
             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);
             try {
                 const record = recordComprehensionPass({
                     changeDir,
                     specPaths,
                     tasksPath,
+                    planPath,
                     projectConfig,
                     scorePercent: options.score,
                     attempt: options.attempt ?? 1,
                     questionCount: options.questionCount ?? 0,
+                    pendingTaskCount,
+                    artifactPresence,
                 });
                 spinner?.stop();
                 if (options.json) {
@@ -453,11 +488,17 @@ export function printApplyInstructionsText(instructions) {
     if (state === 'blocked' && missingComprehension && comprehension) {
         console.log('### ⚠️ Comprehension Required');
         console.log();
-        console.log(`Pass the spec and task comprehension quiz (score ≥ ${comprehension.thresholdPercent}%) before implementation.`);
-        console.log(`Questions: ${comprehension.questionCount}`);
+        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}% (specs changed — retake required)`);
+            console.log(`Previous score: ${comprehension.bestScorePercent}% (artifacts changed — retake required)`);
         }
         console.log('Complete the quiz via /opsx:apply.');
         console.log();

package/dist/commands/workflow/shared.d.ts

@@ -23,6 +23,8 @@ export interface ApplyComprehensionInfo {
     thresholdPercent: number;
     bestScorePercent?: number;
     questionCount: number;
+    questionAllocation: Record<string, number>;
+    optionsPerQuestion: number;
     requirementCount: number;
     scenarioCount: number;
     pendingTaskCount: number;

package/dist/core/completions/command-registry.js

@@ -191,6 +191,25 @@ export const COMMAND_REGISTRY = [
                 description: 'Schema override',
                 takesValue: true,
             },
+            {
+                name: 'record-comprehension-pass',
+                description: 'Record a successful comprehension quiz pass (use with instructions apply)',
+            },
+            {
+                name: 'score',
+                description: 'Quiz score 0-100 (required with --record-comprehension-pass)',
+                takesValue: true,
+            },
+            {
+                name: 'attempt',
+                description: 'Quiz attempt number',
+                takesValue: true,
+            },
+            {
+                name: 'question-count',
+                description: 'Number of quiz questions taken',
+                takesValue: true,
+            },
             COMMON_FLAGS.json,
             COMMON_FLAGS.store,
         ],

package/dist/core/comprehension/fingerprint.d.ts

@@ -1,5 +1,14 @@
+export interface ApplyArtifactFingerprintInput {
+    specPaths: string[];
+    tasksPath?: string | null;
+    planPath?: string | null;
+}
 /**
- * SHA-256 fingerprint of delta spec and optional tasks file contents.
+ * SHA-256 fingerprint of delta specs and optional plan/tasks file contents.
+ */
+export declare function fingerprintApplyArtifacts(input: ApplyArtifactFingerprintInput): string;
+/**
+ * @deprecated Use fingerprintApplyArtifacts
  */
 export declare function fingerprintSpecFiles(specPaths: string[], tasksPath?: string | null): string;
 //# sourceMappingURL=fingerprint.d.ts.map

package/dist/core/comprehension/fingerprint.js

@@ -1,25 +1,33 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
+function hashFileContent(hash, label, filePath) {
+    hash.update(`${label}:`);
+    hash.update(filePath);
+    hash.update('\0');
+    hash.update(readFileSync(filePath, 'utf-8'));
+    hash.update('\0');
+}
 /**
- * SHA-256 fingerprint of delta spec and optional tasks file contents.
+ * SHA-256 fingerprint of delta specs and optional plan/tasks file contents.
  */
-export function fingerprintSpecFiles(specPaths, tasksPath) {
-    const sorted = [...specPaths].sort();
+export function fingerprintApplyArtifacts(input) {
+    const sorted = [...input.specPaths].sort();
     const hash = createHash('sha256');
     for (const specPath of sorted) {
-        hash.update('spec:');
-        hash.update(specPath);
-        hash.update('\0');
-        hash.update(readFileSync(specPath, 'utf-8'));
-        hash.update('\0');
+        hashFileContent(hash, 'spec', specPath);
     }
-    if (tasksPath && existsSync(tasksPath)) {
-        hash.update('tasks:');
-        hash.update(tasksPath);
-        hash.update('\0');
-        hash.update(readFileSync(tasksPath, 'utf-8'));
-        hash.update('\0');
+    if (input.planPath && existsSync(input.planPath)) {
+        hashFileContent(hash, 'plan', input.planPath);
+    }
+    if (input.tasksPath && existsSync(input.tasksPath)) {
+        hashFileContent(hash, 'tasks', input.tasksPath);
     }
     return hash.digest('hex');
 }
+/**
+ * @deprecated Use fingerprintApplyArtifacts
+ */
+export function fingerprintSpecFiles(specPaths, tasksPath) {
+    return fingerprintApplyArtifacts({ specPaths, tasksPath });
+}
 //# sourceMappingURL=fingerprint.js.map

package/dist/core/comprehension/index.d.ts

@@ -1,15 +1,18 @@
 import type { ProjectConfig } from '../project-config.js';
 import { type ComprehensionPassRecord } from './pass-record.js';
+import { OPTIONS_PER_QUESTION, type ArtifactPresence, type QuestionAllocation } from './stats.js';
 export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, type ComprehensionConfig, } from './config.js';
-export { fingerprintSpecFiles } from './fingerprint.js';
+export { fingerprintApplyArtifacts, fingerprintSpecFiles } from './fingerprint.js';
 export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, type ComprehensionPassRecord, } from './pass-record.js';
-export { computeQuestionCount, computeSpecStats, countSpecStats, type SpecStats } from './stats.js';
+export { computeQuestionAllocation, computeQuestionCount, computeSpecStats, countSpecStats, OPTIONS_PER_QUESTION, type ArtifactPresence, type QuestionAllocation, type QuestionCategory, type SpecStats, } from './stats.js';
 export interface ComprehensionGateInfo {
     required: boolean;
     passed: boolean;
     thresholdPercent: number;
     bestScorePercent?: number;
     questionCount: number;
+    questionAllocation: QuestionAllocation;
+    optionsPerQuestion: number;
     requirementCount: number;
     scenarioCount: number;
     pendingTaskCount: number;
@@ -17,7 +20,9 @@ export interface ComprehensionGateInfo {
 }
 export interface ComprehensionGateOptions {
     tasksPath?: string | null;
+    planPath?: string | null;
     pendingTaskCount?: number;
+    artifactPresence?: ArtifactPresence;
 }
 export interface ComprehensionGateResult {
     active: boolean;
@@ -40,10 +45,13 @@ export declare function recordComprehensionPass(input: {
     changeDir: string;
     specPaths: string[];
     tasksPath?: string | null;
+    planPath?: string | null;
     projectConfig: ProjectConfig | null | undefined;
     scorePercent: number;
     attempt: number;
     questionCount: number;
     pendingTaskCount?: number;
+    artifactPresence?: ArtifactPresence;
 }): ComprehensionPassRecord;
+export { OPTIONS_PER_QUESTION as comprehensionOptionsPerQuestion };
 //# sourceMappingURL=index.d.ts.map

package/dist/core/comprehension/index.js

@@ -1,11 +1,11 @@
 import { resolveComprehensionConfig } from './config.js';
-import { fingerprintSpecFiles } from './fingerprint.js';
+import { fingerprintApplyArtifacts } from './fingerprint.js';
 import { buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
-import { computeSpecStats } from './stats.js';
+import { computeSpecStats, OPTIONS_PER_QUESTION, } from './stats.js';
 export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, } from './config.js';
-export { fingerprintSpecFiles } from './fingerprint.js';
+export { fingerprintApplyArtifacts, fingerprintSpecFiles } from './fingerprint.js';
 export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
-export { computeQuestionCount, computeSpecStats, countSpecStats } from './stats.js';
+export { computeQuestionAllocation, computeQuestionCount, computeSpecStats, countSpecStats, OPTIONS_PER_QUESTION, } from './stats.js';
 /**
  * Evaluate whether apply is blocked by the comprehension gate.
  */
@@ -13,17 +13,19 @@ export function checkComprehensionGate(changeDir, specPaths, projectConfig, gate
     const config = resolveComprehensionConfig(projectConfig);
     const pendingTaskCount = gateOptions.pendingTaskCount ?? 0;
     const tasksPath = gateOptions.tasksPath ?? null;
+    const planPath = gateOptions.planPath ?? null;
+    const artifactPresence = gateOptions.artifactPresence ?? {};
     if (!config.enabled) {
         return { active: false, passed: true };
     }
     if (specPaths.length === 0) {
         return { active: false, passed: true };
     }
-    const stats = computeSpecStats(specPaths, config, pendingTaskCount);
+    const stats = computeSpecStats(specPaths, config, pendingTaskCount, artifactPresence);
     if (stats.requirementCount === 0) {
         return { active: false, passed: true };
     }
-    const fingerprint = fingerprintSpecFiles(specPaths, tasksPath);
+    const fingerprint = fingerprintApplyArtifacts({ specPaths, tasksPath, planPath });
     const record = readPassRecord(changeDir);
     const passed = isPassValid(record, fingerprint);
     const info = {
@@ -31,6 +33,8 @@ export function checkComprehensionGate(changeDir, specPaths, projectConfig, gate
         passed,
         thresholdPercent: config.thresholdPercent,
         questionCount: stats.questionCount,
+        questionAllocation: stats.questionAllocation,
+        optionsPerQuestion: stats.optionsPerQuestion,
         requirementCount: stats.requirementCount,
         scenarioCount: stats.scenarioCount,
         pendingTaskCount: stats.pendingTaskCount,
@@ -62,8 +66,12 @@ export function recordComprehensionPass(input) {
     }
     const stats = input.questionCount > 0
         ? { questionCount: input.questionCount }
-        : computeSpecStats(input.specPaths, config, input.pendingTaskCount ?? 0);
-    const fingerprint = fingerprintSpecFiles(input.specPaths, input.tasksPath);
+        : computeSpecStats(input.specPaths, config, input.pendingTaskCount ?? 0, input.artifactPresence ?? {});
+    const fingerprint = fingerprintApplyArtifacts({
+        specPaths: input.specPaths,
+        tasksPath: input.tasksPath,
+        planPath: input.planPath,
+    });
     const record = buildPassRecord({
         scorePercent: input.scorePercent,
         thresholdPercent: config.thresholdPercent,
@@ -75,4 +83,5 @@ export function recordComprehensionPass(input) {
     deleteSessionRecord(input.changeDir);
     return record;
 }
+export { OPTIONS_PER_QUESTION as comprehensionOptionsPerQuestion };
 //# sourceMappingURL=index.js.map

package/dist/core/comprehension/stats.d.ts

@@ -1,10 +1,27 @@
 import type { ComprehensionConfig } from './config.js';
+export declare const OPTIONS_PER_QUESTION = 3;
+export type QuestionCategory = 'plan' | 'specs' | 'design' | 'proposal' | 'tasks';
+export type QuestionAllocation = Partial<Record<QuestionCategory, number>>;
+export interface ArtifactPresence {
+    hasPlan?: boolean;
+    hasProposal?: boolean;
+    hasDesign?: boolean;
+    hasSpecs?: boolean;
+    hasTasks?: boolean;
+}
 export interface SpecStats {
     requirementCount: number;
     scenarioCount: number;
     pendingTaskCount: number;
     questionCount: number;
+    questionAllocation: QuestionAllocation;
+    optionsPerQuestion: number;
 }
+/**
+ * Distribute quiz questions across artifact categories.
+ * When plan exists, plan receives ceil(total/2) — strictly more than any other category.
+ */
+export declare function computeQuestionAllocation(total: number, presence: ArtifactPresence): QuestionAllocation;
 /**
  * Count requirements and scenarios across delta spec files.
  */
@@ -14,5 +31,5 @@ export declare function countSpecStats(specPaths: string[]): Pick<SpecStats, 're
  * clamp(min, max, round(req * 0.6 + scenarios * 0.15 + pendingTasks * 0.15)).
  */
 export declare function computeQuestionCount(requirementCount: number, scenarioCount: number, pendingTaskCount: number, config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>): number;
-export declare function computeSpecStats(specPaths: string[], config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>, pendingTaskCount?: number): SpecStats;
+export declare function computeSpecStats(specPaths: string[], config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>, pendingTaskCount?: number, presence?: ArtifactPresence): SpecStats;
 //# sourceMappingURL=stats.d.ts.map

package/dist/core/comprehension/stats.js

@@ -1,6 +1,89 @@
 import { readFileSync } from 'node:fs';
 import { parseDeltaSpec } from '../parsers/requirement-blocks.js';
 const SCENARIO_HEADER_REGEX = /^####\s*Scenario:/gim;
+export const OPTIONS_PER_QUESTION = 3;
+const NON_PLAN_PRIORITY = ['specs', 'design', 'proposal', 'tasks'];
+function isCategoryPresent(category, presence) {
+    switch (category) {
+        case 'plan':
+            return presence.hasPlan === true;
+        case 'specs':
+            return presence.hasSpecs === true;
+        case 'design':
+            return presence.hasDesign === true;
+        case 'proposal':
+            return presence.hasProposal === true;
+        case 'tasks':
+            return presence.hasTasks === true;
+        default:
+            return false;
+    }
+}
+function sumAllocation(allocation) {
+    return Object.values(allocation).reduce((sum, n) => sum + (n ?? 0), 0);
+}
+/**
+ * Distribute quiz questions across artifact categories.
+ * When plan exists, plan receives ceil(total/2) — strictly more than any other category.
+ */
+export function computeQuestionAllocation(total, presence) {
+    if (total <= 0) {
+        return {};
+    }
+    if (presence.hasPlan) {
+        const allocation = {};
+        const planQuota = Math.ceil(total / 2);
+        allocation.plan = planQuota;
+        let remainder = total - planQuota;
+        for (const category of NON_PLAN_PRIORITY) {
+            if (remainder <= 0) {
+                break;
+            }
+            if (!isCategoryPresent(category, presence)) {
+                continue;
+            }
+            allocation[category] = (allocation[category] ?? 0) + 1;
+            remainder--;
+        }
+        const presentOthers = NON_PLAN_PRIORITY.filter((category) => isCategoryPresent(category, presence));
+        let index = 0;
+        while (remainder > 0 && presentOthers.length > 0) {
+            const category = presentOthers[index % presentOthers.length];
+            allocation[category] = (allocation[category] ?? 0) + 1;
+            remainder--;
+            index++;
+        }
+        return allocation;
+    }
+    return computeQuestionAllocationEven(total, presence);
+}
+/**
+ * Even split when plan is absent: at least one per present category, extras specs-first.
+ */
+function computeQuestionAllocationEven(total, presence) {
+    const present = NON_PLAN_PRIORITY.filter((category) => isCategoryPresent(category, presence));
+    if (present.length === 0) {
+        return {};
+    }
+    const allocation = {};
+    let assigned = 0;
+    for (const category of present) {
+        if (assigned >= total) {
+            break;
+        }
+        allocation[category] = 1;
+        assigned++;
+    }
+    let remainder = total - assigned;
+    let index = 0;
+    while (remainder > 0) {
+        const category = present[index % present.length];
+        allocation[category] = (allocation[category] ?? 0) + 1;
+        remainder--;
+        index++;
+    }
+    return allocation;
+}
 function countScenariosInBlock(raw) {
     const matches = raw.match(SCENARIO_HEADER_REGEX);
     return matches?.length ?? 0;
@@ -33,9 +116,18 @@ export function computeQuestionCount(requirementCount, scenarioCount, pendingTas
     const raw = Math.round(requirementCount * 0.6 + scenarioCount * 0.15 + pendingTaskCount * 0.15);
     return clamp(config.minQuestions, config.maxQuestions, raw);
 }
-export function computeSpecStats(specPaths, config, pendingTaskCount = 0) {
+export function computeSpecStats(specPaths, config, pendingTaskCount = 0, presence = {}) {
     const { requirementCount, scenarioCount } = countSpecStats(specPaths);
     const questionCount = computeQuestionCount(requirementCount, scenarioCount, pendingTaskCount, config);
-    return { requirementCount, scenarioCount, pendingTaskCount, questionCount };
+    const questionAllocation = computeQuestionAllocation(questionCount, presence);
+    const allocationTotal = sumAllocation(questionAllocation);
+    return {
+        requirementCount,
+        scenarioCount,
+        pendingTaskCount,
+        questionCount: allocationTotal > 0 ? allocationTotal : questionCount,
+        questionAllocation,
+        optionsPerQuestion: OPTIONS_PER_QUESTION,
+    };
 }
 //# sourceMappingURL=stats.js.map

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

@@ -58,7 +58,7 @@ ${COMPREHENSION_QUIZ_GUIDANCE}
 
    After comprehension is passed (or not required), read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
+   - **spec-driven**: proposal, specs, design, plan, tasks
    - Other schemas: follow the contextFiles from CLI output
 
 6. **Show current progress**
@@ -227,7 +227,7 @@ ${COMPREHENSION_QUIZ_GUIDANCE}
 
    After comprehension is passed (or not required), read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
+   - **spec-driven**: proposal, specs, design, plan, tasks
    - Other schemas: follow the contextFiles from CLI output
 
 6. **Show current progress**

package/dist/core/templates/workflows/comprehension-guidance.d.ts

@@ -4,6 +4,6 @@
  * Interpolated into apply skill and slash command templates so agents run
  * a spec comprehension gate before implementation.
  */
-export declare const COMPREHENSION_QUIZ_GUIDANCE = "4. **Comprehension quiz (required before implementation)**\n\n   After `openspec instructions apply --change \"<name>\" --json`, check comprehension status:\n\n   - If `missingComprehension` is true OR `comprehension.required && !comprehension.passed`:\n     - Do NOT edit application source code or mark task checkboxes yet\n     - Read `contextFiles.proposal`, `contextFiles.design`, `contextFiles.specs`, and `contextFiles.tasks` (or the `tasks` array in apply JSON)\n     - Use `comprehension.questionCount` from the JSON as the number of questions\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - Each question MUST map to one artifact category:\n     - **Proposal**: motivation, scope, or impact from `proposal.md`\n     - **Design**: decisions, trade-offs, or approach from `design.md`\n     - **Specs**: a `### Requirement:` or `#### Scenario:` from delta specs\n     - **Tasks**: conceptual understanding of the implementation plan from pending (unchecked) tasks\n   - When proposal, design, specs (with requirements), and pending tasks all exist, include at least one question from each category; fill remaining slots from any category\n   - Do NOT use completed tasks as question sources\n   - Each question: 4 options (1 correct from the source substance, 3 plausible distractors from other proposal/design/requirements/scenarios/task substance in the change)\n\n   **Task question quality**\n   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design\n   - **Forbidden**: task numbers, checklist order, \"which task says X verbatim\", or answers identifiable only by task index or checkbox position\n   - Good: \"What is the primary file where quiz rules are centralized?\" (answer from task substance)\n   - Bad: \"Which task number updates `comprehension-guidance.ts`?\" or \"What is the exact text of task 2.1?\"\n\n   **Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)\n\n   **On failure (score below threshold)**\n   - Announce score and that a new quiz is required\n   - Update `.comprehension-session.yaml` in the change dir with `used_sources` from this attempt\n   - Generate a NEW question set using different proposal/design/requirement/scenario/task sources (avoid `used_sources`)\n   - Retry until pass\n\n   **On pass**\n   ```bash\n   openspec instructions apply --change \"<name>\" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json\n   ```\n   - Re-run `openspec instructions apply --change \"<name>\" --json`\n   - Confirm `state` is `\"ready\"` and `comprehension.passed` is true before continuing\n\n   **Output template**\n   ```\n   ## Applying: <change-name> \u2014 comprehension check\n\n   Proposal, design, specs (<requirementCount> requirements, <scenarioCount> scenarios), tasks (<pendingTaskCount> pending) \u2192 <questionCount> questions\n\n   Question 1/N: ...\n   ...\n   \u2713 Comprehension passed (<score>%, attempt <n>)\n   ```\n\n   Then continue to step 5 (show progress) and implementation.";
+export declare const COMPREHENSION_QUIZ_GUIDANCE = "4. **Comprehension quiz (required before implementation)**\n\n   After `openspec instructions apply --change \"<name>\" --json`, check comprehension status:\n\n   - If `missingComprehension` is true OR `comprehension.required && !comprehension.passed`:\n     - Do NOT edit application source code or mark task checkboxes yet\n     - Read `contextFiles.proposal`, `contextFiles.design`, `contextFiles.specs`, `contextFiles.plan`, and `contextFiles.tasks` (or the `tasks` array in apply JSON)\n     - Use `comprehension.questionCount` and `comprehension.questionAllocation` from the JSON\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - **Follow `comprehension.questionAllocation`** \u2014 generate the exact count per category (e.g. plan\u00D74, specs\u00D71); do not invent your own split\n   - Each question maps to one artifact category:\n     - **Proposal**: motivation, scope, or impact from `proposal.md`\n     - **Design**: decisions, trade-offs, or approach from `design.md`\n     - **Specs**: a `### Requirement:` or `#### Scenario:` from delta specs\n     - **Plan**: code map, file targets, test plan, sequencing, or alignment with design from `plan.md`\n     - **Tasks**: conceptual understanding of the implementation approach from pending (unchecked) tasks\n   - Do NOT use completed tasks as question sources\n   - Each question: **3 options** (`comprehension.optionsPerQuestion`, default 3) \u2014 1 correct from source substance, 2 plausible distractors from other proposal/design/spec/plan/task substance in the change\n\n   **Plan question quality**\n   - Test code map, file targets, test plan, sequencing, or alignment with design\n   - **Forbidden**: section numbers, verbatim headings, trivia answerable without reading plan substance\n\n   **Task question quality**\n   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design/plan\n   - **Forbidden**: task numbers, checklist order, \"which task says X verbatim\", or answers identifiable only by task index or checkbox position\n   - Good: \"What is the primary file where quiz rules are centralized?\" (answer from task substance)\n   - Bad: \"Which task number updates `comprehension-guidance.ts`?\" or \"What is the exact text of task 2.1?\"\n\n   **Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)\n\n   **On failure (score below threshold)**\n   - Announce score and that a new quiz is required\n   - Update `.comprehension-session.yaml` in the change dir with `used_sources` from this attempt\n   - Generate a NEW question set using different proposal/design/spec/plan/task sources (avoid `used_sources`)\n   - Retry until pass\n\n   **On pass**\n   ```bash\n   openspec instructions apply --change \"<name>\" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json\n   ```\n   - Re-run `openspec instructions apply --change \"<name>\" --json`\n   - Confirm `state` is `\"ready\"` and `comprehension.passed` is true before continuing\n\n   **Output template**\n   ```\n   ## Applying: <change-name> \u2014 comprehension check\n\n   plan\u00D7N, specs\u00D7N, design\u00D7N, proposal\u00D7N, tasks\u00D7N \u2192 <questionCount> questions (3 options each)\n\n   Question 1/N: ...\n   ...\n   \u2713 Comprehension passed (<score>%, attempt <n>)\n   ```\n\n   Then continue to step 5 (show progress) and implementation.";
 export declare const COMPREHENSION_APPLY_GUARDRAIL = "- NEVER implement code or mark tasks while `missingComprehension` is true\n- NEVER skip the comprehension quiz when the apply JSON requires it\n- NEVER answer comprehension quiz questions yourself \u2014 the human developer must answer every question\n- NEVER call `--record-comprehension-pass` until the user has answered every question\n- If the user asks to skip the quiz, refuse and explain they must pass or set comprehension.enabled: false in openspec/config.yaml";
 //# sourceMappingURL=comprehension-guidance.d.ts.map

package/dist/core/templates/workflows/comprehension-guidance.js

@@ -11,22 +11,27 @@ export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required be
 
    - If \`missingComprehension\` is true OR \`comprehension.required && !comprehension.passed\`:
      - Do NOT edit application source code or mark task checkboxes yet
-     - Read \`contextFiles.proposal\`, \`contextFiles.design\`, \`contextFiles.specs\`, and \`contextFiles.tasks\` (or the \`tasks\` array in apply JSON)
-     - Use \`comprehension.questionCount\` from the JSON as the number of questions
+     - Read \`contextFiles.proposal\`, \`contextFiles.design\`, \`contextFiles.specs\`, \`contextFiles.plan\`, and \`contextFiles.tasks\` (or the \`tasks\` array in apply JSON)
+     - Use \`comprehension.questionCount\` and \`comprehension.questionAllocation\` from the JSON
 
    **Generate questions**
    - Create exactly \`comprehension.questionCount\` multiple-choice questions
-   - Each question MUST map to one artifact category:
+   - **Follow \`comprehension.questionAllocation\`** — generate the exact count per category (e.g. plan×4, specs×1); do not invent your own split
+   - Each question maps to one artifact category:
      - **Proposal**: motivation, scope, or impact from \`proposal.md\`
      - **Design**: decisions, trade-offs, or approach from \`design.md\`
      - **Specs**: a \`### Requirement:\` or \`#### Scenario:\` from delta specs
-     - **Tasks**: conceptual understanding of the implementation plan from pending (unchecked) tasks
-   - When proposal, design, specs (with requirements), and pending tasks all exist, include at least one question from each category; fill remaining slots from any category
+     - **Plan**: code map, file targets, test plan, sequencing, or alignment with design from \`plan.md\`
+     - **Tasks**: conceptual understanding of the implementation approach from pending (unchecked) tasks
    - Do NOT use completed tasks as question sources
-   - Each question: 4 options (1 correct from the source substance, 3 plausible distractors from other proposal/design/requirements/scenarios/task substance in the change)
+   - Each question: **3 options** (\`comprehension.optionsPerQuestion\`, default 3) — 1 correct from source substance, 2 plausible distractors from other proposal/design/spec/plan/task substance in the change
+
+   **Plan question quality**
+   - Test code map, file targets, test plan, sequencing, or alignment with design
+   - **Forbidden**: section numbers, verbatim headings, trivia answerable without reading plan substance
 
    **Task question quality**
-   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design
+   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design/plan
    - **Forbidden**: task numbers, checklist order, "which task says X verbatim", or answers identifiable only by task index or checkbox position
    - Good: "What is the primary file where quiz rules are centralized?" (answer from task substance)
    - Bad: "Which task number updates \`comprehension-guidance.ts\`?" or "What is the exact text of task 2.1?"
@@ -36,7 +41,7 @@ export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required be
    **On failure (score below threshold)**
    - Announce score and that a new quiz is required
    - Update \`.comprehension-session.yaml\` in the change dir with \`used_sources\` from this attempt
-   - Generate a NEW question set using different proposal/design/requirement/scenario/task sources (avoid \`used_sources\`)
+   - Generate a NEW question set using different proposal/design/spec/plan/task sources (avoid \`used_sources\`)
    - Retry until pass
 
    **On pass**
@@ -50,7 +55,7 @@ export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required be
    \`\`\`
    ## Applying: <change-name> — comprehension check
 
-   Proposal, design, specs (<requirementCount> requirements, <scenarioCount> scenarios), tasks (<pendingTaskCount> pending) → <questionCount> questions
+   plan×N, specs×N, design×N, proposal×N, tasks×N → <questionCount> questions (3 options each)
 
    Question 1/N: ...
    ...

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

@@ -95,7 +95,7 @@ The artifact types and their purpose depend on the schema. Use the \`instruction
 
 Common artifact patterns:
 
-**spec-driven schema** (proposal → specs → design → tasks):
+**spec-driven schema** (proposal → specs → design → plan → tasks):
 - **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
   - The Capabilities section is critical - each capability listed will need a spec file.
 - **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
@@ -216,7 +216,7 @@ The artifact types and their purpose depend on the schema. Use the \`instruction
 
 Common artifact patterns:
 
-**spec-driven schema** (proposal → specs → design → tasks):
+**spec-driven schema** (proposal → specs → design → plan → tasks):
 - **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
   - The Capabilities section is critical - each capability listed will need a spec file.
 - **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).

package/dist/core/templates/workflows/onboard.js

@@ -47,7 +47,7 @@ I'll walk you through a complete change cycle—from idea to implementation—us
 1. Pick a small, real task in your codebase
 2. Explore the problem briefly
 3. Create a change (the container for our work)
-4. Build the artifacts: proposal → specs → design → tasks
+4. Build the artifacts: proposal → specs → design → plan → tasks
 5. Implement the tasks
 6. Archive the completed change
 
@@ -170,7 +170,7 @@ Now let's create a change to hold our work.
 \`\`\`
 ## Creating a Change
 
-A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the \`changeRoot\` reported by \`openspec status --change "<name>" --json\` and holds your artifacts—proposal, specs, design, tasks.
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the \`changeRoot\` reported by \`openspec status --change "<name>" --json\` and holds your artifacts—proposal, specs, design, plan, tasks.
 
 Let me create one for our task.
 \`\`\`

package/dist/core/templates/workflows/propose.js

@@ -4,12 +4,13 @@ import { PROMPT_CLARIFY, PROMPT_OPEN_ENDED } from './user-prompt-guidance.js';
 export function getOpsxProposeSkillTemplate() {
     return {
         name: 'openspec-propose',
-        description: 'Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.',
+        description: 'Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, plan, and tasks ready for implementation.',
         instructions: `Propose a new change - create the change and generate all artifacts in one step.
 
 I'll create a change with artifacts:
 - proposal.md (what & why)
 - design.md (how)
+- plan.md (file-level implementation plan)
 - tasks.md (implementation steps)
 
 When ready to implement, run /opsx:apply
@@ -125,6 +126,7 @@ export function getOpsxProposeCommandTemplate() {
 I'll create a change with artifacts:
 - proposal.md (what & why)
 - design.md (how)
+- plan.md (file-level implementation plan)
 - tasks.md (implementation steps)
 
 When ready to implement, run /opsx:apply

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codewalla_india/openspec",
-  "version": "1.0.04",
+  "version": "1.0.05",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

package/schemas/spec-driven/schema.yaml

@@ -1,6 +1,6 @@
 name: spec-driven
 version: 1
-description: Default OpenSpec workflow - proposal → specs → design → tasks
+description: Default OpenSpec workflow - proposal → specs → design → plan → tasks
 artifacts:
   - id: proposal
     generates: proposal.md
@@ -24,7 +24,7 @@ artifacts:
       Keep it concise (1-2 pages). Focus on the "why" not the "how" -
       implementation details belong in design.md.
 
-      This is the foundation - specs, design, and tasks all build on this.
+      This is the foundation - specs, design, plan, and tasks all build on this.
     requires: []
 
   - id: specs
@@ -110,6 +110,26 @@ artifacts:
     requires:
       - proposal
 
+  - id: plan
+    generates: plan.md
+    description: File-level implementation plan with code map
+    template: plan.md
+    instruction: |
+      Create a concrete implementation plan from design and specs.
+
+      Sections:
+      - **Code map**: Files to create, modify, or delete
+      - **Implementation order**: Sequenced steps at file/module level
+      - **Test plan**: How to verify the change
+      - **Risks**: Known risks with mitigations ([Risk] → Mitigation)
+      - **Done definition**: Objective criteria for completion
+
+      Do NOT restate behavioral requirements — link to specs.
+      Do NOT duplicate design decisions — reference design.md.
+    requires:
+      - specs
+      - design
+
   - id: tasks
     generates: tasks.md
     description: Implementation checklist with trackable tasks
@@ -139,14 +159,17 @@ artifacts:
       - [ ] 2.2 Add CSV formatting utilities
       ```
 
-      Reference specs for what needs to be built, design for how to build it.
+      Derive tasks from plan.md code map. Reference specs for what to build,
+      design for architectural decisions, and plan for file-level targets.
+      Include file/module references where helpful.
       Each task should be verifiable - you know when it's done.
     requires:
       - specs
       - design
+      - plan
 
 apply:
-  requires: [tasks]
+  requires: [plan, tasks]
   tracks: tasks.md
   instruction: |
     Read context files, work through pending tasks, mark complete as you go.

package/schemas/spec-driven/templates/plan.md

@@ -0,0 +1,19 @@
+## Code Map
+
+<!-- files to create/modify/delete -->
+
+## Implementation Order
+
+<!-- sequenced steps at file/module level -->
+
+## Test Plan
+
+<!-- how to verify -->
+
+## Risks
+
+<!-- [Risk] → Mitigation -->
+
+## Done Definition
+
+<!-- objective completion criteria -->