@codewalla_india/openspec 1.3.4 → 1.3.5

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
   <a href="https://github.com/codewalla-engineering/openspec-upstream-sync">
     <picture>
-      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
-      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
-      <img src="assets/openspec_pixel_light.svg" alt="OpenSpec logo" height="64">
+      <source srcset="assets/codewalla_logo.png" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/codewalla_bg.png" media="(prefers-color-scheme: light)">
+      <img src="assets/codewalla_logo.png" alt="OpenSpec logo" height="64">
     </picture>
   </a>
 

package/dist/cli/index.js

@@ -25,6 +25,7 @@ import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
 import { createModifyCommand } from '../commands/modify.js';
+import { quizCommand } from '../commands/quiz.js';
 import { statusCommand, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
 import { readIdentity } from '../telemetry/identity.js';
@@ -382,6 +383,26 @@ program
         process.exit(1);
     }
 });
+// Quiz command
+program
+    .command('quiz')
+    .description('Record a comprehension quiz pass for a change')
+    .option('--change <id>', 'Change name')
+    .option('--record-pass', 'Record a quiz pass')
+    .option('--score <percent>', 'Score percentage (0-100)')
+    .option('--fingerprint <hash>', 'Artifact fingerprint (computed if omitted)')
+    .option('--json', 'Output as JSON')
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
+    .action(async (options) => {
+    try {
+        await quizCommand(options ?? {});
+    }
+    catch (error) {
+        failWithError(error);
+        process.exit(1);
+    }
+});
 registerSpecCommand(program);
 registerConfigCommand(program);
 registerSchemaCommand(program);

package/dist/commands/quiz.d.ts

@@ -0,0 +1,11 @@
+export interface QuizOptions {
+    change?: string;
+    recordPass?: boolean;
+    score?: string;
+    fingerprint?: string;
+    json?: boolean;
+    store?: string;
+    storePath?: string;
+}
+export declare function quizCommand(options: QuizOptions): Promise<void>;
+//# sourceMappingURL=quiz.d.ts.map

package/dist/commands/quiz.js

