@codewalla_india/openspec 1.3.0 → 1.3.2

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

@@ -1,19 +1,19 @@
-## Context
-
-<!-- Background and current state -->
-
-## Goals / Non-Goals
-
-**Goals:**
-<!-- What this design aims to achieve -->
-
-**Non-Goals:**
-<!-- What is explicitly out of scope -->
-
-## Decisions
-
-<!-- Key design decisions and rationale -->
-
-## Risks / Trade-offs
-
-<!-- Known risks and trade-offs -->
+## Context
+
+<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions with rationale and alternatives considered -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->

package/schemas/spec-driven/templates/plan-template.md

@@ -0,0 +1,91 @@
+## Code Map
+
+<!-- List all files that will be created, modified, or deleted for this change -->
+
+### Files to Create
+<!-- List new files to be created with brief descriptions -->
+<!-- Example:
+- `src/core/new-feature.ts` - Core implementation of new feature
+- `src/core/new-feature.test.ts` - Unit tests for new feature
+-->
+
+### Files to Modify
+<!-- List existing files that will be modified with brief descriptions -->
+<!-- Example:
+- `src/core/index.ts` - Export new feature module
+- `src/cli/commands.ts` - Add CLI command for new feature
+-->
+
+### Files to Delete
+<!-- List files that will be removed (if any) -->
+<!-- Example:
+- `src/legacy/old-feature.ts` - Remove deprecated feature
+-->
+
+## Implementation Order
+
+<!-- Sequence the implementation work at file/module level -->
+<!-- Use numbered steps with file references in parentheses -->
+<!-- Example:
+
+1. **Core Implementation** (new-feature.ts)
+   - Implement primary data structures
+   - Add main function logic
+   - Handle edge cases
+
+2. **CLI Integration** (commands.ts)
+   - Add command registration
+   - Implement command handler
+   - Add help text
+
+3. **Testing** (new-feature.test.ts)
+   - Write unit tests
+   - Add integration tests
+   - Verify coverage
+-->
+
+## Test Plan
+
+<!-- Describe how to verify the change -->
+<!-- Include test types: unit, integration, e2e, manual -->
+<!-- Example:
+
+### Unit Tests
+- Test core function with valid inputs
+- Test error handling for invalid inputs
+- Test edge cases
+
+### Integration Tests
+- Test CLI command with real filesystem
+- Test integration with existing modules
+
+### Manual Tests
+- Verify CLI command works as expected
+- Check error messages are clear
+-->
+
+## Risks
+
+<!-- Identify known risks with mitigations -->
+<!-- Format: [Risk] → Mitigation -->
+<!-- Example:
+
+**Breaking Change Risk**
+- [Risk] Existing users may rely on old behavior
+- [Mitigation] Provide migration guide, add deprecation warning
+
+**Performance Risk**
+- [Risk] New feature may slow down existing operations
+- [Mitigation] Add performance tests, optimize hot paths
+-->
+
+## Done Definition
+
+<!-- Define objective criteria for completion -->
+<!-- Example:
+- All unit tests passing
+- All integration tests passing
+- Documentation updated
+- Error messages are clear and actionable
+- Performance requirements met
+-->

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

@@ -1,24 +1,29 @@
-## Why
-
-<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
-
-## What Changes
-
-<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
-
-## Capabilities
-
-### New Capabilities
-<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
-- `<name>`: <brief description of what this capability covers>
-
-### Modified Capabilities
-<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
-     Only list here if spec-level behavior changes. Each needs a delta spec file.
-     Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
-- `<existing-name>`: <what requirement is changing>
-
-## Impact
-
-<!-- Affected code, APIs, dependencies, systems -->
-<!-- If this change maps to a Jira ticket, note it here (e.g., Jira: CW-1234). Do NOT use the ticket key as a capability name. -->
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
+     (e.g., user-auth or identity/user-auth) that follow the project's existing
+     spec organization. Each creates specs/<capability-path>/spec.md. -->
+- `<capability-path>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use the exact existing path under openspec/specs/. Leave empty if no requirement
+     changes. A change with no capabilities at all (pure refactor, tooling, docs)
+     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
+     a zero-delta change without that marker. Do not invent a requirement just to
+     satisfy validation. -->
+- `<existing-capability-path>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

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

@@ -1,8 +1,11 @@
-## ADDED Requirements
-
-### Requirement: <!-- requirement name -->
-<!-- requirement text -->
-
-#### Scenario: <!-- scenario name -->
-- **WHEN** <!-- condition -->
-- **THEN** <!-- expected outcome -->
+## Purpose
+<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
+
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

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

