@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/core/comprehension/index.js

@@ -1,87 +0,0 @@
-import { resolveComprehensionConfig } from './config.js';
-import { fingerprintApplyArtifacts } from './fingerprint.js';
-import { buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
-import { computeSpecStats, OPTIONS_PER_QUESTION, } from './stats.js';
-export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, } from './config.js';
-export { fingerprintApplyArtifacts, fingerprintSpecFiles } from './fingerprint.js';
-export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
-export { computeQuestionAllocation, computeQuestionCount, computeSpecStats, countSpecStats, OPTIONS_PER_QUESTION, } from './stats.js';
-/**
- * Evaluate whether apply is blocked by the comprehension gate.
- */
-export function checkComprehensionGate(changeDir, specPaths, projectConfig, gateOptions = {}) {
-    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, artifactPresence);
-    if (stats.requirementCount === 0) {
-        return { active: false, passed: true };
-    }
-    const fingerprint = fingerprintApplyArtifacts({ specPaths, tasksPath, planPath });
-    const record = readPassRecord(changeDir);
-    const passed = isPassValid(record, fingerprint);
-    const info = {
-        required: true,
-        passed,
-        thresholdPercent: config.thresholdPercent,
-        questionCount: stats.questionCount,
-        questionAllocation: stats.questionAllocation,
-        optionsPerQuestion: stats.optionsPerQuestion,
-        requirementCount: stats.requirementCount,
-        scenarioCount: stats.scenarioCount,
-        pendingTaskCount: stats.pendingTaskCount,
-        ...(record && !passed
-            ? { bestScorePercent: record.score_percent, attempts: record.attempt }
-            : record && passed
-                ? { attempts: record.attempt }
-                : {}),
-    };
-    return { active: true, passed, info };
-}
-export class ComprehensionPassError extends Error {
-    score;
-    threshold;
-    constructor(message, score, threshold) {
-        super(message);
-        this.score = score;
-        this.threshold = threshold;
-        this.name = 'ComprehensionPassError';
-    }
-}
-/**
- * Record a comprehension pass after quiz success.
- */
-export function recordComprehensionPass(input) {
-    const config = resolveComprehensionConfig(input.projectConfig);
-    if (input.scorePercent < config.thresholdPercent) {
-        throw new ComprehensionPassError(`Score ${input.scorePercent}% is below the ${config.thresholdPercent}% threshold required to apply.`, input.scorePercent, config.thresholdPercent);
-    }
-    const stats = input.questionCount > 0
-        ? { questionCount: input.questionCount }
-        : 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,
-        attempt: input.attempt,
-        questionCount: stats.questionCount,
-        specFingerprint: fingerprint,
-    });
-    writePassRecord(input.changeDir, record);
-    deleteSessionRecord(input.changeDir);
-    return record;
-}
-export { OPTIONS_PER_QUESTION as comprehensionOptionsPerQuestion };
-//# sourceMappingURL=index.js.map

package/dist/core/comprehension/pass-record.d.ts

@@ -1,29 +0,0 @@
-import { z } from 'zod';
-export declare const COMPREHENSION_PASS_FILENAME = ".comprehension-pass.yaml";
-export declare const COMPREHENSION_SESSION_FILENAME = ".comprehension-session.yaml";
-declare const PassRecordSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    passed: z.ZodLiteral<true>;
-    score_percent: z.ZodNumber;
-    threshold_percent: z.ZodNumber;
-    attempt: z.ZodNumber;
-    question_count: z.ZodNumber;
-    spec_fingerprint: z.ZodString;
-    passed_at: z.ZodString;
-}, z.core.$strip>;
-export type ComprehensionPassRecord = z.infer<typeof PassRecordSchema>;
-export declare function passRecordPath(changeDir: string): string;
-export declare function sessionRecordPath(changeDir: string): string;
-export declare function readPassRecord(changeDir: string): ComprehensionPassRecord | null;
-export declare function writePassRecord(changeDir: string, record: ComprehensionPassRecord): void;
-export declare function deleteSessionRecord(changeDir: string): void;
-export declare function isPassValid(record: ComprehensionPassRecord | null, currentFingerprint: string): boolean;
-export declare function buildPassRecord(input: {
-    scorePercent: number;
-    thresholdPercent: number;
-    attempt: number;
-    questionCount: number;
-    specFingerprint: string;
-}): ComprehensionPassRecord;
-export {};
-//# sourceMappingURL=pass-record.d.ts.map

package/dist/core/comprehension/pass-record.js

