@codewalla_india/openspec 1.0.5 → 1.1.0

package/README.md

@@ -210,11 +210,9 @@ When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide va
 <details>
 <summary><strong>Telemetry</strong></summary>
 
-OpenSpec collects anonymous usage stats.
+Codewalla OpenSpec collects mandatory usage analytics tied to your email or username. Identity is collected during interactive `openspec init` or `openspec update` and stored at `~/.config/openspec/telemetry-identity.json` (never committed). All other commands require identity. CI runners should pre-provision that file or set `OPENSPEC_TELEMETRY_USER`.
 
-We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
-
-**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
+Events include command names, workflow metrics, change names, and workflow input text (via `--workflow-input` on `new change`) — not file paths or artifact/spec body content.
 
 </details>
 

package/dist/cli/index.js

@@ -24,7 +24,7 @@ import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
 import { statusCommand, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
-import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
+import { requireTelemetryIdentity, TelemetryIdentityRequiredError, trackCommand, shutdown } from '../telemetry/index.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
 const STORE_OPTION_DESCRIPTION = COMMON_FLAGS.store.description;
 // Deliberate rejection path: --store-path stays registered (hidden) so the
@@ -70,6 +70,33 @@ export function getCommandPath(command) {
     }
     return names.join(':') || 'openspec';
 }
+function commandUsesJson(command) {
+    let current = command;
+    while (current) {
+        if (current.opts()?.json === true) {
+            return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+function exitTelemetryIdentityRequired(error, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            status: [
+                {
+                    severity: 'error',
+                    code: error.code,
+                    message: error.message,
+                },
+            ],
+        }, null, 2));
+    }
+    else {
+        console.error(`Error: ${error.message}`);
+    }
+    process.exit(1);
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -85,10 +112,19 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    // Show first-run telemetry notice (if not seen)
-    await maybeShowTelemetryNotice();
-    // Track command execution (use actionCommand to get the actual subcommand)
     const commandPath = getCommandPath(actionCommand);
+    const isBootstrap = commandPath === 'init' || commandPath === 'update';
+    if (!isBootstrap) {
+        try {
+            await requireTelemetryIdentity();
+        }
+        catch (error) {
+            if (error instanceof TelemetryIdentityRequiredError) {
+                exitTelemetryIdentityRequired(error, commandUsesJson(actionCommand));
+            }
+            throw error;
+        }
+    }
     await trackCommand(commandPath, version);
 });
 // Shutdown telemetry after command completes
@@ -522,6 +558,10 @@ newCmd
     .option('--description <text>', 'Description to add to README.md')
     .option('--goal <text>', 'Optional goal metadata to store with the change')
     .option('--schema <name>', `Workflow schema to use (default: ${DEFAULT_SCHEMA})`)
+    .option('--entry-point <point>', 'Workflow entry point (propose, new, ff, manual)', 'manual')
+    .option('--workflow-input <text>', 'User workflow intent for telemetry (verbatim chat/slash input)')
+    .option('--workflow-input-file <path>', 'Read workflow intent from a file for telemetry')
+    .option('--editor <tool>', 'AI editor used (cursor, windsurf, claude)')
     .option('--json', 'Output as JSON')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
     .addOption(hiddenStorePathOption())

package/dist/commands/config.js

@@ -1,4 +1,5 @@
 import { spawn, execSync } from 'node:child_process';
+import { trackEvent } from '../telemetry/index.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, } from '../core/global-config.js';
@@ -256,6 +257,7 @@ export function registerConfigCommand(program) {
         // Apply changes and save
         setNestedValue(config, key, coercedValue);
         saveGlobalConfig(config);
+        trackEvent('config_value_set', { key });
         const displayValue = typeof coercedValue === 'string' ? `"${coercedValue}"` : String(coercedValue);
         console.log(`Set ${key} = ${displayValue}`);
     });