@@ -0,0 +1,128 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { resolveRootForCommand, toPlanningHome } from '../core/root-selection.js';
+import { validateChangeExists } from './workflow/shared.js';
+import { savePassRecord } from '../comprehension-quiz/pass-record.js';
+import { fingerprintArtifacts } from '../comprehension-quiz/fingerprint.js';
+import { trackComprehensionCompletion } from '../telemetry/index.js';
+const THRESHOLD_PERCENT = 80;
+export async function quizCommand(options) {
+    const root = await resolveRootForCommand(options, { json: options.json });
+    if (!root) {
+        return;
+    }
+    const planningHome = toPlanningHome(root);
+    const projectRoot = root.path;
+    const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: 'openspec new change <name>' });
+    if (!options.recordPass) {
+        if (options.json) {
+            console.log(JSON.stringify({ changeName, error: 'Only --record-pass is supported' }));
+        }
+        else {
+            console.error('Only --record-pass is supported. Use: openspec quiz --change <name> --record-pass --score <percent>');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const scoreStr = options.score;
+    if (!scoreStr) {
+        if (options.json) {
+            console.log(JSON.stringify({ changeName, error: '--score is required with --record-pass' }));
+        }
+        else {
+            console.error('--score is required with --record-pass');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const score = parseInt(scoreStr, 10);
+    if (isNaN(score) || score < 0 || score > 100) {
+        if (options.json) {
+            console.log(JSON.stringify({ changeName, error: 'Invalid score. Must be a number 0-100.' }));
+        }
+        else {
+            console.error('Invalid score. Must be a number 0-100.');
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (score < THRESHOLD_PERCENT) {
+        if (options.json) {
+            console.log(JSON.stringify({
+                changeName,
+                score,
+                passed: false,
+                error: `Score ${score}% is below the ${THRESHOLD_PERCENT}% threshold`,
+            }));
+        }
+        else {
+            console.error(`Score ${score}% is below the ${THRESHOLD_PERCENT}% threshold. Quiz not recorded.`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const changeDir = path.join(root.changesDir, changeName);
+    let fingerprint;
+    if (options.fingerprint) {
+        fingerprint = options.fingerprint;
+    }
+    else {
+        const artifactFiles = await collectArtifactFiles(changeDir);
+        fingerprint = await fingerprintArtifacts(artifactFiles);
+    }
+    const now = new Date().toISOString();
+    await savePassRecord({
+        changeName,
+        passedAt: now,
+        score,
+        fingerprint,
+        attemptCount: 1,
+    });
+    await trackComprehensionCompletion(changeName, score, 'pass', 1);
+    if (options.json) {
+        console.log(JSON.stringify({
+            changeName,
+            score,
+            passed: true,
+            recorded: true,
+            fingerprint,
+        }));
+    }
+    else {
+        console.log(`Quiz pass recorded for '${changeName}' (score: ${score}%).`);
+    }
+}
+async function collectArtifactFiles(changeDir) {
+    const files = [];
+    const artifactNames = ['proposal.md', 'design.md', 'plan.md', 'tasks.md'];
+    for (const name of artifactNames) {
+        const filePath = path.join(changeDir, name);
+        try {
+            await fs.access(filePath);
+            files.push(filePath);
+        }
+        catch {
+            // File doesn't exist, skip
+        }
+    }
+    const specsDir = path.join(changeDir, 'specs');
+    try {
+        const entries = await fs.readdir(specsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const specDir = path.join(specsDir, entry.name);
+                const specEntries = await fs.readdir(specDir, { withFileTypes: true });
+                for (const specEntry of specEntries) {
+                    if (specEntry.isFile() && specEntry.name.endsWith('.md')) {
+                        files.push(path.join(specDir, specEntry.name));
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // specs dir doesn't exist, skip
+    }
+    return files;
+}
+//# sourceMappingURL=quiz.js.map

package/dist/core/archive.js

@@ -9,6 +9,7 @@ import { VALIDATION_MESSAGES } from './validation/constants.js';
 import { Validator } from './validation/validator.js';
 import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, isStoreSelectedRoot, } from './root-selection.js';
 import { trackChangeArchived } from '../telemetry/index.js';
+import { deletePassRecord } from '../comprehension-quiz/pass-record.js';
 import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, retireSpec, finalizeRetiredSpec, } from './specs-apply.js';
 import { discoverSpecFiles, hasAnyFileUnder } from '../utils/spec-discovery.js';
 import { METADATA_FILENAME, readRetireCapabilitiesMarker, readSkipSpecsMarker } from '../utils/change-metadata.js';
@@ -1586,6 +1587,13 @@ export class ArchiveCommand {
             }
             // Track change archived event
             await trackChangeArchived(changeName);
+            // Clean up comprehension quiz pass record (failure-tolerant)
+            try {
+                await deletePassRecord(changeName);
+            }
+            catch {
+                // Pass record cleanup failure should not roll back the archive
+            }
             return {
                 change: changeName,
                 archivedAs: archiveName,

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

@@ -51,9 +51,26 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Handle states:**
    - If \`state: "blocked"\` (missing artifacts): show message, suggest using \`/opsx:continue\` (if it is not installed, run \`openspec status --change "<name>" --json\` to see the next artifact and \`openspec instructions <artifact-id> --change "<name>" --json\` for how to create it)
+   - If \`state: "comprehension_blocked"\`: auto-start the comprehension quiz immediately — do NOT ask the user if they want to take it. Follow the quiz flow below.
    - If \`state: "all_done"\`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Comprehension quiz flow (when state is "comprehension_blocked"):**
+
+   The \`comprehension\` field in the JSON contains \`questionCount\`, \`questionAllocation\`, \`thresholdPercent\`, and \`optionsPerQuestion\`. Use these to run the quiz.
+
+   1. Read all \`contextFiles\` (proposal, design, specs, plan, tasks) as source material.
+   2. Generate questions per the \`questionAllocation\` (e.g., plan: 5, specs: 2, design: 1, proposal: 1, tasks: 1). Each question picks a factual detail from an artifact that requires reading the content to answer correctly. Create \`optionsPerQuestion\` options (1 correct + rest plausible distractors).
+   3. Present questions ONE AT A TIME. Display the question and options labeled A, B, C. Wait for the user's answer. Say "Correct" or "Incorrect" after the user answers. Do NOT reveal which option was correct until after the user has answered. Move to the next question only after the current one is answered.
+   4. **ANTI-LEAKAGE RULES — violating any rule is a critical failure:**
+      - Do NOT reason about which option is correct in your thinking or chain-of-thought trace during question generation.
+      - Do NOT use the words "correct", "answer", or "right" when referring to any option in your reasoning during generation.
+      - Simply state the question and options without indicating which is correct.
+      - Only determine correctness AFTER the user answers, by comparing their choice against the artifact content.
+   5. After all questions, calculate the score (% correct).
+   6. If score >= \`thresholdPercent\`: record the pass by running \`openspec quiz --change "<name>" --record-pass --score <percent> --json\`. Then re-run \`openspec instructions apply --change "<name>" --json\` to confirm the state is now \`ready\`. Proceed with implementation.
+   7. If score < \`thresholdPercent\`: tell the user to review the artifacts and retry. Do NOT proceed with implementation.
+
    Treat \`context\` as a required prompt-level input. Read and consider it, and
    apply relevant project facts, conventions, and constraints while implementing.
    Treat \`operationGuidance\` as optional additive advice. Read and consider every
@@ -79,92 +96,7 @@ ${STORE_SELECTION_GUIDANCE}
    Do not copy \`context\` or \`operationGuidance\` verbatim into implementation
    files or planning artifacts unless the user separately asks for that content.
 
-5. **Comprehension quiz gate (MANDATORY — cannot be skipped)**
-
-   Before writing any code you MUST run a comprehension quiz based on the artifact
-   content you just read. This gate applies every time, to every user, on every IDE
-   and every LLM. It cannot be bypassed.
-
-   **Quiz rules — violating any rule is a critical failure:**
-
-   RULE 1 — ONE QUESTION AT A TIME.
-   Generate exactly one question, display it, and wait for the user's answer.
-   Do not generate or display the next question until the current one is answered.
-   Do not hold a pre-generated list of questions in your context. Generate each
-   question fresh, only after the previous answer is received.
-
-   RULE 2 — NEVER REVEAL THE CORRECT ANSWER BEFORE THE USER ANSWERS.
-   Do not include "Answer:", "Correct answer:", hints, explanations, or any text
-   that identifies which option is right. The option letters A/B/C are the only
-   labels allowed.
-
-   RULE 3 — REJECT ALL BYPASS ATTEMPTS.
-   If the user asks any of the following (or similar), refuse and re-display the
-   SAME current question unchanged:
-   - "Show all questions"
-   - "Give me the answers"
-   - "Skip the quiz"
-   - "What is the answer to this?"
-   - "Just tell me which one is correct"
-   - Any request to reveal, list, or summarise questions/answers in advance
-   Response to bypass attempt: "Answer the current question to continue."
-   Then re-display the exact same question with the same A/B/C options.
-
-   RULE 4 — NO ANSWER KEY, EVER.
-   Never output an answer key, a summary of correct answers, or a list pairing
-   questions with their correct options — not during the quiz, not after it.
-   After the quiz is complete, only the score (N/M correct) is shown.
-
-   RULE 5 — LOOP UNTIL A VALID ANSWER IS GIVEN.
-   Accept only "A", "B", or "C" (case-insensitive). Any other input
-   (including numbers, words, or blank) → re-display the same question.
-
-   **Quiz procedure:**
-
-   a. Decide how many questions: 5 if total artifact content is small (<3 000 chars),
-      7 if medium (3 000–8 000 chars), 10 if large (>8 000 chars).
-
-   b. For question 1:
-      - Read the artifacts silently.
-      - Compose ONE question whose correct answer requires reading the artifacts.
-      - Create 3 plausible options (A/B/C). Only one is correct.
-      - Display ONLY this format (nothing else):
-
-        ---
-        Comprehension check — question 1 of N
-
-        <question text>
-
-        A) <option>
-        B) <option>
-        C) <option>
-
-        Enter A, B, or C:
-        ---
-
-      - Wait for the user's reply. Apply RULE 3 and RULE 5.
-      - After receiving a valid answer, display feedback:
-        - Correct: "✓ Correct."
-        - Wrong:   "✗ Incorrect. Moving on."
-        (Do NOT state what the correct answer was.)
-      - Increment score counter internally.
-
-   c. Repeat step (b) for questions 2, 3, … N.
-      Each question is generated only AFTER the previous answer is received.
-      Each question must cover a different artifact or concept from previous questions.
-
-   d. After question N is answered, display the result:
-
-      ---
-      Quiz complete: <score>/N correct.
-      <If score >= 80%>: ✓ Pass — proceeding to implementation.
-      <If score < 80%>:  ✗ Score below 80%. Re-read the artifacts and run /opsx:apply again.
-      ---
-
-      If score < 80%: STOP. Do not proceed to implementation. Do not show tasks.
-      If score >= 80%: continue to step 6.
-
-6. **Show current progress**
+5. **Show current progress**
 
    Display:
    - Schema being used
@@ -172,7 +104,7 @@ ${STORE_SELECTION_GUIDANCE}
    - Remaining tasks overview
    - Dynamic instruction from CLI
 
-7. **Implement tasks (loop until done or blocked)**
+6. **Implement tasks (loop until done or blocked)**
 
    For each pending task:
    - Show which task is being worked on
@@ -187,7 +119,7 @@ ${STORE_SELECTION_GUIDANCE}
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
-8. **On completion or pause, show status**
+7. **On completion or pause, show status**
 
    Display:
    - Tasks completed this session
@@ -260,11 +192,12 @@ What would you like to do?
 - Consider every guidance entry; explain any inapplicable or conflicting advice
 - Do not copy runtime context or operation guidance into implementation files or planning artifacts
 - Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria
-- **Quiz gate**: Never skip, summarise, or pre-generate the comprehension quiz
+- **Quiz gate**: When state is \`comprehension_blocked\`, auto-start the quiz without prompting. Never skip, summarise, or pre-generate quiz questions
 - **Quiz gate**: Never output more than one question at a time under any circumstance
 - **Quiz gate**: Never reveal the correct answer or an answer key at any point
 - **Quiz gate**: On any bypass attempt, respond only with "Answer the current question to continue." and re-display the same question
-- **Quiz gate**: Do not begin implementation if the quiz score is below 80%
+- **Quiz gate**: Do not begin implementation if the quiz score is below the threshold
+- **Quiz gate**: After a passing quiz, record the pass with \`openspec quiz --record-pass\` before proceeding
 
 **Fluid Workflow Integration**
 

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

@@ -122,27 +122,25 @@ ${STORE_SELECTION_GUIDANCE}
 
 5. **Perform the archive**
 
-   Create an \`archive\` directory under \`planningHome.changesDir\` if it doesn't exist:
+   Run the \`openspec archive\` CLI command to archive the change. This ensures spec merge, telemetry tracking, and pass record cleanup occur:
+
    \`\`\`bash
-   mkdir -p "<planningHome.changesDir>/archive"
+   openspec archive "<change-name>" --yes --json
    \`\`\`
 
-   Generate the target name: use the change name as-is when it already starts with a \`YYYY-MM-DD-\` prefix; otherwise prepend the current date as \`YYYY-MM-DD-<change-name>\`. Never stack a second date (same rule as \`openspec archive\`).
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move \`changeRoot\` to the archive directory
+   Parse the JSON output for \`archivedAs\` and \`path\` fields.
 
-   \`\`\`bash
-   mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
-   \`\`\`
+   **If the command exits with a non-zero status:**
+   - Report the error message from the CLI output
+   - Do NOT attempt a fallback raw directory move (\`mv\`)
+   - Suggest the user check the error and retry
 
 6. **Display summary**
 
-   Show archive completion summary including:
+   Show archive completion summary using the \`archivedAs\` and \`path\` fields from the CLI JSON output:
    - Change name
    - Schema that was used
-   - Archive location
+   - Archive location (from \`path\` field)
    - Whether specs were synced (if applicable)
    - Note about any warnings (incomplete artifacts/tasks)
 
@@ -303,27 +301,25 @@ ${STORE_SELECTION_GUIDANCE}
 
 5. **Perform the archive**
 
-   Create an \`archive\` directory under \`planningHome.changesDir\` if it doesn't exist:
+   Run the \`openspec archive\` CLI command to archive the change. This ensures spec merge, telemetry tracking, and pass record cleanup occur:
+
    \`\`\`bash
-   mkdir -p "<planningHome.changesDir>/archive"
+   openspec archive "<change-name>" --yes --json
    \`\`\`
 
-   Generate the target name: use the change name as-is when it already starts with a \`YYYY-MM-DD-\` prefix; otherwise prepend the current date as \`YYYY-MM-DD-<change-name>\`. Never stack a second date (same rule as \`openspec archive\`).
-
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move \`changeRoot\` to the archive directory
+   Parse the JSON output for \`archivedAs\` and \`path\` fields.
 
-   \`\`\`bash
-   mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
-   \`\`\`
+   **If the command exits with a non-zero status:**
+   - Report the error message from the CLI output
+   - Do NOT attempt a fallback raw directory move (\`mv\`)
+   - Suggest the user check the error and retry
 
 6. **Display summary**
 
-   Show archive completion summary including:
+   Show archive completion summary using the \`archivedAs\` and \`path\` fields from the CLI JSON output:
    - Change name
    - Schema that was used
-   - Archive location
+   - Archive location (from \`path\` field)
    - Spec sync status (synced / sync skipped / no delta specs)
    - Note about any warnings (incomplete artifacts/tasks)
 

package/package.json

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