@@ -1,64 +0,0 @@
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { z } from 'zod';
-export const COMPREHENSION_PASS_FILENAME = '.comprehension-pass.yaml';
-export const COMPREHENSION_SESSION_FILENAME = '.comprehension-session.yaml';
-const PassRecordSchema = z.object({
-    version: z.literal(1),
-    passed: z.literal(true),
-    score_percent: z.number().int().min(0).max(100),
-    threshold_percent: z.number().int().min(0).max(100),
-    attempt: z.number().int().positive(),
-    question_count: z.number().int().positive(),
-    spec_fingerprint: z.string().min(1),
-    passed_at: z.string().min(1),
-});
-export function passRecordPath(changeDir) {
-    return path.join(changeDir, COMPREHENSION_PASS_FILENAME);
-}
-export function sessionRecordPath(changeDir) {
-    return path.join(changeDir, COMPREHENSION_SESSION_FILENAME);
-}
-export function readPassRecord(changeDir) {
-    const filePath = passRecordPath(changeDir);
-    if (!existsSync(filePath)) {
-        return null;
-    }
-    try {
-        const parsed = parseYaml(readFileSync(filePath, 'utf-8'));
-        const result = PassRecordSchema.safeParse(parsed);
-        return result.success ? result.data : null;
-    }
-    catch {
-        return null;
-    }
-}
-export function writePassRecord(changeDir, record) {
-    writeFileSync(passRecordPath(changeDir), stringifyYaml(record), 'utf-8');
-}
-export function deleteSessionRecord(changeDir) {
-    const filePath = sessionRecordPath(changeDir);
-    if (existsSync(filePath)) {
-        unlinkSync(filePath);
-    }
-}
-export function isPassValid(record, currentFingerprint) {
-    if (!record?.passed) {
-        return false;
-    }
-    return record.spec_fingerprint === currentFingerprint;
-}
-export function buildPassRecord(input) {
-    return {
-        version: 1,
-        passed: true,
-        score_percent: input.scorePercent,
-        threshold_percent: input.thresholdPercent,
-        attempt: input.attempt,
-        question_count: input.questionCount,
-        spec_fingerprint: input.specFingerprint,
-        passed_at: new Date().toISOString(),
-    };
-}
-//# sourceMappingURL=pass-record.js.map

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

