@codewalla_india/openspec 1.0.4 → 1.0.6

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/mcp-guidance.d.ts

@@ -6,7 +6,7 @@
  * and Playwright MCP tools.
  */
 export declare const ATLASSIAN_ENRICHMENT_GUIDANCE = "3.5. **Enrich from Jira (if ticket key available)**\n\n   Scan the change name, proposal.md, and design.md for a Jira issue key\n   (pattern: one or more capital letters, a dash, one or more digits \u2014 e.g., CW-123, PROJ-456).\n\n   If a ticket key is found, use the **Atlassian MCP**:\n\n   **a. Fetch the issue**\n   - Retrieve: summary, description, issue type, status, labels\n   - Extract any \"Acceptance Criteria\" section from the description\n   - Note the assignee and reporter\n\n   **b. Walk the parent hierarchy**\n   - If the issue has a parent (sub-task \u2192 story, or story \u2192 epic):\n     - Fetch the parent ticket for business goal context\n     - If parent has a parent (epic), fetch that too for initiative framing\n     - Note the full path: Initiative \u2192 Epic \u2192 Story \u2192 Sub-task\n\n   **c. Fetch recent comments**\n   - Get comments, ordered by date\n   - Look for scope reduction (\"out of scope\", \"defer X\"), changed approach,\n     blocker resolutions, or QA/review feedback added after planning\n\n   **d. Cross-check against tasks.md**\n   - For each acceptance criterion in Jira: verify at least one task covers it\n   - If an AC has no corresponding task \u2192 add it to the flagged list\n   - For any comment that changed scope post-planning \u2192 note the discrepancy\n\n   **Output:** Print a \"Jira Context\" section showing:\n   - Ticket key + summary, type, status\n   - Parent chain (if any)\n   - ACs: covered \u2713 / not covered \u2717\n   - Scope-change comments (if any, with date)\n   - \"Proceeding with implementation\" or \"\u26A0 Pausing \u2014 scope mismatch found, confirm before continuing\"\n\n   **If no ticket key found or Atlassian MCP unavailable:** Skip silently and continue.";
-export declare const ATLASSIAN_PROPOSE_GUIDANCE = "0. **Import from Jira (if a ticket key is provided)**\n\n   If the user's input contains or is a Jira issue key (e.g., \"CW-1234\" or \"CW-1234 add dark mode\"):\n\n   Use the **Atlassian MCP** to fetch the issue:\n   - summary \u2192 becomes the change name candidate (kebab-case it)\n   - description \u2192 seed for proposal.md \"Why\" and \"What Changes\" sections\n   - acceptance criteria \u2192 seed for specs artifact requirements\n   - parent epic \u2192 context for the \"Impact\" section of the proposal\n\n   Walk the parent chain:\n   - Fetch the epic (or story parent) for business-level framing\n   - Include the epic goal as opening context in the proposal\n\n   After fetching, proceed to step 1 using the ticket data as pre-filled input.\n   Tell the user: \"Found CW-1234: '<summary>'. Creating change from Jira ticket.\"\n\n   **If no ticket key:** proceed normally from step 1.";
+export declare const ATLASSIAN_PROPOSE_GUIDANCE = "0. **Import from Jira (if a ticket key is provided)**\n\n   If the user's input contains or is a Jira issue key (e.g., \"CW-1234\" or \"CW-1234 add dark mode\"):\n\n   Use the **Atlassian MCP** to fetch the issue:\n   - summary \u2192 becomes the change name candidate (kebab-case it)\n   - description \u2192 seed for proposal.md \"Why\" and \"What Changes\" sections\n   - acceptance criteria \u2192 seed for specs artifact requirements\n   - parent epic \u2192 context for the \"Impact\" section of the proposal\n\n   Walk the parent chain:\n   - Fetch the epic (or story parent) for business-level framing\n   - Include the epic goal as opening context in the proposal\n\n   After fetching, proceed to step 1 using the ticket data as pre-filled input.\n   Tell the user: \"Found CW-1234: '<summary>'. Creating change from Jira ticket.\"\n\n   **Naming conventions** (Jira tracks work; specs track behavior):\n\n   - **Change name**: kebab-case summary; optionally prefix with lowercase ticket key\n     (e.g., `cw-1234-add-dark-mode`). Never use the ticket key alone as the change name.\n   - **Capabilities** (proposal + delta specs): pick domain names from existing\n     `openspec/specs/` or derive from behavior (`ui`, `auth`). **Do NOT** name\n     capabilities or spec folders after the Jira key.\n   - **Acceptance criteria**: map each AC to requirements/scenarios inside the\n     appropriate capability spec\u2014not to a ticket-named spec file.\n   - **Traceability**: record ticket key(s) in proposal **Impact**\n     (e.g., `Jira: CW-1234` or `Jira: CW-100 (epic), CW-1234 (story)`).\n   - **Follow-up work**: when continuing or splitting ticket work, create a new change\n     folder with a distinct name; reference the same or related tickets in Impact.\n     Do not reuse archived change folders or ticket-key spec folders.\n\n   **If no ticket key:** proceed normally from step 1.";
 export declare const CONTEXT7_LOOKUP_GUIDANCE = "   **Before implementing each task \u2014 library check:**\n\n   If the task description references a specific library, framework, or package\n   (e.g., \"implement with Prisma\", \"add React Query cache\", \"use Drizzle ORM transactions\",\n   \"migrate to Next.js App Router\", \"use tRPC v11 procedure\"):\n\n   1. Call `resolve-library-id` (Context7 MCP) with the library name to get its Context7 ID\n   2. Call `query-docs` with the Context7 ID and the specific question from the task\n      \u2014 e.g., \"How to use transactions with Drizzle ORM 0.38?\"\n   3. Use the returned documentation to guide the implementation\n\n   **When to trigger this check:**\n   - Task mentions a package by name\n   - Task uses version-specific language (\"v5 API\", \"new hook syntax\")\n   - Task involves migration between library versions\n   - The codebase's package.json shows a recently updated dependency relevant to the task\n\n   **When to skip:**\n   - Task is purely business logic (no library API involved)\n   - You already fetched docs for this library in a previous task this session\n     (reuse the earlier result, don't call again)\n\n   **Cap:** Do not call Context7 more than 3 times per apply session.";
 export declare const PLAYWRIGHT_APPLY_GUARDRAIL = "- Do NOT run Playwright or browser tests during apply. If the user explicitly asks to also \"run tests\", \"verify UI\", or \"check in browser\" in the same message, complete all tasks first, then invoke openspec-verify-change (or `/opsx:verify`) to handle browser verification \u2014 do not do it inline during apply";
 export declare const PLAYWRIGHT_VERIFY_GUIDANCE = "8. **Browser verification (Playwright)**\n\n   After codebase analysis (steps 5\u20137), assess if the change touches UI or web pages:\n   - proposal.md or tasks.md mentions pages, components, screens, UI, CSS, visual, layout\n\n   **If yes, use the Playwright MCP:**\n\n   **a. Check for a running dev server**\n   - Scan package.json `scripts` for: `dev`, `start`, `preview`, `serve`\n   - Check if localhost is reachable (common ports: 3000, 3001, 5173, 8080)\n   - If a URL is available, announce it. If not, note \"No dev server detected \u2014 skipping visual verification.\"\n\n   **b. If dev server is reachable:**\n   - Use `browser_navigate` to open the affected page(s) identified from the change\n   - Use `browser_take_screenshot` to capture the current visual state\n   - Use `browser_snapshot` to get the accessibility tree and verify key elements\n   - Use `browser_console_messages` to check for JS errors introduced by this change\n   - If network requests are relevant: `browser_network_requests` to spot regressions\n\n   **c. Playwright test files**\n   Search the project for:\n   - `**/*.spec.ts`, `**/*.e2e.ts`, `**/playwright/**/*.ts`, `**/e2e/**/*.ts`\n   If test files related to the changed pages/components are found:\n   - List them\n   - If the user asks you to run them, execute and report pass/fail inline\n\n   **If no dev server is reachable:**\n   Add a SUGGESTION to the report: \"Start dev server and re-run /opsx:verify for visual confirmation.\"\n\n   Include browser results in the verification report (step 9).";

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