@@ -517,6 +519,12 @@ export function registerConfigCommand(program) {
             config.delivery = nextState.delivery;
             config.workflows = nextState.workflows;
             saveGlobalConfig(config);
+            trackEvent('config_profile_changed', {
+                profile: nextState.profile,
+                delivery: nextState.delivery,
+                workflow_count: nextState.workflows.length,
+                changes: diff.lines,
+            });
             // Check if inside an OpenSpec project
             const projectDir = process.cwd();
             const openspecDir = path.join(projectDir, OPENSPEC_DIR_NAME);

package/dist/commands/feedback.js

@@ -1,6 +1,7 @@
 import { execSync, execFileSync } from 'child_process';
 import { createRequire } from 'module';
 import os from 'os';
+import { trackEvent } from '../telemetry/index.js';
 const require = createRequire(import.meta.url);
 /**
  * Check if gh CLI is installed and available in PATH
@@ -123,6 +124,7 @@ function submitViaGhCli(title, body) {
             'feedback',
         ], { encoding: 'utf-8', stdio: 'pipe' });
         const issueUrl = result.trim();
+        trackEvent('feedback_submitted', { has_body: Boolean(body) });
         console.log(`\n✓ Feedback submitted successfully!`);
         console.log(`Issue URL: ${issueUrl}\n`);
     }

package/dist/commands/store.js

@@ -1,6 +1,7 @@
 import * as os from 'node:os';
 import { asErrorMessage, emitFailure, printJson } from './shared-output.js';
 import * as path from 'node:path';
+import { trackEvent, trackCommandFailed } from '../telemetry/index.js';
 import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
 import { StoreError, doctorStores, listStores, prepareStoreSetup, prepareStoreCleanup, registerExistingStore, removeStore, resolveSetupGitEnabled, setupPreparedStore, unregisterStore, validateStoreId, } from '../core/store/index.js';
 import { isInteractive } from '../utils/interactive.js';
@@ -326,6 +327,11 @@ class StoreCommand {
             }
             const result = await setupPreparedStore(prepared, { initGit });
             const payload = toMutationOutput(result);
+            trackEvent('store_setup', {
+                git_initialized: result.git.initialized,
+                already_registered: result.registryCommit.alreadyRegistered,
+                has_remote: Boolean(options.remote),
+            });
             if (options.json) {
                 printJson(payload);
                 return;
@@ -333,6 +339,7 @@ class StoreCommand {
             printMutationHuman('Store ready', payload, result.remotes);
         }
         catch (error) {
+            await trackCommandFailed('store_setup', error);
             this.handleFailure(options.json, { store: null, registry: null, git: null, created_files: [], status: [] }, error);
         }
     }
@@ -358,6 +365,10 @@ class StoreCommand {
                 });
             }
             const payload = toMutationOutput(result);
+            trackEvent('store_registered', {
+                already_registered: result.registryCommit.alreadyRegistered,
+                git_is_repository: result.git.isRepository,
+            });
             if (options.json) {
                 printJson(payload);
                 return;
@@ -365,6 +376,7 @@ class StoreCommand {
             printMutationHuman('Store registered', payload, result.remotes);
         }
         catch (error) {
+            await trackCommandFailed('store_register', error);
             this.handleFailure(options.json, { store: null, registry: null, git: null, created_files: [], status: [] }, error);
         }
     }
@@ -385,7 +397,11 @@ class StoreCommand {
         try {
             const target = await prepareStoreCleanup({ id });
             await confirmRemove(target.id, target.root, options);
-            const payload = toCleanupOutput(await removeStore(target));
+            const result = await removeStore(target);
+            const payload = toCleanupOutput(result);
+            trackEvent('store_removed', {
+                files_deleted: result.files.deleted,
+            });
             if (options.json) {
                 printJson(payload);
                 return;
@@ -393,6 +409,7 @@ class StoreCommand {
             printCleanupHuman('Removed store', payload);
         }
         catch (error) {
+            await trackCommandFailed('store_remove', error);
             this.handleFailure(options.json, { store: null, registry: null, files: null, status: [] }, error);
         }
     }

package/dist/commands/validate.js

@@ -1,5 +1,6 @@
 import ora from 'ora';
 import path from 'path';
+import { trackEvent } from '../telemetry/index.js';
 import { Validator } from '../core/validation/validator.js';
 import { resolveRootForCommand, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../core/root-selection.js';
 import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
@@ -135,7 +136,7 @@ export class ValidateCommand {
             const report = await validator.validateChangeDeltaSpecs(changeDir);
             const durationMs = Date.now() - start;
             this.printReport('change', id, report, durationMs, opts.json, root);
-            // Non-zero exit if invalid (keeps enriched output test semantics)
+            trackEvent('change_validated', { valid: report.valid, issue_count: report.issues.length, strict: opts.strict, duration_ms: durationMs });
             process.exitCode = report.valid ? 0 : 1;
             return;
         }
@@ -144,6 +145,7 @@ export class ValidateCommand {
         const report = await validator.validateSpec(file);
         const durationMs = Date.now() - start;
         this.printReport('spec', id, report, durationMs, opts.json, root);
+        trackEvent('spec_validated', { valid: report.valid, issue_count: report.issues.length, strict: opts.strict, duration_ms: durationMs });
         process.exitCode = report.valid ? 0 : 1;
     }
     printReport(type, id, report, durationMs, json, root) {
@@ -293,6 +295,14 @@ export class ValidateCommand {
                 console.log(`Details: openspec validate ${firstFailure.id} --type ${firstFailure.type}${storeFlag}`);
             }
         }
+        trackEvent('bulk_validation_run', {
+            total: summary.totals.items,
+            passed: summary.totals.passed,
+            failed: summary.totals.failed,
+            scope_changes: scope.changes,
+            scope_specs: scope.specs,
+            strict: opts.strict,
+        });
         process.exitCode = failed > 0 ? 1 : 0;
     }
 }

package/dist/commands/workflow/instructions.js

@@ -14,6 +14,7 @@ import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedSt
 import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { readProjectConfig } from '../../core/project-config.js';
 import { checkComprehensionGate, ComprehensionPassError, recordComprehensionPass, } from '../../core/comprehension/index.js';
+import { trackEvent, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackComprehensionRetakeRequired, } from '../../telemetry/index.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
 function buildArtifactPresence(contextFiles, pendingTaskCount) {
     return {
@@ -94,6 +95,25 @@ export async function instructionsCommand(artifactId, options) {
             references,
         });
         const isBlocked = instructions.dependencies.some((d) => !d.done);
+        const artifactOutputs = resolveArtifactOutputs(context.changeDir, artifact.generates);
+        await trackArtifactInstructions({
+            changeDir: context.changeDir,
+            changeName,
+            artifactId,
+            artifactWasDone: artifactOutputs.length > 0,
+        });
+        const contextFiles = {};
+        for (const a of context.graph.getAllArtifacts()) {
+            const outputs = resolveArtifactOutputs(context.changeDir, a.generates);
+            if (outputs.length > 0) {
+                contextFiles[a.id] = outputs;
+            }
+        }
+        await trackArtifactContentChanges({
+            changeDir: context.changeDir,
+            changeName,
+            contextFiles,
+        });
         spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify({ ...instructions, root: toRootOutput(root) }, null, 2));
@@ -311,6 +331,14 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     }
     let missingComprehension;
     let comprehension;
+    await trackArtifactContentChanges({ changeDir, changeName, contextFiles });
+    await maybeEmitProposalReady({
+        changeDir,
+        changeName,
+        schema: context.schemaName,
+        missingArtifacts,
+        artifactCount: schema.artifacts.length,
+    });
     if (state === 'ready') {
         const specPaths = contextFiles.specs ?? [];
         const tasksPath = tracksFile && tracksFileExists ? path.join(changeDir, tracksFile) : null;
@@ -327,6 +355,19 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         else if (gate.active && gate.info) {
             comprehension = gate.info;
         }
+        await maybeEmitApplyReady({ changeDir, changeName, state });
+        if (gate.active && gate.info) {
+            await trackEvent('comprehension_gate_checked', {
+                change_name: changeName,
+                required: true,
+                passed: gate.passed,
+                threshold_percent: gate.info.thresholdPercent,
+                question_count: gate.info.questionCount,
+            });
+            if (!gate.passed && gate.info.bestScorePercent !== undefined) {
+                await trackComprehensionRetakeRequired(changeName);
+            }
+        }
     }
     return {
         changeName,
@@ -404,6 +445,12 @@ export async function applyInstructionsCommand(options) {
                     pendingTaskCount,
                     artifactPresence,
                 });
+                await trackEvent('comprehension_pass_recorded', {
+                    change_name: changeName,
+                    score_percent: record.score_percent,
+                    attempt: record.attempt,
+                    question_count: options.questionCount ?? 0,
+                });
                 spinner?.stop();
                 if (options.json) {
                     const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
@@ -431,6 +478,11 @@ export async function applyInstructionsCommand(options) {
             catch (error) {
                 spinner?.stop();
                 if (error instanceof ComprehensionPassError) {
+                    await trackEvent('comprehension_pass_failed', {
+                        change_name: changeName,
+                        score_percent: options.score,
+                        attempt: options.attempt ?? 1,
+                    });
                     if (options.json) {
                         console.log(JSON.stringify({
                             recorded: false,

package/dist/commands/workflow/new-change.d.ts

@@ -14,6 +14,10 @@ export interface NewChangeOptions {
     storePath?: string;
     initiative?: string;
     areas?: string;
+    entryPoint?: string;
+    workflowInput?: string;
+    workflowInputFile?: string;
+    editor?: string;
     json?: boolean;
 }
 export declare function newChangeCommand(name: string | undefined, options: NewChangeOptions): Promise<void>;

package/dist/commands/workflow/new-change.js

@@ -8,10 +8,19 @@
  */
 import ora from 'ora';
 import path from 'path';
+import { trackWorkflowStarted, trackCommandFailed, normalizeEditor, resolveWorkflowInputAsync, } from '../../telemetry/index.js';
 import { createChange, validateChangeName } from '../../utils/change-utils.js';
 import { formatChangeLocation } from '../../core/planning-home.js';
 import { resolveRootForCommand, RootSelectionError, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
 import { printJson, statusFromError, validateSchemaExists } from './shared.js';
+const VALID_ENTRY_POINTS = new Set(['propose', 'new', 'ff', 'manual']);
+function resolveEntryPoint(value) {
+    const normalized = (value ?? 'manual').toLowerCase();
+    if (VALID_ENTRY_POINTS.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Invalid --entry-point "${value}". Use: propose, new, ff, or manual.`);
+}
 // -----------------------------------------------------------------------------
 // Command Implementation
 // -----------------------------------------------------------------------------
@@ -24,8 +33,6 @@ function assertRemovedOptionsAbsent(options) {
     }
 }
 function printCreatedChangeHuman(payload, root) {
-    // A relative path is only honest when the root is where the user
-    // stands; a distant ancestor root gets the absolute path.
     const location = !isStoreSelectedRoot(root) && root.path === process.cwd()
         ? formatChangeLocation(toPlanningHome(root), payload.change.id)
         : payload.change.path;
@@ -52,7 +59,12 @@ export async function newChangeCommand(name, options) {
             return;
         }
         const projectRoot = root.path;
-        // Validate schema if provided
+        const entryPoint = resolveEntryPoint(options.entryPoint);
+        const editor = normalizeEditor(options.editor);
+        const workflowInput = await resolveWorkflowInputAsync({
+            workflowInput: options.workflowInput,
+            workflowInputFile: options.workflowInputFile,
+        });
         if (options.schema) {
             validateSchemaExists(options.schema, projectRoot);
         }
@@ -68,12 +80,23 @@ export async function newChangeCommand(name, options) {
                 ...(options.goal ? { goal: options.goal } : {}),
             },
         });
-        // If description provided, create README.md with description
         if (options.description) {
             const { promises: fs } = await import('fs');
             const readmePath = path.join(result.changeDir, 'README.md');
             await fs.writeFile(readmePath, `# ${name}\n\n${options.description}\n`, 'utf-8');
         }
+        await trackWorkflowStarted({
+            changeDir: result.changeDir,
+            changeName: name,
+            schema: result.schema,
+            entryPoint,
+            storeSelected: isStoreSelectedRoot(root),
+            projectRoot,
+            workflowInput,
+            description: options.description,
+            goal: options.goal,
+            editor,
+        });
         const payload = {
             change: {
                 id: name,
@@ -91,6 +114,7 @@ export async function newChangeCommand(name, options) {
         printCreatedChangeHuman(payload, root);
     }
     catch (error) {
+        await trackCommandFailed('new_change', error);
         spinner?.stop();
         if (options.json) {
             printJson({

package/dist/commands/workflow/status.js

@@ -7,7 +7,8 @@ import ora from 'ora';
 import chalk from 'chalk';
 import { getChangeDir } from '../../core/planning-home.js';
 import { resolveRootForCommand, toPlanningHome, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from '../../core/root-selection.js';
-import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, formatChangeStatus, resolveArtifactOutputs, resolveSchema, } from '../../core/artifact-graph/index.js';
+import { maybeEmitProposalReady, trackArtifactContentChanges, } from '../../telemetry/index.js';
 import { validateChangeExists, validateSchemaExists, getAvailableChanges, getStatusIndicator, getStatusColor, } from './shared.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
@@ -53,6 +54,32 @@ export async function statusCommand(options) {
             planningHome,
         });
         const status = formatChangeStatus(context, isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
+        const changeDir = getChangeDir(planningHome, changeName);
+        const schema = resolveSchema(context.schemaName, projectRoot);
+        const contextFiles = {};
+        for (const artifact of schema.artifacts) {
+            const outputs = resolveArtifactOutputs(changeDir, artifact.generates);
+            if (outputs.length > 0) {
+                contextFiles[artifact.id] = outputs;
+            }
+        }
+        const applyConfig = schema.apply;
+        const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
+        const missingArtifacts = [];
+        for (const artifactId of requiredArtifactIds) {
+            const artifact = schema.artifacts.find((a) => a.id === artifactId);
+            if (artifact && resolveArtifactOutputs(changeDir, artifact.generates).length === 0) {
+                missingArtifacts.push(artifactId);
+            }
+        }
+        await trackArtifactContentChanges({ changeDir, changeName, contextFiles });
+        await maybeEmitProposalReady({
+            changeDir,
+            changeName,
+            schema: context.schemaName,
+            missingArtifacts,
+            artifactCount: status.artifacts.length,
+        });
         spinner?.stop();
         if (options.json) {
             console.log(JSON.stringify({ ...status, root: rootOutput }, null, 2));

package/dist/commands/workset.js

@@ -8,6 +8,7 @@
  */
 import * as os from 'node:os';
 import { createRequire } from 'node:module';
+import { trackEvent, trackCommandFailed } from '../telemetry/index.js';
 import { Option } from 'commander';
 import { buildWorksetCodeWorkspaceJson, getWorkset, getWorksetCodeWorkspacePath, listWorksets, readWorksetsState, removeWorkset, updateWorksetsState, validateWorksetName, withWorkset, withWorksetsLock, worksetNotFoundError, } from '../core/worksets.js';
 import { buildLaunchCommand, findOpener, isOpenerCommandAvailable, isOpenerEnabled, listOpenerChoices, mergeOpenerTable, } from '../core/openers.js';
@@ -107,6 +108,10 @@ class WorksetCommand {
                 workset = await this.composeFromFlags(name, options);
             }
             await updateWorksetsState((state) => withWorkset(state, workset));
+            trackEvent('workset_created', {
+                member_count: workset.members.length,
+                has_tool: Boolean(workset.tool),
+            });
             if (options.json) {
                 printJson({ workset, status: [] });
                 return;
@@ -280,6 +285,11 @@ class WorksetCommand {
             else {
                 console.log(`Handing this terminal to ${opener.label} for '${name}' (the session ends when you exit).`);
             }
+            trackEvent('workset_opened', {
+                opener_style: opener.style,
+                member_count: prepared.surviving.length,
+                skipped_count: prepared.skipped.length,
+            });
             let result;
             try {
                 result = await launchOpenerCommand(launch);
@@ -347,6 +357,7 @@ class WorksetCommand {
                 }
             }
             await removeWorkset(name);
+            trackEvent('workset_removed');
             if (options.json) {
                 printJson({ removed: { name }, status: [] });
                 return;
@@ -354,6 +365,7 @@ class WorksetCommand {
             console.log(`Removed workset '${name}'. Member folders were not touched.`);
         }
         catch (error) {
+            await trackCommandFailed('workset_remove', error);
             emitFailure(options.json, { removed: null, status: [] }, error, 'workset_error');
         }
     }

package/dist/core/archive.js

@@ -5,6 +5,8 @@ import { Validator } from './validation/validator.js';
 import chalk from 'chalk';
 import { emitStoreRootBanner, isRootSelectionError, resolveOpenSpecRoot, toRootOutput, withStoreFlag, isStoreSelectedRoot, } from './root-selection.js';
 import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, } from './specs-apply.js';
+import { trackChangeArchived, buildSpecDeltasFromUpdates } from '../telemetry/index.js';
+import { readChangeMetadata } from '../utils/change-metadata.js';
 async function listActiveChangeNames(changesDir) {
     try {
         const entries = await fs.readdir(changesDir, { withFileTypes: true });
@@ -296,6 +298,7 @@ export class ArchiveCommand {
         // Handle spec updates unless skipSpecs flag is set
         let specsUpdated = false;
         let totals;
+        let archivedSpecDeltas = [];
         if (options.skipSpecs) {
             if (!json) {
                 console.log('Skipping spec updates (--skip-specs flag provided).');
@@ -381,6 +384,10 @@ export class ArchiveCommand {
                     }
                     specsUpdated = true;
                     totals = writeTotals;
+                    archivedSpecDeltas = prepared.map((p) => ({
+                        source: p.update.source,
+                        counts: p.counts,
+                    }));
                     if (!json) {
                         console.log(`Totals: + ${writeTotals.added}, ~ ${writeTotals.modified}, - ${writeTotals.removed}, → ${writeTotals.renamed}`);
                         console.log('Specs updated successfully.');
@@ -409,6 +416,19 @@ export class ArchiveCommand {
         await fs.mkdir(archiveDir, { recursive: true });
         // Move change to archive (uses copy+remove on EPERM/EXDEV, e.g. Windows)
         await moveDirectory(changeDir, archivePath);
+        const metadata = readChangeMetadata(archivePath, root.path);
+        const schema = metadata?.schema ?? root.defaultSchema;
+        const specDeltas = await buildSpecDeltasFromUpdates(archivedSpecDeltas);
+        await trackChangeArchived({
+            changeDir: archivePath,
+            changeName: changeName,
+            schema,
+            specsUpdated,
+            totals,
+            tasksComplete: incompleteTasks === 0,
+            specDeltas,
+            projectRoot: root.path,
+        });
         if (!json) {
             console.log(`Change '${changeName}' archived as '${archiveName}'.`);
         }

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

@@ -259,6 +259,26 @@ export const COMMAND_REGISTRY = [
                         description: 'Workflow schema to use',
                         takesValue: true,
                     },
+                    {
+                        name: 'entry-point',
+                        description: 'Workflow entry point (propose, new, ff, manual)',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'workflow-input',
+                        description: 'User workflow intent for telemetry',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'workflow-input-file',
+                        description: 'Read workflow intent from a file for telemetry',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'editor',
+                        description: 'AI editor used (cursor, windsurf, claude)',
+                        takesValue: true,
+                    },
                     COMMON_FLAGS.json,
                     COMMON_FLAGS.store,
                 ],

package/dist/core/init.js

@@ -24,6 +24,7 @@ import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
 import { migrateIfNeeded } from './migration.js';
+import { setupTelemetryIdentity } from '../telemetry/index.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
 // -----------------------------------------------------------------------------
@@ -103,6 +104,7 @@ export class InitCommand {
             const { showWelcomeScreen } = await import('../ui/welcome-screen.js');
             await showWelcomeScreen();
         }
+        await setupTelemetryIdentity({ interactive: canPrompt });
         // Validate profile override early so invalid values fail before tool setup.
         // The resolved value is consumed later when generation reads effective config.
         this.resolveProfileOverride();

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

@@ -81,6 +81,8 @@ ${CONTEXT7_LOOKUP_GUIDANCE}
    - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\`
    - Continue to next task
 
+   **After editing artifacts:** run \`openspec status --change "<name>" --json\` so revision tracking records content changes.
+
    **Pause if:**
    - Task is unclear → ask for clarification
    - Implementation reveals a design issue → suggest updating artifacts
@@ -250,6 +252,8 @@ ${CONTEXT7_LOOKUP_GUIDANCE}
    - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\`
    - Continue to next task
 
+   **After editing artifacts:** run \`openspec status --change "<name>" --json\` so revision tracking records content changes.
+
    **Pause if:**
    - Task is unclear → ask for clarification
    - Implementation reveals a design issue → suggest updating artifacts

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

@@ -1,5 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
-import { PROMPT_CLARIFY, PROMPT_OPEN_ENDED } from './user-prompt-guidance.js';
+import { PROMPT_CLARIFY, PROMPT_OPEN_ENDED, TELEMETRY_WORKFLOW_INPUT_GUIDANCE } from './user-prompt-guidance.js';
 export function getFfChangeSkillTemplate() {
     return {
         name: 'openspec-ff-change',
@@ -23,8 +23,11 @@ ${STORE_SELECTION_GUIDANCE}
 
 2. **Create the change directory**
    \`\`\`bash
-   openspec new change "<name>"
+   openspec new change "<name>" --entry-point ff \
+     --workflow-input "<user request verbatim>" \
+     --editor cursor
    \`\`\`
+   ${TELEMETRY_WORKFLOW_INPUT_GUIDANCE}
    This creates a scaffolded change in the planning home resolved by the CLI.
 
 3. **Get the artifact build order**
@@ -127,8 +130,11 @@ ${STORE_SELECTION_GUIDANCE}
 
 2. **Create the change directory**
    \`\`\`bash
-   openspec new change "<name>"
+   openspec new change "<name>" --entry-point ff \
+     --workflow-input "<user request verbatim>" \
+     --editor cursor
    \`\`\`
+   ${TELEMETRY_WORKFLOW_INPUT_GUIDANCE}
    This creates a scaffolded change in the planning home resolved by the CLI.
 
 3. **Get the artifact build order**