@@ -1,35 +0,0 @@
-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.
- */
-export declare function countSpecStats(specPaths: string[]): Pick<SpecStats, 'requirementCount' | 'scenarioCount'>;
-/**
- * Target quiz length from spec and task size:
- * 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, presence?: ArtifactPresence): SpecStats;
-//# sourceMappingURL=stats.d.ts.map

package/dist/core/comprehension/stats.js

@@ -1,133 +0,0 @@
-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;
-}
-/**
- * Count requirements and scenarios across delta spec files.
- */
-export function countSpecStats(specPaths) {
-    let requirementCount = 0;
-    let scenarioCount = 0;
-    for (const specPath of specPaths) {
-        const content = readFileSync(specPath, 'utf-8');
-        const plan = parseDeltaSpec(content);
-        const blocks = [...plan.added, ...plan.modified];
-        requirementCount += blocks.length;
-        for (const block of blocks) {
-            scenarioCount += countScenariosInBlock(block.raw);
-        }
-    }
-    return { requirementCount, scenarioCount };
-}
-function clamp(min, max, value) {
-    return Math.min(max, Math.max(min, value));
-}
-/**
- * Target quiz length from spec and task size:
- * clamp(min, max, round(req * 0.6 + scenarios * 0.15 + pendingTasks * 0.15)).
- */
-export function computeQuestionCount(requirementCount, scenarioCount, pendingTaskCount, config) {
-    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, presence = {}) {
-    const { requirementCount, scenarioCount } = countSpecStats(specPaths);
-    const questionCount = computeQuestionCount(requirementCount, scenarioCount, pendingTaskCount, config);
-    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/comprehension-guidance.d.ts

@@ -1,9 +0,0 @@
-/**
- * Comprehension quiz guidance for apply workflows.
- *
- * 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`, `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

@@ -1,71 +0,0 @@
-/**
- * Comprehension quiz guidance for apply workflows.
- *
- * Interpolated into apply skill and slash command templates so agents run
- * a spec comprehension gate before implementation.
- */
-import { COMPREHENSION_PRESENT_AND_GRADE } from './user-prompt-guidance.js';
-export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required before implementation)**
-
-   After \`openspec instructions apply --change "<name>" --json\`, check comprehension status:
-
-   - 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\`, \`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
-   - **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
-     - **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: **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/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?"
-
-   ${COMPREHENSION_PRESENT_AND_GRADE}
-
-   **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/spec/plan/task sources (avoid \`used_sources\`)
-   - Retry until pass
-
-   **On pass**
-   \`\`\`bash
-   openspec instructions apply --change "<name>" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json
-   \`\`\`
-   - Re-run \`openspec instructions apply --change "<name>" --json\`
-   - Confirm \`state\` is \`"ready"\` and \`comprehension.passed\` is true before continuing
-
-   **Output template**
-   \`\`\`
-   ## Applying: <change-name> — comprehension check
-
-   plan×N, specs×N, design×N, proposal×N, tasks×N → <questionCount> questions (3 options each)
-
-   Question 1/N: ...
-   ...
-   ✓ Comprehension passed (<score>%, attempt <n>)
-   \`\`\`
-
-   Then continue to step 5 (show progress) and implementation.`;
-export const COMPREHENSION_APPLY_GUARDRAIL = `- NEVER implement code or mark tasks while \`missingComprehension\` is true
-- NEVER skip the comprehension quiz when the apply JSON requires it
-- NEVER answer comprehension quiz questions yourself — the human developer must answer every question
-- NEVER call \`--record-comprehension-pass\` until the user has answered every question
-- 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.js.map

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

@@ -1,13 +0,0 @@
-/**
- * Shared MCP guidance for Codewalla workflow templates.
- *
- * Interpolated into propose, apply, and verify workflows so generated
- * skills and slash commands consistently teach when to use Atlassian, Context7,
- * 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   **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).";
-//# sourceMappingURL=mcp-guidance.d.ts.map

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

@@ -1,131 +0,0 @@
-/**
- * Shared MCP guidance for Codewalla workflow templates.
- *
- * Interpolated into propose, apply, and verify workflows so generated
- * skills and slash commands consistently teach when to use Atlassian, Context7,
- * and Playwright MCP tools.
- */
-export const ATLASSIAN_ENRICHMENT_GUIDANCE = `3.5. **Enrich from Jira (if ticket key available)**
-
-   Scan the change name, proposal.md, and design.md for a Jira issue key
-   (pattern: one or more capital letters, a dash, one or more digits — e.g., CW-123, PROJ-456).
-
-   If a ticket key is found, use the **Atlassian MCP**:
-
-   **a. Fetch the issue**
-   - Retrieve: summary, description, issue type, status, labels
-   - Extract any "Acceptance Criteria" section from the description
-   - Note the assignee and reporter
-
-   **b. Walk the parent hierarchy**
-   - If the issue has a parent (sub-task → story, or story → epic):
-     - Fetch the parent ticket for business goal context
-     - If parent has a parent (epic), fetch that too for initiative framing
-     - Note the full path: Initiative → Epic → Story → Sub-task
-
-   **c. Fetch recent comments**
-   - Get comments, ordered by date
-   - Look for scope reduction ("out of scope", "defer X"), changed approach,
-     blocker resolutions, or QA/review feedback added after planning
-
-   **d. Cross-check against tasks.md**
-   - For each acceptance criterion in Jira: verify at least one task covers it
-   - If an AC has no corresponding task → add it to the flagged list
-   - For any comment that changed scope post-planning → note the discrepancy
-
-   **Output:** Print a "Jira Context" section showing:
-   - Ticket key + summary, type, status
-   - Parent chain (if any)
-   - ACs: covered ✓ / not covered ✗
-   - Scope-change comments (if any, with date)
-   - "Proceeding with implementation" or "⚠ Pausing — scope mismatch found, confirm before continuing"
-
-   **If no ticket key found or Atlassian MCP unavailable:** Skip silently and continue.`;
-export const ATLASSIAN_PROPOSE_GUIDANCE = `0. **Import from Jira (if a ticket key is provided)**
-
-   If the user's input contains or is a Jira issue key (e.g., "CW-1234" or "CW-1234 add dark mode"):
-
-   Use the **Atlassian MCP** to fetch the issue:
-   - summary → becomes the change name candidate (kebab-case it)
-   - description → seed for proposal.md "Why" and "What Changes" sections
-   - acceptance criteria → seed for specs artifact requirements
-   - parent epic → context for the "Impact" section of the proposal
-
-   Walk the parent chain:
-   - Fetch the epic (or story parent) for business-level framing
-   - Include the epic goal as opening context in the proposal
-
-   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:**
-
-   If the task description references a specific library, framework, or package
-   (e.g., "implement with Prisma", "add React Query cache", "use Drizzle ORM transactions",
-   "migrate to Next.js App Router", "use tRPC v11 procedure"):
-
-   1. Call \`resolve-library-id\` (Context7 MCP) with the library name to get its Context7 ID
-   2. Call \`query-docs\` with the Context7 ID and the specific question from the task
-      — e.g., "How to use transactions with Drizzle ORM 0.38?"
-   3. Use the returned documentation to guide the implementation
-
-   **When to trigger this check:**
-   - Task mentions a package by name
-   - Task uses version-specific language ("v5 API", "new hook syntax")
-   - Task involves migration between library versions
-   - The codebase's package.json shows a recently updated dependency relevant to the task
-
-   **When to skip:**
-   - Task is purely business logic (no library API involved)
-   - You already fetched docs for this library in a previous task this session
-     (reuse the earlier result, don't call again)
-
-   **Cap:** Do not call Context7 more than 3 times per apply session.`;
-export 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 — do not do it inline during apply`;
-export const PLAYWRIGHT_VERIFY_GUIDANCE = `8. **Browser verification (Playwright)**
-
-   After codebase analysis (steps 5–7), assess if the change touches UI or web pages:
-   - proposal.md or tasks.md mentions pages, components, screens, UI, CSS, visual, layout
-
-   **If yes, use the Playwright MCP:**
-
-   **a. Check for a running dev server**
-   - Scan package.json \`scripts\` for: \`dev\`, \`start\`, \`preview\`, \`serve\`
-   - Check if localhost is reachable (common ports: 3000, 3001, 5173, 8080)
-   - If a URL is available, announce it. If not, note "No dev server detected — skipping visual verification."
-
-   **b. If dev server is reachable:**
-   - Use \`browser_navigate\` to open the affected page(s) identified from the change
-   - Use \`browser_take_screenshot\` to capture the current visual state
-   - Use \`browser_snapshot\` to get the accessibility tree and verify key elements
-   - Use \`browser_console_messages\` to check for JS errors introduced by this change
-   - If network requests are relevant: \`browser_network_requests\` to spot regressions
-
-   **c. Playwright test files**
-   Search the project for:
-   - \`**/*.spec.ts\`, \`**/*.e2e.ts\`, \`**/playwright/**/*.ts\`, \`**/e2e/**/*.ts\`
-   If test files related to the changed pages/components are found:
-   - List them
-   - If the user asks you to run them, execute and report pass/fail inline
-
-   **If no dev server is reachable:**
-   Add a SUGGESTION to the report: "Start dev server and re-run /opsx:verify for visual confirmation."
-
-   Include browser results in the verification report (step 9).`;
-//# sourceMappingURL=mcp-guidance.js.map

