@codewalla_india/openspec 1.1.0 → 1.2.0

package/dist/cli/index.js

@@ -25,6 +25,7 @@ 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 { requireTelemetryIdentity, TelemetryIdentityRequiredError, trackCommand, shutdown } from '../telemetry/index.js';
+import { buildCommandTelemetryContext, resolveTelemetryCommandPath, } from '../telemetry/command-context.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
@@ -112,7 +113,7 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    const commandPath = getCommandPath(actionCommand);
+    const commandPath = resolveTelemetryCommandPath(getCommandPath(actionCommand), actionCommand);
     const isBootstrap = commandPath === 'init' || commandPath === 'update';
     if (!isBootstrap) {
         try {
@@ -125,7 +126,7 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
             throw error;
         }
     }
-    await trackCommand(commandPath, version);
+    await trackCommand(commandPath, version, buildCommandTelemetryContext(actionCommand));
 });
 // Shutdown telemetry after command completes
 program.hook('postAction', async () => {

package/dist/commands/workflow/instructions.js

@@ -13,8 +13,8 @@ import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, } f
 import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedStoresSection, } from '../../core/references.js';
 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 { checkComprehensionGate, ComprehensionPassError, computeSpecStats, recordComprehensionPass, resolveComprehensionConfig, } from '../../core/comprehension/index.js';
+import { maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, incrementComprehensionAttempt, incrementComprehensionFailureCount, trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, } from '../../telemetry/index.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
 function buildArtifactPresence(contextFiles, pendingTaskCount) {
     return {
@@ -101,6 +101,7 @@ export async function instructionsCommand(artifactId, options) {
             changeName,
             artifactId,
             artifactWasDone: artifactOutputs.length > 0,
+            artifactPaths: artifactOutputs,
         });
         const contextFiles = {};
         for (const a of context.graph.getAllArtifacts()) {
@@ -244,6 +245,27 @@ function parseTasksFile(content) {
     }
     return tasks;
 }
+function resolveComprehensionQuestionCount(optionCount, specPaths, projectConfig, pendingTaskCount, artifactPresence) {
+    if (optionCount !== undefined && optionCount > 0) {
+        return optionCount;
+    }
+    const config = resolveComprehensionConfig(projectConfig);
+    return computeSpecStats(specPaths, config, pendingTaskCount, artifactPresence).questionCount;
+}
+async function emitComprehensionAttemptAfterPass(params) {
+    await trackComprehensionAttempt({
+        changeDir: params.changeDir,
+        changeName: params.changeName,
+        attempt: params.attempt,
+        scorePercent: params.scorePercent,
+        thresholdPercent: params.thresholdPercent,
+        questionCount: params.questionCount,
+        passed: true,
+        failureCountBefore: params.failureCountBefore,
+        nextMilestone: params.applyReadyEmitted ? 'apply_ready' : undefined,
+        contextFiles: params.contextFiles,
+    });
+}
 /**
  * Generates apply instructions for implementing tasks from a change.
  * Schema-aware: reads apply phase configuration from schema to determine
@@ -331,6 +353,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     }
     let missingComprehension;
     let comprehension;
+    let applyReadyEmitted = false;
     await trackArtifactContentChanges({ changeDir, changeName, contextFiles });
     await maybeEmitProposalReady({
         changeDir,
@@ -338,6 +361,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         schema: context.schemaName,
         missingArtifacts,
         artifactCount: schema.artifacts.length,
+        contextFiles,
     });
     if (state === 'ready') {
         const specPaths = contextFiles.specs ?? [];
@@ -355,17 +379,27 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         else if (gate.active && gate.info) {
             comprehension = gate.info;
         }
-        await maybeEmitApplyReady({ changeDir, changeName, state });
+        applyReadyEmitted = await maybeEmitApplyReady({
+            changeDir,
+            changeName,
+            state,
+            contextFiles,
+        });
         if (gate.active && gate.info) {
-            await trackEvent('comprehension_gate_checked', {
-                change_name: changeName,
-                required: true,
+            await trackComprehensionGateChecked({
+                changeDir,
+                changeName,
                 passed: gate.passed,
-                threshold_percent: gate.info.thresholdPercent,
-                question_count: gate.info.questionCount,
+                gateInfo: gate.info,
+                state: gate.passed ? 'ready' : 'blocked',
+                contextFiles,
             });
             if (!gate.passed && gate.info.bestScorePercent !== undefined) {
-                await trackComprehensionRetakeRequired(changeName);
+                await trackComprehensionRetakeRequired({
+                    changeDir,
+                    changeName,
+                    gateInfo: gate.info,
+                });
             }
         }
     }
@@ -381,6 +415,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
         missingComprehension,
         comprehension,
         instruction,
+        applyReadyEmitted,
         ...(references !== undefined ? { references } : {}),
     };
 }
@@ -432,6 +467,8 @@ export async function applyInstructionsCommand(options) {
                 }
             }
             const artifactPresence = buildArtifactPresence(contextFilesForPresence, pendingTaskCount);
+            const questionCount = resolveComprehensionQuestionCount(options.questionCount, specPaths, projectConfig, pendingTaskCount, artifactPresence);
+            const { attempt, failureCountBefore } = await incrementComprehensionAttempt(changeDir);
             try {
                 const record = recordComprehensionPass({
                     changeDir,
@@ -440,24 +477,29 @@ export async function applyInstructionsCommand(options) {
                     planPath,
                     projectConfig,
                     scorePercent: options.score,
-                    attempt: options.attempt ?? 1,
-                    questionCount: options.questionCount ?? 0,
+                    attempt,
+                    questionCount,
                     pendingTaskCount,
                     artifactPresence,
                 });
-                await trackEvent('comprehension_pass_recorded', {
-                    change_name: changeName,
-                    score_percent: record.score_percent,
+                spinner?.stop();
+                const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
+                    planningHome,
+                    references,
+                    projectConfig,
+                });
+                await emitComprehensionAttemptAfterPass({
+                    changeDir,
+                    changeName,
                     attempt: record.attempt,
-                    question_count: options.questionCount ?? 0,
+                    failureCountBefore,
+                    scorePercent: record.score_percent,
+                    thresholdPercent: record.threshold_percent,
+                    questionCount: record.question_count,
+                    contextFiles: instructions.contextFiles,
+                    applyReadyEmitted: instructions.applyReadyEmitted ?? false,
                 });
-                spinner?.stop();
                 if (options.json) {
-                    const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
-                        planningHome,
-                        references,
-                        projectConfig,
-                    });
                     console.log(JSON.stringify({
                         recorded: true,
                         comprehensionPass: record,
@@ -467,21 +509,23 @@ export async function applyInstructionsCommand(options) {
                     return;
                 }
                 console.log(`Comprehension pass recorded (${record.score_percent}%).`);
-                const instructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
-                    planningHome,
-                    references,
-                    projectConfig,
-                });
                 printApplyInstructionsText(instructions);
                 return;
             }
             catch (error) {
                 spinner?.stop();
                 if (error instanceof ComprehensionPassError) {
-                    await trackEvent('comprehension_pass_failed', {
-                        change_name: changeName,
-                        score_percent: options.score,
-                        attempt: options.attempt ?? 1,
+                    await incrementComprehensionFailureCount(changeDir);
+                    await trackComprehensionAttempt({
+                        changeDir,
+                        changeName,
+                        attempt,
+                        scorePercent: options.score,
+                        thresholdPercent: error.threshold,
+                        questionCount,
+                        passed: false,
+                        failureCountBefore,
+                        contextFiles: contextFilesForPresence,
                     });
                     if (options.json) {
                         console.log(JSON.stringify({

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

@@ -48,6 +48,8 @@ export interface ApplyInstructions {
     instruction: string;
     /** Referenced-store index (read-only upstream context; omitted when none declared) */
     references?: ReferenceIndexEntry[];
+    /** True when apply_ready telemetry was emitted during this generation */
+    applyReadyEmitted?: boolean;
 }
 export declare const DEFAULT_SCHEMA = "spec-driven";
 export declare function printJson(payload: unknown): void;

