@codewalla_india/openspec 1.3.1 → 1.3.3

package/dist/core/validation/constants.d.ts

@@ -19,6 +19,9 @@ export declare const VALIDATION_MESSAGES: {
     readonly CHANGE_WHY_TOO_LONG: "Why section should not exceed 1000 characters";
     readonly CHANGE_WHAT_EMPTY: "What Changes section cannot be empty";
     readonly CHANGE_NO_DELTAS: "Change must have at least one delta";
+    readonly CHANGE_SKIP_SPECS_CONFLICT: "skip_specs is set in .openspec.yaml but spec files exist under specs/. Remove skip_specs or delete the delta spec files";
+    readonly CHANGE_SKIP_SPECS_ACCEPTED: "skip_specs is set in .openspec.yaml: change declares no spec-level behavior changes, zero deltas accepted";
+    readonly CHANGE_SKIP_SPECS_INVALID_METADATA: "skip_specs is set but .openspec.yaml is not valid change metadata, so the marker is not honored. Fix the metadata";
     readonly CHANGE_TOO_MANY_DELTAS: "Consider splitting changes with more than 10 deltas";
     readonly DELTA_SPEC_EMPTY: "Spec name cannot be empty";
     readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
@@ -26,7 +29,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";
-    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
+    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set \"skip_specs: true\" in the change's .openspec.yaml instead. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
     readonly GUIDE_MISSING_SPEC_SECTIONS: "Missing required sections. Expected headers: \"## Purpose\" and \"## Requirements\". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...";
     readonly GUIDE_MISSING_CHANGE_SECTIONS: "Missing required sections. Expected headers: \"## Why\" and \"## What Changes\". Ensure deltas are documented in specs/ using delta headers.";
     readonly GUIDE_SCENARIO_FORMAT: "Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...";

package/dist/core/validation/constants.js

@@ -23,6 +23,9 @@ export const VALIDATION_MESSAGES = {
     CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
     CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
     CHANGE_NO_DELTAS: 'Change must have at least one delta',
+    CHANGE_SKIP_SPECS_CONFLICT: 'skip_specs is set in .openspec.yaml but spec files exist under specs/. Remove skip_specs or delete the delta spec files',
+    CHANGE_SKIP_SPECS_ACCEPTED: 'skip_specs is set in .openspec.yaml: change declares no spec-level behavior changes, zero deltas accepted',
+    CHANGE_SKIP_SPECS_INVALID_METADATA: 'skip_specs is set but .openspec.yaml is not valid change metadata, so the marker is not honored. Fix the metadata',
     CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
     DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
     DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
@@ -32,7 +35,7 @@ export const VALIDATION_MESSAGES = {
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
     // Guidance snippets (appended to primary messages for remediation)
-    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set "skip_specs: true" in the change\'s .openspec.yaml instead. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
     GUIDE_MISSING_SPEC_SECTIONS: 'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
     GUIDE_MISSING_CHANGE_SECTIONS: 'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
     GUIDE_SCENARIO_FORMAT: 'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',

package/dist/core/validation/plan-validator.d.ts

@@ -0,0 +1,8 @@
+export interface PlanValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    duration: number;
+}
+export declare function validatePlan(planPath: string): PlanValidationResult;
+//# sourceMappingURL=plan-validator.d.ts.map

package/dist/core/validation/plan-validator.js

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+const REQUIRED_SECTIONS = [
+    'Code Map',
+    'Implementation Order',
+    'Test Plan',
+    'Risks',
+    'Done Definition',
+];
+export function validatePlan(planPath) {
+    const startTime = performance.now();
+    const errors = [];
+    const warnings = [];
+    try {
+        const content = readFileSync(planPath, 'utf-8');
+        const lines = content.split('\n');
+        // Check for required sections
+        for (const section of REQUIRED_SECTIONS) {
+            const sectionPattern = new RegExp(`^##\\s+${section}`, 'i');
+            const hasSection = lines.some(line => sectionPattern.test(line.trim()));
+            if (!hasSection) {
+                errors.push(`Missing required section: "${section}"`);
+            }
+        }
+        // Performance check
+        const duration = performance.now() - startTime;
+        if (duration > 2000) {
+            warnings.push(`Validation took ${duration.toFixed(0)}ms (exceeds 2 second limit)`);
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            duration,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            errors: [`Failed to read plan file: ${error instanceof Error ? error.message : String(error)}`],
+            warnings: [],
+            duration: performance.now() - startTime,
+        };
+    }
+}
+//# sourceMappingURL=plan-validator.js.map

package/dist/core/validation/task-numbering.d.ts

@@ -0,0 +1,16 @@
+export interface TaskNumberingDocument {
+    path: string;
+    content: string;
+}
+export interface TaskNumberingIssue {
+    path: string;
+    line: number;
+    message: string;
+}
+/**
+ * Finds ambiguous task references across the task files tracked by a change.
+ * Numbering is interpreted only inside `## N.` groups. Unnumbered sections,
+ * unnumbered tasks, and files without numbered groups are intentionally ignored.
+ */
+export declare function findTaskNumberingIssues(documents: readonly TaskNumberingDocument[]): TaskNumberingIssue[];
+//# sourceMappingURL=task-numbering.d.ts.map

package/dist/core/validation/task-numbering.js

@@ -0,0 +1,57 @@
+import { parseTaskLines } from '../../utils/task-progress.js';
+const LEVEL_TWO_HEADING = /^ {0,3}##(?!#)(?:[ \t]+|[ \t]*\r?$)/;
+const NUMBERED_GROUP_HEADING = /^ {0,3}##[ \t]+(\d+)\.(?:[ \t]|\r?$)/;
+const TASK_ID = /^(\d+(?:\.\d+)+(?:[A-Za-z]+)?)(?=\s|$)/;
+/**
+ * Finds ambiguous task references across the task files tracked by a change.
+ * Numbering is interpreted only inside `## N.` groups. Unnumbered sections,
+ * unnumbered tasks, and files without numbered groups are intentionally ignored.
+ */
+export function findTaskNumberingIssues(documents) {
+    const issues = [];
+    const firstLocationById = new Map();
+    for (const document of documents) {
+        const lines = document.content.split('\n');
+        if (!lines.some((line) => NUMBERED_GROUP_HEADING.test(line)))
+            continue;
+        let currentGroup;
+        lines.forEach((line, index) => {
+            if (LEVEL_TWO_HEADING.test(line)) {
+                currentGroup = line.match(NUMBERED_GROUP_HEADING)?.[1];
+            }
+            if (currentGroup === undefined)
+                return;
+            const task = parseTaskLines(line)[0];
+            const id = task?.description.match(TASK_ID)?.[1];
+            if (!id)
+                return;
+            const lineNumber = index + 1;
+            const taskGroup = id.split('.')[0];
+            const normalizedTaskGroup = taskGroup.replace(/^0+(?=\d)/, '');
+            const normalizedCurrentGroup = currentGroup.replace(/^0+(?=\d)/, '');
+            if (normalizedTaskGroup !== normalizedCurrentGroup) {
+                issues.push({
+                    path: document.path,
+                    line: lineNumber,
+                    message: `Task "${id}" is under group ${currentGroup}, but its leading number points to group ${taskGroup}. Move it to group ${taskGroup} or renumber it.`,
+                });
+            }
+            const firstLocation = firstLocationById.get(id);
+            if (firstLocation !== undefined) {
+                const firstDeclaration = firstLocation.path === document.path
+                    ? `on line ${firstLocation.line}`
+                    : `in ${firstLocation.path} on line ${firstLocation.line}`;
+                issues.push({
+                    path: document.path,
+                    line: lineNumber,
+                    message: `Task ID "${id}" is duplicated; it was first declared ${firstDeclaration}.`,
+                });
+            }
+            else {
+                firstLocationById.set(id, { path: document.path, line: lineNumber });
+            }
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=task-numbering.js.map

package/dist/core/validation/validator.d.ts

@@ -12,12 +12,36 @@ export declare class Validator {
      * Validate delta-formatted spec files under a change directory.
      * Enforces:
      * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
+     * - ADDED/MODIFIED: each requirement has at least one scenario; missing
+     *   English SHALL/MUST keywords are guidance unless strict mode is enabled
      * - REMOVED: names only; no scenario/description required
      * - RENAMED: pairs well-formed
      * - No duplicates within sections; no cross-section conflicts per spec
+     *
+     * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
+     * against the current main specs for the scenario loss archive refuses to
+     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
+     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * option keeps existing library and archive callers behaving as before.
+     */
+    validateChangeDeltaSpecs(changeDir: string, options?: {
+        mainSpecsDir?: string;
+        projectRoot?: string;
+    }): Promise<ValidationReport>;
+    private collectTaskNumberingIssues;
+    /**
+     * Report MODIFIED requirements whose block omits a scenario the main spec
+     * still carries. Uses the same comparison archive applies, so validate can
+     * only report what archive would refuse.
+     *
+     * Silent when the main spec or the requirement header is absent: applying a
+     * MODIFIED against a base that is not there yet is a different failure (a
+     * sister change still in flight is the legitimate case), and archive is the
+     * gate for it. A spec that exists but cannot be read is not absent, though —
+     * archive aborts on it, so reporting it beats calling the change valid.
      */
-    validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
+    private findScenarioLossIssues;
+    private formatInvalidMarkerMessage;
     private convertZodErrors;
     private applySpecRules;
     private applyChangeRules;
@@ -28,7 +52,7 @@ export declare class Validator {
     private extractRequirementText;
     private containsShallOrMust;
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
+     * Build a message for a requirement block whose body lacks SHALL/MUST.
      *
      * When the SHALL/MUST keyword already appears in the requirement header (e.g.
      * `### Requirement: The system SHALL ...`) the original generic error