package/dist/core/templates/workflows/user-prompt-guidance.d.ts

@@ -1,16 +0,0 @@
-/**
- * Tool-agnostic user interaction guidance for agent workflows.
- *
- * Cursor's AskUserQuestion is an optional enhancement, not a requirement.
- * All editors (Windsurf, Claude Code, etc.) use plain chat with stop-and-wait.
- */
-export declare const PROMPT_SELECT_CHANGE = "Prompt the user to select a change:\n   - Run `openspec list --json` to get available changes\n   - Present the options clearly in chat (numbered or labeled)\n   - Ask ONE selection question; STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
-export declare const PROMPT_SELECT_CHANGE_RECENT = "Run `openspec list --json` to get available changes sorted by most recently modified. Then prompt the user to select which change to work on in chat. Ask ONE selection question; STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
-export declare const PROMPT_MULTI_SELECT_CHANGES = "Prompt the user to select one or more changes in chat:\n   - Show each change with its schema\n   - Allow multiple selections (e.g., \"select all that apply\" or comma-separated names)\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
-export declare const PROMPT_CONFIRM = "Ask the user to confirm before proceeding in chat:\n   - State what they are confirming and the consequences\n   - Present clear yes/no options\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
-export declare const PROMPT_OPEN_ENDED = "Ask the user an open-ended question in chat (no preset multiple-choice options):\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
-export declare const PROMPT_CLARIFY = "Ask the user a clarifying question in chat:\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
-export declare const COMPREHENSION_PRESENT_AND_GRADE = "**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)";
-export declare const TELEMETRY_WORKFLOW_INPUT_GUIDANCE = "**Telemetry**: When running `openspec new change`, ALWAYS pass:\n   - `--workflow-input \"<user request verbatim>\"` \u2014 slash-command args or the user's open-ended answer\n   - `--editor <cursor|windsurf|claude>` \u2014 the AI tool you are running in\n   - For long or heavily quoted text, write a temp file and use `--workflow-input-file <path>` instead";
-export declare const TELEMETRY_MODIFY_GUIDANCE = "**Telemetry**: When running `openspec instructions modify`, ALWAYS pass:\n   - `--artifact <id>` \u2014 the source artifact being modified\n   - `--workflow-input \"<user request verbatim>\"` \u2014 the user's modify request\n   - `--editor <cursor|windsurf|claude>` \u2014 the AI tool you are running in\n   - For long or heavily quoted text, use `--workflow-input-file <path>` instead";
-//# sourceMappingURL=user-prompt-guidance.d.ts.map