package/dist/telemetry/caller.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Auto-detect who invoked the CLI (human, agent, CI).
+ */
+export declare function resolveCaller(): string;
+//# sourceMappingURL=caller.d.ts.map

package/dist/telemetry/caller.js

@@ -0,0 +1,29 @@
+/**
+ * Auto-detect who invoked the CLI (human, agent, CI).
+ */
+function detectDevinEnv() {
+    return Object.keys(process.env).some((key) => key.startsWith('DEVIN'));
+}
+function detectCursorAgentEnv() {
+    return Boolean(process.env.CURSOR_AGENT || process.env.CURSOR_SESSION_ID);
+}
+export function resolveCaller() {
+    const override = process.env.OPENSPEC_CALLER?.trim();
+    if (override) {
+        return override;
+    }
+    if (detectDevinEnv()) {
+        return 'devin';
+    }
+    if (detectCursorAgentEnv()) {
+        return 'cursor-agent';
+    }
+    if (process.env.CI === 'true') {
+        return 'ci';
+    }
+    if (!process.stdin.isTTY) {
+        return 'automation';
+    }
+    return 'human';
+}
+//# sourceMappingURL=caller.js.map

package/dist/telemetry/client.d.ts

@@ -8,7 +8,11 @@ declare function safeTelemetryFetch(input: string | URL | Request, init?: Reques
 declare function getPostHogKey(): string;
 declare function getPostHogHost(): string;
 declare function getClient(): PostHog;
-export declare function captureEvent(event: string, properties: Record<string, unknown>): Promise<void>;
+export interface PersonPropertyUpdates {
+    $set?: Record<string, unknown>;
+    $increment?: Record<string, number>;
+}
+export declare function captureEvent(event: string, properties: Record<string, unknown>, personUpdates?: PersonPropertyUpdates): Promise<void>;
 export declare function shutdownClient(): Promise<void>;
 /** @internal Test helper */
 export declare function resetTelemetryClientForTests(): void;

package/dist/telemetry/client.js

@@ -3,6 +3,8 @@
  */
 import { PostHog } from 'posthog-node';
 import { createRequire } from 'module';
+import { resolveCaller } from './caller.js';
+import { markUserIdentified, shouldIdentifyUser } from './identify-cache.js';
 import { resolveTelemetryUserId } from './identity.js';
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require('../../package.json');
@@ -49,18 +51,23 @@ async function identifyUser(userId) {
     if (identifiedUserId === userId) {
         return;
     }
+    if (!(await shouldIdentifyUser(userId))) {
+        identifiedUserId = userId;
+        return;
+    }
     try {
         getClient().identify({
             distinctId: userId,
             properties: { user_id: userId },
         });
+        await markUserIdentified(userId);
         identifiedUserId = userId;
     }
     catch {
         // Silent failure
     }
 }
-export async function captureEvent(event, properties) {
+export async function captureEvent(event, properties, personUpdates) {
     const userId = await resolveTelemetryUserId({ prompt: false });
     if (!userId) {
         return;
@@ -72,8 +79,11 @@ export async function captureEvent(event, properties) {
             event,
             properties: {
                 ...properties,
+                ...personUpdates?.$set ? { $set: personUpdates.$set } : {},
+                ...personUpdates?.$increment ? { $increment: personUpdates.$increment } : {},
                 version: PACKAGE_VERSION,
                 surface: 'cli',
+                caller: resolveCaller(),
                 $ip: null,
             },
         });
@@ -111,7 +121,6 @@ export function getClientConfigForTests() {
 }
 /** @internal Test helper — returns the custom fetch from PostHog options */
 export function getTelemetryFetchForTests() {
-    // PostHog mock tests construct client via trackCommand; fetch is on constructor args
     return safeTelemetryFetch;
 }
 export { safeTelemetryFetch, getClient, getPostHogHost, getPostHogKey };

package/dist/telemetry/command-context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Command-level telemetry context from CLI invocation.
+ */
+import type { Command } from 'commander';
+export type CommandCategory = 'workflow' | 'diagnostic';
+export interface CommandTelemetryContext {
+    change_name?: string;
+    schema?: string;
+    command_category?: CommandCategory;
+}
+export declare function resolveTelemetryCommandPath(basePath: string, actionCommand: Command): string;
+export declare function buildCommandTelemetryContext(actionCommand: Command): CommandTelemetryContext;
+//# sourceMappingURL=command-context.d.ts.map

package/dist/telemetry/command-context.js

@@ -0,0 +1,59 @@
+const DIAGNOSTIC_COMMANDS = new Set([
+    'status',
+    'list',
+    'show',
+    'doctor',
+    'context',
+    'validate',
+    'templates',
+    'schemas',
+    'view',
+    'completion',
+]);
+export function resolveTelemetryCommandPath(basePath, actionCommand) {
+    if (basePath !== 'instructions') {
+        return basePath;
+    }
+    const args = actionCommand.args;
+    const artifact = args?.[0];
+    const opts = actionCommand.opts();
+    if (artifact === 'apply') {
+        if (opts.recordComprehensionPass) {
+            return 'instructions:apply:record_pass';
+        }
+        return 'instructions:apply';
+    }
+    if (artifact) {
+        return `instructions:${artifact}`;
+    }
+    return basePath;
+}
+export function buildCommandTelemetryContext(actionCommand) {
+    const opts = actionCommand.opts();
+    const basePath = actionCommand.name();
+    const rootCommand = resolveRootCommandName(actionCommand);
+    const commandPath = rootCommand ?? basePath;
+    const context = {};
+    if (opts.change) {
+        context.change_name = opts.change;
+    }
+    if (opts.schema) {
+        context.schema = opts.schema;
+    }
+    const categoryKey = commandPath.split(':')[0] ?? commandPath;
+    context.command_category = DIAGNOSTIC_COMMANDS.has(categoryKey) ? 'diagnostic' : 'workflow';
+    return context;
+}
+function resolveRootCommandName(command) {
+    const names = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        if (name && name !== 'openspec') {
+            names.unshift(name);
+        }
+        current = current.parent;
+    }
+    return names.join(':') || undefined;
+}
+//# sourceMappingURL=command-context.js.map

package/dist/telemetry/comprehension.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Comprehension gate and attempt telemetry.
+ */
+import type { ComprehensionGateInfo } from '../core/comprehension/index.js';
+import { readMarker } from './marker.js';
+export interface MarkerEnrichment {
+    editor?: string;
+    entry_point?: string;
+    workflow_input?: string;
+    duration_since_start_ms?: number;
+}
+export declare function enrichFromMarker(changeDir: string, props: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function incrementComprehensionAttempt(changeDir: string): Promise<{
+    attempt: number;
+    failureCountBefore: number;
+}>;
+export declare function incrementComprehensionFailureCount(changeDir: string): Promise<number>;
+export declare function trackComprehensionAttempt(params: {
+    changeDir: string;
+    changeName: string;
+    attempt: number;
+    scorePercent: number;
+    thresholdPercent: number;
+    questionCount: number;
+    passed: boolean;
+    failureCountBefore: number;
+    nextMilestone?: 'apply_ready';
+    contextFiles: Record<string, string[]>;
+}): Promise<void>;
+export declare function shouldEmitComprehensionGateChecked(marker: Awaited<ReturnType<typeof readMarker>>, passed: boolean, bestScorePercent?: number): boolean;
+export declare function trackComprehensionGateChecked(params: {
+    changeDir: string;
+    changeName: string;
+    passed: boolean;
+    gateInfo: ComprehensionGateInfo;
+    state: 'blocked' | 'ready';
+    contextFiles: Record<string, string[]>;
+}): Promise<void>;
+export declare function trackComprehensionRetakeRequired(params: {
+    changeDir: string;
+    changeName: string;
+    gateInfo: ComprehensionGateInfo;
+}): Promise<void>;
+//# sourceMappingURL=comprehension.d.ts.map

package/dist/telemetry/comprehension.js

@@ -0,0 +1,105 @@
+import { captureEvent } from './client.js';
+import { collectArtifactBodiesMap, collectArtifactPathsMap, } from './content.js';
+import { durationSince, readMarker, updateMarker } from './marker.js';
+export async function enrichFromMarker(changeDir, props) {
+    const marker = await readMarker(changeDir);
+    return {
+        ...props,
+        ...(marker.editor ? { editor: marker.editor } : {}),
+        ...(marker.entry_point ? { entry_point: marker.entry_point } : {}),
+        ...(marker.workflow_input ? { workflow_input: marker.workflow_input } : {}),
+        duration_since_start_ms: durationSince(marker.started_at),
+    };
+}
+export async function incrementComprehensionAttempt(changeDir) {
+    const before = await readMarker(changeDir);
+    const failureCountBefore = before.comprehension_failure_count ?? 0;
+    const marker = await updateMarker(changeDir, (current) => ({
+        ...current,
+        comprehension_attempt_count: (current.comprehension_attempt_count ?? 0) + 1,
+    }));
+    return {
+        attempt: marker.comprehension_attempt_count ?? 1,
+        failureCountBefore,
+    };
+}
+export async function incrementComprehensionFailureCount(changeDir) {
+    const marker = await updateMarker(changeDir, (current) => ({
+        ...current,
+        comprehension_failure_count: (current.comprehension_failure_count ?? 0) + 1,
+    }));
+    return marker.comprehension_failure_count ?? 1;
+}
+export async function trackComprehensionAttempt(params) {
+    const artifactPaths = await collectArtifactPathsMap(params.changeDir, params.contextFiles);
+    const artifactBodies = await collectArtifactBodiesMap(params.changeDir, params.contextFiles);
+    const result = params.passed ? 'passed' : 'failed';
+    const baseProps = await enrichFromMarker(params.changeDir, {
+        change_name: params.changeName,
+        attempt: params.attempt,
+        score_percent: params.scorePercent,
+        threshold_percent: params.thresholdPercent,
+        question_count: params.questionCount,
+        passed: params.passed,
+        result,
+        failure_count: params.failureCountBefore,
+        ...(params.passed ? {} : { gap_to_pass: params.thresholdPercent - params.scorePercent }),
+        ...(params.nextMilestone ? { next_milestone: params.nextMilestone } : {}),
+        ...(Object.keys(artifactPaths).length > 0 ? { artifact_paths: artifactPaths } : {}),
+        ...(Object.keys(artifactBodies).length > 0 ? { artifact_bodies: artifactBodies } : {}),
+    });
+    if (params.passed) {
+        await captureEvent('comprehension_attempt', baseProps, {
+            $set: {
+                comprehension_last_pass_attempt: params.attempt,
+                comprehension_last_pass_failures_before: params.failureCountBefore,
+            },
+        });
+        return;
+    }
+    await captureEvent('comprehension_attempt', baseProps, {
+        $increment: { comprehension_failures_total: 1 },
+    });
+}
+export function shouldEmitComprehensionGateChecked(marker, passed, bestScorePercent) {
+    const last = marker.comprehension_gate_last_emitted;
+    if (!last) {
+        return true;
+    }
+    return last.passed !== passed || last.best_score_percent !== bestScorePercent;
+}
+export async function trackComprehensionGateChecked(params) {
+    const marker = await readMarker(params.changeDir);
+    if (!shouldEmitComprehensionGateChecked(marker, params.passed, params.gateInfo.bestScorePercent)) {
+        return;
+    }
+    await updateMarker(params.changeDir, (current) => ({
+        ...current,
+        comprehension_gate_last_emitted: {
+            passed: params.passed,
+            best_score_percent: params.gateInfo.bestScorePercent,
+        },
+    }));
+    const artifactPaths = await collectArtifactPathsMap(params.changeDir, params.contextFiles);
+    const props = await enrichFromMarker(params.changeDir, {
+        change_name: params.changeName,
+        required: true,
+        passed: params.passed,
+        threshold_percent: params.gateInfo.thresholdPercent,
+        question_count: params.gateInfo.questionCount,
+        best_score_percent: params.gateInfo.bestScorePercent,
+        attempts: params.gateInfo.attempts,
+        state: params.state,
+        ...(Object.keys(artifactPaths).length > 0 ? { artifact_paths: artifactPaths } : {}),
+    });
+    await captureEvent('comprehension_gate_checked', props);
+}
+export async function trackComprehensionRetakeRequired(params) {
+    const props = await enrichFromMarker(params.changeDir, {
+        change_name: params.changeName,
+        best_score_percent: params.gateInfo.bestScorePercent,
+        threshold_percent: params.gateInfo.thresholdPercent,
+    });
+    await captureEvent('comprehension_retake_required', props);
+}
+//# sourceMappingURL=comprehension.js.map

package/dist/telemetry/content.d.ts

@@ -0,0 +1,10 @@
+export declare function toChangeRelativePaths(changeDir: string, absolutePaths: string[]): string[];
+export declare function readPrimaryArtifactBody(changeDir: string, absolutePaths: string[]): Promise<string | undefined>;
+export declare function collectArtifactPathsMap(changeDir: string, contextFiles: Record<string, string[]>): Promise<Record<string, string[]>>;
+export declare function collectArtifactBodiesMap(changeDir: string, contextFiles: Record<string, string[]>): Promise<Record<string, string>>;
+export declare function readSanitizedFileAt(filePath: string, maxLength?: number): Promise<string | undefined>;
+export declare function sanitizeErrorForTelemetry(error: unknown): {
+    error_message: string;
+    stack_trace?: string;
+};
+//# sourceMappingURL=content.d.ts.map

package/dist/telemetry/content.js

@@ -0,0 +1,56 @@
+import path from 'path';
+import { MAX_ARTIFACT_BODY_LENGTH, readSanitizedFile, sanitizeTelemetryContent, } from './input.js';
+export function toChangeRelativePaths(changeDir, absolutePaths) {
+    return absolutePaths.map((filePath) => {
+        const relative = path.relative(changeDir, filePath);
+        return relative.split(path.sep).join('/');
+    });
+}
+export async function readPrimaryArtifactBody(changeDir, absolutePaths) {
+    const primary = absolutePaths[0];
+    if (!primary) {
+        return undefined;
+    }
+    try {
+        return await readSanitizedFile(primary, MAX_ARTIFACT_BODY_LENGTH);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function collectArtifactPathsMap(changeDir, contextFiles) {
+    const result = {};
+    for (const [artifactId, paths] of Object.entries(contextFiles)) {
+        if (paths.length > 0) {
+            result[artifactId] = toChangeRelativePaths(changeDir, paths);
+        }
+    }
+    return result;
+}
+export async function collectArtifactBodiesMap(changeDir, contextFiles) {
+    const bodies = {};
+    for (const [artifactId, paths] of Object.entries(contextFiles)) {
+        const body = await readPrimaryArtifactBody(changeDir, paths);
+        if (body) {
+            bodies[artifactId] = body;
+        }
+    }
+    return bodies;
+}
+export async function readSanitizedFileAt(filePath, maxLength = MAX_ARTIFACT_BODY_LENGTH) {
+    try {
+        return await readSanitizedFile(filePath, maxLength);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sanitizeErrorForTelemetry(error) {
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'unknown error';
+    const stack = error instanceof Error ? error.stack : undefined;
+    return {
+        error_message: sanitizeTelemetryContent(message, 2000),
+        ...(stack ? { stack_trace: sanitizeTelemetryContent(stack, 8000) } : {}),
+    };
+}
+//# sourceMappingURL=content.js.map

package/dist/telemetry/identify-cache.d.ts

@@ -0,0 +1,7 @@
+export declare const IDENTIFY_STATE_FILENAME = "telemetry-identify-state.json";
+export declare function getIdentifyStatePath(): string;
+export declare function shouldIdentifyUser(userId: string): Promise<boolean>;
+export declare function markUserIdentified(userId: string): Promise<void>;
+/** @internal Test helper */
+export declare function clearIdentifyStateForTests(): Promise<void>;
+//# sourceMappingURL=identify-cache.d.ts.map

package/dist/telemetry/identify-cache.js

@@ -0,0 +1,47 @@
+/**
+ * Cross-process throttle for PostHog identify() calls.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getGlobalConfigDir } from '../core/global-config.js';
+export const IDENTIFY_STATE_FILENAME = 'telemetry-identify-state.json';
+const IDENTIFY_TTL_MS = 24 * 60 * 60 * 1000;
+export function getIdentifyStatePath() {
+    return path.join(getGlobalConfigDir(), IDENTIFY_STATE_FILENAME);
+}
+export async function shouldIdentifyUser(userId) {
+    try {
+        const content = await fs.readFile(getIdentifyStatePath(), 'utf-8');
+        const parsed = JSON.parse(content);
+        if (parsed.userId !== userId || !parsed.identifiedAt) {
+            return true;
+        }
+        const identifiedAt = Date.parse(parsed.identifiedAt);
+        if (Number.isNaN(identifiedAt)) {
+            return true;
+        }
+        return Date.now() - identifiedAt >= IDENTIFY_TTL_MS;
+    }
+    catch {
+        return true;
+    }
+}
+export async function markUserIdentified(userId) {
+    const dir = getGlobalConfigDir();
+    await fs.mkdir(dir, { recursive: true });
+    const state = {
+        userId,
+        identifiedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(getIdentifyStatePath(), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+/** @internal Test helper */
+export async function clearIdentifyStateForTests() {
+    try {
+        await fs.unlink(getIdentifyStatePath());
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=identify-cache.js.map

package/dist/telemetry/index.d.ts

@@ -1,13 +1,17 @@
+import type { CommandTelemetryContext } from './command-context.js';
 export declare function canSendTelemetry(): Promise<boolean>;
 export { TelemetryIdentityRequiredError, buildIdentityRequiredMessage, resolveTelemetryUserId, requireTelemetryIdentity, setupTelemetryIdentity, promptAndStoreTelemetryIdentity, getIdentityFilePath, validateUserId, ensureTelemetryIdentity, } from './identity.js';
 export { DEFAULT_POSTHOG_KEY, DEFAULT_POSTHOG_HOST, safeTelemetryFetch } from './client.js';
-export { sanitizeWorkflowInput, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, type WorkflowEditor, } from './input.js';
-export declare function trackCommand(commandName: string, version: string): Promise<void>;
+export { sanitizeWorkflowInput, sanitizeTelemetryContent, readSanitizedFile, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, MAX_ARTIFACT_BODY_LENGTH, type WorkflowEditor, } from './input.js';
+export { resolveTelemetryCommandPath, buildCommandTelemetryContext, type CommandTelemetryContext, type CommandCategory, } from './command-context.js';
+export { resolveCaller } from './caller.js';
+export declare function trackCommand(commandName: string, version: string, context?: CommandTelemetryContext): Promise<void>;
 export declare function trackEvent(event: string, properties?: Record<string, unknown>): Promise<void>;
 export declare function trackCommandFailed(command: string, error: unknown, errorCode?: string): Promise<void>;
 export declare function shutdown(): Promise<void>;
 /** @internal Test helper */
 export declare function resetTelemetryForTests(): void;
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackComprehensionRetakeRequired, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 export type { EntryPoint } from './marker.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -3,26 +3,34 @@
  */
 import { resolveTelemetryUserId } from './identity.js';
 import { captureEvent, shutdownClient, resetTelemetryClientForTests } from './client.js';
+import { sanitizeErrorForTelemetry } from './content.js';
 export async function canSendTelemetry() {
     const userId = await resolveTelemetryUserId({ prompt: false });
     return userId !== null;
 }
 export { TelemetryIdentityRequiredError, buildIdentityRequiredMessage, resolveTelemetryUserId, requireTelemetryIdentity, setupTelemetryIdentity, promptAndStoreTelemetryIdentity, getIdentityFilePath, validateUserId, ensureTelemetryIdentity, } from './identity.js';
 export { DEFAULT_POSTHOG_KEY, DEFAULT_POSTHOG_HOST, safeTelemetryFetch } from './client.js';
-export { sanitizeWorkflowInput, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, } from './input.js';
-export async function trackCommand(commandName, version) {
+export { sanitizeWorkflowInput, sanitizeTelemetryContent, readSanitizedFile, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, MAX_ARTIFACT_BODY_LENGTH, } from './input.js';
+export { resolveTelemetryCommandPath, buildCommandTelemetryContext, } from './command-context.js';
+export { resolveCaller } from './caller.js';
+export async function trackCommand(commandName, version, context) {
     await captureEvent('command_executed', {
         command: commandName,
         version,
+        ...(context?.change_name ? { change_name: context.change_name } : {}),
+        ...(context?.schema ? { schema: context.schema } : {}),
+        ...(context?.command_category ? { command_category: context.command_category } : {}),
     });
 }
 export async function trackEvent(event, properties = {}) {
     await captureEvent(event, properties);
 }
 export async function trackCommandFailed(command, error, errorCode) {
+    const errorDetails = sanitizeErrorForTelemetry(error);
     await trackEvent('command_failed', {
         command,
         error_code: errorCode ?? (error instanceof Error ? error.name : 'unknown'),
+        ...errorDetails,
     });
 }
 export async function shutdown() {
@@ -32,5 +40,6 @@ export async function shutdown() {
 export function resetTelemetryForTests() {
     resetTelemetryClientForTests();
 }
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackComprehensionRetakeRequired, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 //# sourceMappingURL=index.js.map

package/dist/telemetry/input.d.ts

@@ -1,6 +1,9 @@
 export declare const VALID_EDITORS: readonly ["cursor", "windsurf", "claude"];
 export type WorkflowEditor = (typeof VALID_EDITORS)[number];
+export declare const MAX_ARTIFACT_BODY_LENGTH = 8000;
+export declare function sanitizeTelemetryContent(text: string, maxLength?: number): string;
 export declare function sanitizeWorkflowInput(text: string): string;
+export declare function readSanitizedFile(filePath: string, maxLength?: number): Promise<string>;
 export declare function readWorkflowInputFile(filePath: string): Promise<string>;
 export declare function normalizeEditor(value?: string): WorkflowEditor | undefined;
 export declare function resolveWorkflowInput(options: {

package/dist/telemetry/input.js

@@ -4,21 +4,33 @@
 import { promises as fs } from 'fs';
 export const VALID_EDITORS = ['cursor', 'windsurf', 'claude'];
 const MAX_WORKFLOW_INPUT_LENGTH = 2000;
+export const MAX_ARTIFACT_BODY_LENGTH = 8000;
 const SECRET_PATTERNS = [
     /\bsk-[a-zA-Z0-9_-]{8,}\b/g,
     /\bghp_[a-zA-Z0-9]{20,}\b/g,
     /Bearer\s+[a-zA-Z0-9._-]+/gi,
 ];
-export function sanitizeWorkflowInput(text) {
+function redactSecrets(text) {
     let sanitized = text.trim();
     for (const pattern of SECRET_PATTERNS) {
         sanitized = sanitized.replace(pattern, '[redacted]');
     }
-    if (sanitized.length > MAX_WORKFLOW_INPUT_LENGTH) {
-        return sanitized.slice(0, MAX_WORKFLOW_INPUT_LENGTH);
+    return sanitized;
+}
+export function sanitizeTelemetryContent(text, maxLength = MAX_WORKFLOW_INPUT_LENGTH) {
+    const sanitized = redactSecrets(text);
+    if (sanitized.length > maxLength) {
+        return sanitized.slice(0, maxLength);
     }
     return sanitized;
 }
+export function sanitizeWorkflowInput(text) {
+    return sanitizeTelemetryContent(text, MAX_WORKFLOW_INPUT_LENGTH);
+}
+export async function readSanitizedFile(filePath, maxLength = MAX_ARTIFACT_BODY_LENGTH) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return sanitizeTelemetryContent(content, maxLength);
+}
 export async function readWorkflowInputFile(filePath) {
     const content = await fs.readFile(filePath, 'utf-8');
     return sanitizeWorkflowInput(content);

package/dist/telemetry/marker.d.ts

@@ -10,7 +10,14 @@ export interface ChangeTelemetryMarker {
     proposal_ready_emitted?: boolean;
     apply_ready_emitted?: boolean;
     artifact_hashes?: Record<string, string>;
+    artifact_body_cache?: Record<string, string>;
     revision_counts?: Record<string, number>;
+    comprehension_attempt_count?: number;
+    comprehension_failure_count?: number;
+    comprehension_gate_last_emitted?: {
+        passed: boolean;
+        best_score_percent?: number;
+    };
 }
 export declare function markerPath(changeDir: string): string;
 export declare function readMarker(changeDir: string): Promise<ChangeTelemetryMarker>;

package/dist/telemetry/workflow.d.ts

@@ -17,24 +17,26 @@ export declare function maybeEmitProposalReady(params: {
     schema: string;
     missingArtifacts: string[];
     artifactCount: number;
+    contextFiles?: Record<string, string[]>;
 }): Promise<void>;
 export declare function maybeEmitApplyReady(params: {
     changeDir: string;
     changeName: string;
     state: string;
-}): Promise<void>;
+    contextFiles?: Record<string, string[]>;
+}): Promise<boolean>;
 export declare function trackArtifactInstructions(params: {
     changeDir: string;
     changeName: string;
     artifactId: string;
     artifactWasDone: boolean;
+    artifactPaths?: string[];
 }): Promise<void>;
 export declare function trackArtifactContentChanges(params: {
     changeDir: string;
     changeName: string;
     contextFiles: Record<string, string[]>;
 }): Promise<void>;
-export declare function trackComprehensionRetakeRequired(changeName: string): Promise<void>;
 interface SpecDeltaInfo {
     capability: string;
     counts: {

package/dist/telemetry/workflow.js

@@ -6,6 +6,8 @@ import path from 'path';
 import { captureGitHead } from './git-stats.js';
 import { durationBetween, durationSince, hashFileAt, readMarker, totalRevisions, updateMarker, } from './marker.js';
 import { captureEvent } from './client.js';
+import { enrichFromMarker } from './comprehension.js';
+import { collectArtifactPathsMap, readPrimaryArtifactBody, readSanitizedFileAt, toChangeRelativePaths, } from './content.js';
 import { sanitizeWorkflowInput } from './input.js';
 const TRACKED_ARTIFACT_IDS = ['proposal', 'design', 'plan', 'tasks', 'specs'];
 export async function trackWorkflowStarted(params) {
@@ -37,6 +39,10 @@ export async function trackWorkflowStarted(params) {
         ...(params.editor ? { editor: params.editor } : {}),
     });
 }
+async function buildArtifactPathsSummary(changeDir, contextFiles) {
+    const paths = await collectArtifactPathsMap(changeDir, contextFiles);
+    return Object.keys(paths).length > 0 ? paths : undefined;
+}
 export async function maybeEmitProposalReady(params) {
     if (params.missingArtifacts.length > 0) {
         return;
@@ -51,35 +57,56 @@ export async function maybeEmitProposalReady(params) {
         proposal_ready_at: proposalReadyAt,
         proposal_ready_emitted: true,
     }));
-    await captureEvent('change_proposal_ready', {
+    const artifactPaths = params.contextFiles
+        ? await buildArtifactPathsSummary(params.changeDir, params.contextFiles)
+        : undefined;
+    const props = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         schema: params.schema,
         artifact_count: params.artifactCount,
         duration_since_start_ms: durationSince(marker.started_at),
+        ...(artifactPaths ? { artifact_paths: artifactPaths } : {}),
     });
+    await captureEvent('change_proposal_ready', props);
 }
 export async function maybeEmitApplyReady(params) {
     if (params.state !== 'ready') {
-        return;
+        return false;
     }
     const marker = await readMarker(params.changeDir);
     if (marker.apply_ready_emitted) {
-        return;
+        return false;
     }
     await updateMarker(params.changeDir, (current) => ({
         ...current,
         apply_ready_emitted: true,
     }));
-    await captureEvent('apply_ready', {
+    const artifactPaths = params.contextFiles
+        ? await buildArtifactPathsSummary(params.changeDir, params.contextFiles)
+        : undefined;
+    const props = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         duration_since_start_ms: durationSince(marker.started_at),
+        ...(artifactPaths ? { artifact_paths: artifactPaths } : {}),
     });
+    await captureEvent('apply_ready', props);
+    return true;
 }
 export async function trackArtifactInstructions(params) {
-    await captureEvent('artifact_instructions_requested', {
+    const relativePaths = params.artifactPaths && params.artifactPaths.length > 0
+        ? toChangeRelativePaths(params.changeDir, params.artifactPaths)
+        : undefined;
+    const artifactBody = params.artifactPaths && params.artifactPaths.length > 0
+        ? await readPrimaryArtifactBody(params.changeDir, params.artifactPaths)
+        : undefined;
+    const props = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         artifact_id: params.artifactId,
+        artifact_was_done: params.artifactWasDone,
+        ...(relativePaths ? { artifact_paths: relativePaths } : {}),
+        ...(artifactBody ? { artifact_body: artifactBody } : {}),
     });
+    await captureEvent('artifact_instructions_requested', props);
     if (!params.artifactWasDone) {
         return;
     }
@@ -90,11 +117,12 @@ export async function trackArtifactInstructions(params) {
         return { ...current, revision_counts: revisionCounts };
     });
     const revisionNumber = marker.revision_counts?.[params.artifactId] ?? 1;
-    await captureEvent('artifact_revision_requested', {
+    const revisionProps = await enrichFromMarker(params.changeDir, {
         change_name: params.changeName,
         artifact_id: params.artifactId,
         revision_number: revisionNumber,
     });
+    await captureEvent('artifact_revision_requested', revisionProps);
 }
 async function hashArtifactFiles(changeDir, contextFiles) {
     const hashes = {};
@@ -116,6 +144,20 @@ async function hashArtifactFiles(changeDir, contextFiles) {
     }
     return hashes;
 }
+async function refreshArtifactBodyCache(changeDir, contextFiles) {
+    const cache = {};
+    for (const artifactId of TRACKED_ARTIFACT_IDS) {
+        const paths = contextFiles[artifactId];
+        if (!paths?.length) {
+            continue;
+        }
+        const body = await readPrimaryArtifactBody(changeDir, paths);
+        if (body) {
+            cache[artifactId] = body;
+        }
+    }
+    return cache;
+}
 export async function trackArtifactContentChanges(params) {
     const currentHashes = await hashArtifactFiles(params.changeDir, params.contextFiles);
     if (Object.keys(currentHashes).length === 0) {
@@ -123,31 +165,36 @@ export async function trackArtifactContentChanges(params) {
     }
     const marker = await readMarker(params.changeDir);
     const previousHashes = marker.artifact_hashes ?? {};
+    const previousBodies = marker.artifact_body_cache ?? {};
     for (const [artifactId, hash] of Object.entries(currentHashes)) {
         const previous = previousHashes[artifactId];
         if (previous && previous !== hash) {
+            const paths = params.contextFiles[artifactId] ?? [];
+            const bodyAfter = paths[0] ? await readSanitizedFileAt(paths[0]) : undefined;
+            const bodyBefore = previousBodies[artifactId];
             const updated = await updateMarker(params.changeDir, (current) => {
                 const revisionCounts = { ...(current.revision_counts ?? {}) };
                 revisionCounts[artifactId] = (revisionCounts[artifactId] ?? 0) + 1;
                 return { ...current, revision_counts: revisionCounts };
             });
-            await captureEvent('artifact_content_changed', {
+            const changeProps = await enrichFromMarker(params.changeDir, {
                 change_name: params.changeName,
                 artifact_id: artifactId,
                 change_count: updated.revision_counts?.[artifactId] ?? 1,
+                artifact_paths: toChangeRelativePaths(params.changeDir, paths),
+                ...(bodyBefore ? { body_before: bodyBefore } : {}),
+                ...(bodyAfter ? { body_after: bodyAfter } : {}),
             });
+            await captureEvent('artifact_content_changed', changeProps);
         }
     }
+    const bodyCache = await refreshArtifactBodyCache(params.changeDir, params.contextFiles);
     await updateMarker(params.changeDir, (current) => ({
         ...current,
         artifact_hashes: { ...(current.artifact_hashes ?? {}), ...currentHashes },
+        artifact_body_cache: { ...(current.artifact_body_cache ?? {}), ...bodyCache },
     }));
 }
-export async function trackComprehensionRetakeRequired(changeName) {
-    await captureEvent('comprehension_retake_required', {
-        change_name: changeName,
-    });
-}
 async function countDeltaSpecLines(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf-8');

package/package.json

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