@@ -1,9 +1,9 @@
-## 1. <!-- Task Group Name -->
-
-- [ ] 1.1 <!-- Task description -->
-- [ ] 1.2 <!-- Task description -->
-
-## 2. <!-- Task Group Name -->
-
-- [ ] 2.1 <!-- Task description -->
-- [ ] 2.2 <!-- Task description -->
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->

package/scripts/postinstall.js

@@ -1,83 +1,83 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script that hints about shell completions
- *
- * Completion installation is opt-in: the user must run
- * `openspec completion install` explicitly. This script only
- * prints a one-line tip after npm install.
- *
- * The tip is suppressed when:
- * - CI=true environment variable is set
- * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
- * - dist/ directory doesn't exist (dev setup scenario)
- *
- * The script never fails npm install - all errors are caught and handled gracefully.
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Check if we should skip installation
- */
-function shouldSkipInstallation() {
-  // Skip in CI environments
-  if (process.env.CI === 'true' || process.env.CI === '1') {
-    return { skip: true, reason: 'CI environment detected' };
-  }
-
-  // Skip if user opted out
-  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
-    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
-  }
-
-  return { skip: false };
-}
-
-/**
- * Check if dist/ directory exists
- */
-async function distExists() {
-  const distPath = path.join(__dirname, '..', 'dist');
-  try {
-    const stat = await fs.stat(distPath);
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Main function
- */
-async function main() {
-  try {
-    // Check if we should skip
-    const skipCheck = shouldSkipInstallation();
-    if (skipCheck.skip) {
-      // Silent skip - no output
-      return;
-    }
-
-    // Check if dist/ exists (skip silently if not - expected during dev setup)
-    if (!(await distExists())) {
-      return;
-    }
-
-    // Completions are opt-in — just print a hint
-    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
-  } catch (error) {
-    // Fail gracefully - never break npm install
-  }
-}
-
-// Run main and handle any unhandled errors
-main().catch(() => {
-  // Silent failure - never break npm install
-  process.exit(0);
-});
+#!/usr/bin/env node
+
+/**
+ * Postinstall script that hints about shell completions
+ *
+ * Completion installation is opt-in: the user must run
+ * `openspec completion install` explicitly. This script only
+ * prints a one-line tip after npm install.
+ *
+ * The tip is suppressed when:
+ * - CI=true environment variable is set
+ * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ *
+ * The script never fails npm install - all errors are caught and handled gracefully.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Check if we should skip installation
+ */
+function shouldSkipInstallation() {
+  // Skip in CI environments
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return { skip: true, reason: 'CI environment detected' };
+  }
+
+  // Skip if user opted out
+  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
+    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
+  }
+
+  return { skip: false };
+}
+
+/**
+ * Check if dist/ directory exists
+ */
+async function distExists() {
+  const distPath = path.join(__dirname, '..', 'dist');
+  try {
+    const stat = await fs.stat(distPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  try {
+    // Check if we should skip
+    const skipCheck = shouldSkipInstallation();
+    if (skipCheck.skip) {
+      // Silent skip - no output
+      return;
+    }
+
+    // Check if dist/ exists (skip silently if not - expected during dev setup)
+    if (!(await distExists())) {
+      return;
+    }
+
+    // Completions are opt-in — just print a hint
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  } catch (error) {
+    // Fail gracefully - never break npm install
+  }
+}
+
+// Run main and handle any unhandled errors
+main().catch(() => {
+  // Silent failure - never break npm install
+  process.exit(0);
+});

package/dist/core/command-generation/adapters/codex.d.ts

@@ -1,16 +0,0 @@
-/**
- * Codex Command Adapter
- *
- * Formats commands for Codex following its frontmatter specification.
- * Codex custom prompts live in the global home directory (~/.codex/prompts/)
- * and are not shared through the repository. The CODEX_HOME env var can
- * override the default ~/.codex location.
- */
-import type { ToolCommandAdapter } from '../types.js';
-/**
- * Codex adapter for command generation.
- * File path: <CODEX_HOME>/prompts/opsx-<id>.md (absolute, global)
- * Frontmatter: description, argument-hint
- */
-export declare const codexAdapter: ToolCommandAdapter;
-//# sourceMappingURL=codex.d.ts.map

package/dist/core/command-generation/adapters/codex.js

@@ -1,39 +0,0 @@
-/**
- * Codex Command Adapter
- *
- * Formats commands for Codex following its frontmatter specification.
- * Codex custom prompts live in the global home directory (~/.codex/prompts/)
- * and are not shared through the repository. The CODEX_HOME env var can
- * override the default ~/.codex location.
- */
-import os from 'os';
-import path from 'path';
-/**
- * Returns the Codex home directory.
- * Respects the CODEX_HOME env var, defaulting to ~/.codex.
- */
-function getCodexHome() {
-    const envHome = process.env.CODEX_HOME?.trim();
-    return path.resolve(envHome ? envHome : path.join(os.homedir(), '.codex'));
-}
-/**
- * Codex adapter for command generation.
- * File path: <CODEX_HOME>/prompts/opsx-<id>.md (absolute, global)
- * Frontmatter: description, argument-hint
- */
-export const codexAdapter = {
-    toolId: 'codex',
-    getFilePath(commandId) {
-        return path.join(getCodexHome(), 'prompts', `opsx-${commandId}.md`);
-    },
-    formatFile(content) {
-        return `---
-description: ${content.description}
-argument-hint: command arguments
----
-
-${content.body}
-`;
-    },
-};
-//# sourceMappingURL=codex.js.map

package/dist/core/command-generation/adapters/windsurf.d.ts

@@ -1,14 +0,0 @@
-/**
- * Windsurf Command Adapter
- *
- * Formats commands for Windsurf following its frontmatter specification.
- * Windsurf uses a similar format to Claude but may have different conventions.
- */
-import type { ToolCommandAdapter } from '../types.js';
-/**
- * Windsurf adapter for command generation.
- * File path: .windsurf/workflows/opsx-<id>.md
- * Frontmatter: name, description, category, tags
- */
-export declare const windsurfAdapter: ToolCommandAdapter;
-//# sourceMappingURL=windsurf.d.ts.map

package/dist/core/command-generation/adapters/windsurf.js

@@ -1,38 +0,0 @@
-/**
- * Windsurf Command Adapter
- *
- * Formats commands for Windsurf following its frontmatter specification.
- * Windsurf uses a similar format to Claude but may have different conventions.
- */
-import path from 'path';
-import { escapeYamlValue } from '../yaml.js';
-/**
- * Formats a tags array as a YAML array with proper escaping.
- */
-function formatTagsArray(tags) {
-    const escapedTags = tags.map((tag) => escapeYamlValue(tag));
-    return `[${escapedTags.join(', ')}]`;
-}
-/**
- * Windsurf adapter for command generation.
- * File path: .windsurf/workflows/opsx-<id>.md
- * Frontmatter: name, description, category, tags
- */
-export const windsurfAdapter = {
-    toolId: 'windsurf',
-    getFilePath(commandId) {
-        return path.join('.windsurf', 'workflows', `opsx-${commandId}.md`);
-    },
-    formatFile(content) {
-        return `---
-name: ${escapeYamlValue(content.name)}
-description: ${escapeYamlValue(content.description)}
-category: ${escapeYamlValue(content.category)}
-tags: ${formatTagsArray(content.tags)}
----
-
-${content.body}
-`;
-    },
-};
-//# sourceMappingURL=windsurf.js.map

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

@@ -1,20 +0,0 @@
-import type { ProjectConfig } from '../project-config.js';
-export interface ComprehensionConfig {
-    enabled: boolean;
-    thresholdPercent: number;
-    minQuestions: number;
-    maxQuestions: number;
-}
-export declare const DEFAULT_COMPREHENSION_CONFIG: ComprehensionConfig;
-export interface ComprehensionConfigInput {
-    enabled?: boolean;
-    threshold_percent?: number;
-    min_questions?: number;
-    max_questions?: number;
-}
-/**
- * Resolve comprehension settings from project config.
- * Defaults apply when config is missing or fields are absent.
- */
-export declare function resolveComprehensionConfig(projectConfig: ProjectConfig | null | undefined): ComprehensionConfig;
-//# sourceMappingURL=config.d.ts.map

package/dist/core/comprehension/config.js

@@ -1,23 +0,0 @@
-export const DEFAULT_COMPREHENSION_CONFIG = {
-    enabled: true,
-    thresholdPercent: 80,
-    minQuestions: 5,
-    maxQuestions: 10,
-};
-/**
- * Resolve comprehension settings from project config.
- * Defaults apply when config is missing or fields are absent.
- */
-export function resolveComprehensionConfig(projectConfig) {
-    const raw = projectConfig?.comprehension;
-    if (!raw) {
-        return { ...DEFAULT_COMPREHENSION_CONFIG };
-    }
-    return {
-        enabled: raw.enabled ?? DEFAULT_COMPREHENSION_CONFIG.enabled,
-        thresholdPercent: raw.thresholdPercent ?? DEFAULT_COMPREHENSION_CONFIG.thresholdPercent,
-        minQuestions: raw.minQuestions ?? DEFAULT_COMPREHENSION_CONFIG.minQuestions,
-        maxQuestions: raw.maxQuestions ?? DEFAULT_COMPREHENSION_CONFIG.maxQuestions,
-    };
-}
-//# sourceMappingURL=config.js.map

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

@@ -1,14 +0,0 @@
-export interface ApplyArtifactFingerprintInput {
-    specPaths: string[];
-    tasksPath?: string | null;
-    planPath?: string | null;
-}
-/**
- * SHA-256 fingerprint of delta specs and optional plan/tasks file contents.
- */
-export declare function fingerprintApplyArtifacts(input: ApplyArtifactFingerprintInput): string;
-/**
- * @deprecated Use fingerprintApplyArtifacts
- */
-export declare function fingerprintSpecFiles(specPaths: string[], tasksPath?: string | null): string;
-//# sourceMappingURL=fingerprint.d.ts.map

package/dist/core/comprehension/fingerprint.js

@@ -1,33 +0,0 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-function hashFileContent(hash, label, filePath) {
-    hash.update(`${label}:`);
-    hash.update(filePath);
-    hash.update('\0');
-    hash.update(readFileSync(filePath, 'utf-8'));
-    hash.update('\0');
-}
-/**
- * SHA-256 fingerprint of delta specs and optional plan/tasks file contents.
- */
-export function fingerprintApplyArtifacts(input) {
-    const sorted = [...input.specPaths].sort();
-    const hash = createHash('sha256');
-    for (const specPath of sorted) {
-        hashFileContent(hash, 'spec', specPath);
-    }
-    if (input.planPath && existsSync(input.planPath)) {
-        hashFileContent(hash, 'plan', input.planPath);
-    }
-    if (input.tasksPath && existsSync(input.tasksPath)) {
-        hashFileContent(hash, 'tasks', input.tasksPath);
-    }
-    return hash.digest('hex');
-}
-/**
- * @deprecated Use fingerprintApplyArtifacts
- */
-export function fingerprintSpecFiles(specPaths, tasksPath) {
-    return fingerprintApplyArtifacts({ specPaths, tasksPath });
-}
-//# sourceMappingURL=fingerprint.js.map

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

@@ -1,57 +0,0 @@
-import type { ProjectConfig } from '../project-config.js';
-import { type ComprehensionPassRecord } from './pass-record.js';
-import { OPTIONS_PER_QUESTION, type ArtifactPresence, type QuestionAllocation } from './stats.js';
-export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, type ComprehensionConfig, } from './config.js';
-export { fingerprintApplyArtifacts, fingerprintSpecFiles } from './fingerprint.js';
-export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, type ComprehensionPassRecord, } from './pass-record.js';
-export { computeQuestionAllocation, computeQuestionCount, computeSpecStats, countSpecStats, OPTIONS_PER_QUESTION, type ArtifactPresence, type QuestionAllocation, type QuestionCategory, type SpecStats, } from './stats.js';
-export interface ComprehensionGateInfo {
-    required: boolean;
-    passed: boolean;
-    thresholdPercent: number;
-    bestScorePercent?: number;
-    questionCount: number;
-    questionAllocation: QuestionAllocation;
-    optionsPerQuestion: number;
-    requirementCount: number;
-    scenarioCount: number;
-    pendingTaskCount: number;
-    attempts?: number;
-}
-export interface ComprehensionGateOptions {
-    tasksPath?: string | null;
-    planPath?: string | null;
-    pendingTaskCount?: number;
-    artifactPresence?: ArtifactPresence;
-}
-export interface ComprehensionGateResult {
-    active: boolean;
-    passed: boolean;
-    info?: ComprehensionGateInfo;
-}
-/**
- * Evaluate whether apply is blocked by the comprehension gate.
- */
-export declare function checkComprehensionGate(changeDir: string, specPaths: string[], projectConfig: ProjectConfig | null | undefined, gateOptions?: ComprehensionGateOptions): ComprehensionGateResult;
-export declare class ComprehensionPassError extends Error {
-    readonly score: number;
-    readonly threshold: number;
-    constructor(message: string, score: number, threshold: number);
-}
-/**
- * Record a comprehension pass after quiz success.
- */
-export declare function recordComprehensionPass(input: {
-    changeDir: string;
-    specPaths: string[];
-    tasksPath?: string | null;
-    planPath?: string | null;
-    projectConfig: ProjectConfig | null | undefined;
-    scorePercent: number;
-    attempt: number;
-    questionCount: number;
-    pendingTaskCount?: number;
-    artifactPresence?: ArtifactPresence;
-}): ComprehensionPassRecord;
-export { OPTIONS_PER_QUESTION as comprehensionOptionsPerQuestion };
-//# sourceMappingURL=index.d.ts.map