@@ -58,6 +58,21 @@ export const ATLASSIAN_PROPOSE_GUIDANCE = `0. **Import from Jira (if a ticket ke
    After fetching, proceed to step 1 using the ticket data as pre-filled input.
    Tell the user: "Found CW-1234: '<summary>'. Creating change from Jira ticket."
 
+   **Naming conventions** (Jira tracks work; specs track behavior):
+
+   - **Change name**: kebab-case summary; optionally prefix with lowercase ticket key
+     (e.g., \`cw-1234-add-dark-mode\`). Never use the ticket key alone as the change name.
+   - **Capabilities** (proposal + delta specs): pick domain names from existing
+     \`openspec/specs/\` or derive from behavior (\`ui\`, \`auth\`). **Do NOT** name
+     capabilities or spec folders after the Jira key.
+   - **Acceptance criteria**: map each AC to requirements/scenarios inside the
+     appropriate capability spec—not to a ticket-named spec file.
+   - **Traceability**: record ticket key(s) in proposal **Impact**
+     (e.g., \`Jira: CW-1234\` or \`Jira: CW-100 (epic), CW-1234 (story)\`).
+   - **Follow-up work**: when continuing or splitting ticket work, create a new change
+     folder with a distinct name; reference the same or related tickets in Impact.
+     Do not reuse archived change folders or ticket-key spec folders.
+
    **If no ticket key:** proceed normally from step 1.`;
 export const CONTEXT7_LOOKUP_GUIDANCE = `   **Before implementing each task — library check:**
 

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.6",
   "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
@@ -15,7 +15,12 @@ artifacts:
       - **Capabilities**: Identify which specs will be created or modified:
         - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
         - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
-      - **Impact**: Affected code, APIs, dependencies, or systems.
+      - **Impact**: Affected code, APIs, dependencies, or systems. If importing from
+        Jira, record ticket key(s) here (e.g., `Jira: CW-1234`) for traceability.
+
+      When importing from Jira: name capabilities by behavioral domain (e.g., `ui`,
+      `user-auth`), not by ticket key. Reference the ticket in Impact, not in
+      capability names.
 
       IMPORTANT: The Capabilities section is critical. It creates the contract between
       proposal and specs phases. Research existing specs before filling this in.
@@ -24,7 +29,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
@@ -38,6 +43,9 @@ artifacts:
       - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
       - Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
 
+      When Jira acceptance criteria exist: translate them into requirements under the
+      capability folders listed in the proposal. Never create specs/<ticket-key>/.
+
       Delta operations (use ## headers):
       - **ADDED Requirements**: New capabilities
       - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
@@ -110,6 +118,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 +167,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 -->

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

@@ -21,3 +21,4 @@
 ## Impact
 
 <!-- Affected code, APIs, dependencies, systems -->
+<!-- If this change maps to a Jira ticket, note it here (e.g., Jira: CW-1234). Do NOT use the ticket key as a capability name. -->