@codewalla_india/openspec 1.3.1 → 1.3.2

package/dist/core/modify/history-tracker.js

@@ -0,0 +1,114 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Tracks modification history in the change marker (.openspec.yaml).
+ */
+export class HistoryTracker {
+    changeRoot;
+    constructor(changeRoot) {
+        this.changeRoot = changeRoot;
+    }
+    /**
+     * Records a modification event in the change marker.
+     */
+    async recordModification(changeName, modifiedArtifacts, intent) {
+        const markerPath = join(this.changeRoot, changeName, '.openspec.yaml');
+        try {
+            const content = await readFile(markerPath, 'utf-8');
+            const marker = this.parseMarker(content);
+            // Add new modification record
+            marker.modifyHistory.push({
+                timestamp: new Date().toISOString(),
+                modifiedArtifacts,
+                intent,
+            });
+            // Write back
+            await writeFile(markerPath, this.stringifyMarker(marker), 'utf-8');
+        }
+        catch (error) {
+            // If marker doesn't exist, create it
+            if (error.code === 'ENOENT') {
+                const marker = {
+                    modifyHistory: [{
+                            timestamp: new Date().toISOString(),
+                            modifiedArtifacts,
+                            intent,
+                        }],
+                };
+                await writeFile(markerPath, this.stringifyMarker(marker), 'utf-8');
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Gets the modification history for a change.
+     */
+    async getHistory(changeName) {
+        const markerPath = join(this.changeRoot, changeName, '.openspec.yaml');
+        try {
+            const content = await readFile(markerPath, 'utf-8');
+            const marker = this.parseMarker(content);
+            return marker.modifyHistory || [];
+        }
+        catch (error) {
+            // If marker doesn't exist, return empty history
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Parses the change marker YAML content.
+     * In a full implementation, this would use a proper YAML parser.
+     */
+    parseMarker(content) {
+        // Simplified parsing - in production, use a YAML library
+        const lines = content.split('\n');
+        const marker = { modifyHistory: [] };
+        let inHistory = false;
+        let currentRecord = {};
+        for (const line of lines) {
+            if (line.trim() === 'modifyHistory:') {
+                inHistory = true;
+                continue;
+            }
+            if (inHistory) {
+                if (line.trim().startsWith('- timestamp:')) {
+                    if (currentRecord.timestamp && currentRecord.modifiedArtifacts && currentRecord.intent) {
+                        marker.modifyHistory.push(currentRecord);
+                    }
+                    currentRecord = { timestamp: line.split(':')[1].trim() };
+                }
+                else if (line.trim().startsWith('modifiedArtifacts:')) {
+                    currentRecord.modifiedArtifacts = line.split(':')[1].trim().split(',').map(s => s.trim());
+                }
+                else if (line.trim().startsWith('intent:')) {
+                    currentRecord.intent = line.split(':')[1].trim();
+                }
+            }
+        }
+        // Add the last record
+        if (currentRecord.timestamp && currentRecord.modifiedArtifacts && currentRecord.intent) {
+            marker.modifyHistory.push(currentRecord);
+        }
+        return marker;
+    }
+    /**
+     * Stringifies the change marker to YAML format.
+     * In a full implementation, this would use a proper YAML stringifier.
+     */
+    stringifyMarker(marker) {
+        // Simplified YAML generation - in production, use a YAML library
+        let yaml = 'modifyHistory:\n';
+        for (const record of marker.modifyHistory) {
+            yaml += `  - timestamp: ${record.timestamp}\n`;
+            yaml += `    modifiedArtifacts: [${record.modifiedArtifacts.join(', ')}]\n`;
+            yaml += `    intent: ${record.intent}\n`;
+        }
+        return yaml;
+    }
+}
+//# sourceMappingURL=history-tracker.js.map

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

@@ -0,0 +1,7 @@
+export { DependencyPropagator } from './dependency-propagator.js';
+export type { DependencyPropagationResult } from './dependency-propagator.js';
+export { ConflictDetector } from './conflict-detector.js';
+export type { ConflictInfo } from './conflict-detector.js';
+export { HistoryTracker } from './history-tracker.js';
+export type { ModificationRecord, ChangeMarker } from './history-tracker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/modify/index.js

@@ -0,0 +1,7 @@
+// Dependency Propagator
+export { DependencyPropagator } from './dependency-propagator.js';
+// Conflict Detector
+export { ConflictDetector } from './conflict-detector.js';
+// History Tracker
+export { HistoryTracker } from './history-tracker.js';
+//# sourceMappingURL=index.js.map

package/dist/core/onboarding-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Onboarding command hints.
+ *
+ * The commands shown to a user after setup must be limited to the workflows
+ * their profile actually installs, otherwise we advertise slash commands that
+ * were correctly never generated.
+ *
+ * This module decides WHICH hints to show. How each one is spelled for a given
+ * tool — command, skill, or a tool-specific skill prefix — is decided by
+ * src/utils/command-references.ts at the call site.
+ */
+import type { WorkflowId } from './profiles.js';
+export type OnboardingCommand = {
+    workflow: WorkflowId;
+    command: string;
+    description: string;
+};
+/**
+ * Longest description the welcome screen can render. It shows these beside a
+ * 24-column art column and only animates at MIN_WIDTH (60) columns or wider; a
+ * longer line wraps, and the animation's cursor-up count assumes unwrapped
+ * lines. See src/ui/welcome-screen.ts.
+ */
+export declare const DESCRIPTION_BUDGET = 17;
+/**
+ * Returns the onboarding hints for the installed workflows, in lifecycle order.
+ * Returns an empty array when none of the onboarding workflows are installed.
+ */
+export declare function getOnboardingCommands(workflows: readonly string[]): OnboardingCommand[];
+//# sourceMappingURL=onboarding-commands.d.ts.map

package/dist/core/onboarding-commands.js

@@ -0,0 +1,38 @@
+/**
+ * Onboarding command hints.
+ *
+ * The commands shown to a user after setup must be limited to the workflows
+ * their profile actually installs, otherwise we advertise slash commands that
+ * were correctly never generated.
+ *
+ * This module decides WHICH hints to show. How each one is spelled for a given
+ * tool — command, skill, or a tool-specific skill prefix — is decided by
+ * src/utils/command-references.ts at the call site.
+ */
+/**
+ * Longest description the welcome screen can render. It shows these beside a
+ * 24-column art column and only animates at MIN_WIDTH (60) columns or wider; a
+ * longer line wraps, and the animation's cursor-up count assumes unwrapped
+ * lines. See src/ui/welcome-screen.ts.
+ */
+export const DESCRIPTION_BUDGET = 17;
+/**
+ * Ordered onboarding hints. Each entry is shown only when its workflow is
+ * installed, so the list follows the change lifecycle: start, then build,
+ * then implement.
+ */
+const ONBOARDING_COMMANDS = [
+    { workflow: 'propose', command: '/opsx:propose', description: 'Start a change' },
+    { workflow: 'new', command: '/opsx:new', description: 'Scaffold a change' },
+    { workflow: 'continue', command: '/opsx:continue', description: 'Next artifact' },
+    { workflow: 'apply', command: '/opsx:apply', description: 'Implement tasks' },
+];
+/**
+ * Returns the onboarding hints for the installed workflows, in lifecycle order.
+ * Returns an empty array when none of the onboarding workflows are installed.
+ */
+export function getOnboardingCommands(workflows) {
+    const installed = new Set(workflows);
+    return ONBOARDING_COMMANDS.filter((entry) => installed.has(entry.workflow));
+}
+//# sourceMappingURL=onboarding-commands.js.map

package/dist/core/openspec-root.js

@@ -11,8 +11,8 @@ export const OPENSPEC_CHANGES_DIR = 'openspec/changes';
 export const OPENSPEC_ARCHIVE_DIR = 'openspec/changes/archive';
 export const DEFAULT_OPENSPEC_SCHEMA = 'spec-driven';
 export const DIRECTORY_ANCHOR_FILE_NAME = '.gitkeep';
-// Git cannot track empty directories, so clones of a fresh store would lose
-// these and fail root-health checks. Anchored at setup time.
+// Git cannot track empty directories, so setup anchors otherwise-empty
+// conventional store directories for teammates who clone the repo later.
 export const ANCHORED_OPENSPEC_DIRS = [OPENSPEC_SPECS_DIR, OPENSPEC_ARCHIVE_DIR];
 async function pathKind(targetPath) {
     try {
@@ -51,6 +51,14 @@ function unresolvedInspection() {
 function missingDirectoryDiagnostic(code, message, target) {
     return makeStoreDiagnostic('error', code, message, { target });
 }
+async function inspectOptionalPlanningDirectory(inspection, storeRoot, key, relativePath, notDirectoryCode, target) {
+    const kind = await pathKind(path.join(storeRoot, relativePath));
+    inspection[key] = { present: kind === 'directory' };
+    if (kind === 'directory' || kind === 'missing')
+        return kind;
+    inspection.diagnostics.push(missingDirectoryDiagnostic(notDirectoryCode, `${relativePath}/ exists but is not a directory.`, target));
+    return kind;
+}
 export async function inspectOpenSpecRoot(storeRoot) {
     const rootKind = await pathKind(storeRoot);
     const inspection = unresolvedInspection();
@@ -90,23 +98,18 @@ export async function inspectOpenSpecRoot(storeRoot) {
             inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_config_missing', 'Missing openspec/config.yaml or openspec/config.yml.', 'openspec.config'));
         }
     }
-    for (const [key, relativePath, code, message, target] of [
-        ['specs', OPENSPEC_SPECS_DIR, 'openspec_specs_missing', 'Missing openspec/specs/.', 'openspec.specs'],
-        ['changes', OPENSPEC_CHANGES_DIR, 'openspec_changes_missing', 'Missing openspec/changes/.', 'openspec.changes'],
-        ['archive', OPENSPEC_ARCHIVE_DIR, 'openspec_archive_missing', 'Missing openspec/changes/archive/.', 'openspec.archive'],
-    ]) {
-        const kind = await pathKind(path.join(storeRoot, relativePath));
-        inspection[key] = { present: kind === 'directory' };
-        if (kind === 'directory')
-            continue;
-        inspection.diagnostics.push(missingDirectoryDiagnostic(kind === 'missing' ? code : code.replace('_missing', '_not_directory'), kind === 'missing' ? message : `${relativePath}/ exists but is not a directory.`, target));
+    await inspectOptionalPlanningDirectory(inspection, storeRoot, 'specs', OPENSPEC_SPECS_DIR, 'openspec_specs_not_directory', 'openspec.specs');
+    const changesKind = await inspectOptionalPlanningDirectory(inspection, storeRoot, 'changes', OPENSPEC_CHANGES_DIR, 'openspec_changes_not_directory', 'openspec.changes');
+    if (changesKind === 'directory') {
+        await inspectOptionalPlanningDirectory(inspection, storeRoot, 'archive', OPENSPEC_ARCHIVE_DIR, 'openspec_archive_not_directory', 'openspec.archive');
+    }
+    else {
+        inspection.archive = { present: false };
     }
     inspection.healthy =
         inspection.present === true &&
             inspection.config.present === true &&
-            inspection.specs.present === true &&
-            inspection.changes.present === true &&
-            inspection.archive.present === true;
+            inspection.diagnostics.length === 0;
     return inspection;
 }
 async function ensureDirectory(storeRoot, relativePath, ledger) {

package/dist/core/parsers/change-parser.d.ts

@@ -1,10 +1,25 @@
-import { MarkdownParser } from './markdown-parser.js';
-import { Change } from '../schemas/index.js';
+import { MarkdownParser, Section } from './markdown-parser.js';
+import { Change, Requirement } from '../schemas/index.js';
 export declare class ChangeParser extends MarkdownParser {
     private changeDir;
     constructor(content: string, changeDir: string);
     parseChangeWithDeltas(name: string): Promise<Change>;
     private parseDeltaSpecs;
+    /**
+     * Read requirements from a delta section, ignoring headers that are not
+     * `### Requirement: <name>`.
+     *
+     * A delta section often carries divider headers such as
+     * `### Documentation Requirements`. The base parser treats every child header
+     * as a requirement, which invented a scenario-less requirement that does not
+     * exist (#498): archive warned about a missing scenario, and `show --json`
+     * reported an extra delta. The delta reader already skips these headers and
+     * notes them, so this keeps the two readers in agreement.
+     *
+     * Overriding here rather than in MarkdownParser keeps main spec parsing —
+     * `view`, `list`, `spec --json`, spec validation — untouched.
+     */
+    protected parseRequirements(section: Section): Requirement[];
     private parseSpecDeltas;
     private parseRenames;
     private parseSectionsFromContent;

package/dist/core/parsers/change-parser.js

@@ -1,6 +1,8 @@
 import { MarkdownParser } from './markdown-parser.js';
+import { buildCodeFenceMask } from './requirement-text.js';
 import path from 'path';
 import { promises as fs } from 'fs';
+import { discoverSpecFiles } from '../../utils/spec-discovery.js';
 export class ChangeParser extends MarkdownParser {
     changeDir;
     constructor(content, changeDir) {
@@ -37,30 +39,42 @@ export class ChangeParser extends MarkdownParser {
     }
     async parseDeltaSpecs(specsDir) {
         const deltas = [];
-        try {
-            const specDirs = await fs.readdir(specsDir, { withFileTypes: true });
-            for (const dir of specDirs) {
-                if (!dir.isDirectory())
-                    continue;
-                const specName = dir.name;
-                const specFile = path.join(specsDir, specName, 'spec.md');
-                try {
-                    const content = await fs.readFile(specFile, 'utf-8');
-                    const specDeltas = this.parseSpecDeltas(specName, content);
-                    deltas.push(...specDeltas);
-                }
-                catch (error) {
-                    // Spec file might not exist, which is okay
-                    continue;
-                }
+        // Discover delta specs recursively so nested layouts like
+        // specs/<area>/<capability>/spec.md are parsed too (#1353)
+        const specFiles = await discoverSpecFiles(specsDir);
+        for (const { id, specFile } of specFiles) {
+            try {
+                const content = await fs.readFile(specFile, 'utf-8');
+                const specDeltas = this.parseSpecDeltas(id, content);
+                deltas.push(...specDeltas);
+            }
+            catch (error) {
+                // Spec file might not be readable, which is okay
+                continue;
             }
-        }
-        catch (error) {
-            // Specs directory might not exist, which is okay
-            return [];
         }
         return deltas;
     }
+    /**
+     * Read requirements from a delta section, ignoring headers that are not
+     * `### Requirement: <name>`.
+     *
+     * A delta section often carries divider headers such as
+     * `### Documentation Requirements`. The base parser treats every child header
+     * as a requirement, which invented a scenario-less requirement that does not
+     * exist (#498): archive warned about a missing scenario, and `show --json`
+     * reported an extra delta. The delta reader already skips these headers and
+     * notes them, so this keeps the two readers in agreement.
+     *
+     * Overriding here rather than in MarkdownParser keeps main spec parsing —
+     * `view`, `list`, `spec --json`, spec validation — untouched.
+     */
+    parseRequirements(section) {
+        return super.parseRequirements({
+            ...section,
+            children: section.children.filter((child) => /^Requirement:\s*\S/i.test(child.title.trim())),
+        });
+    }
     parseSpecDeltas(specName, content) {
         const deltas = [];
         const sections = this.parseSectionsFromContent(content);
@@ -148,7 +162,7 @@ export class ChangeParser extends MarkdownParser {
     parseSectionsFromContent(content) {
         const normalizedContent = ChangeParser.normalizeContent(content);
         const lines = normalizedContent.split('\n');
-        const codeFenceLineMask = ChangeParser.buildCodeFenceMask(lines);
+        const codeFenceLineMask = buildCodeFenceMask(lines);
         const sections = [];
         const stack = [];
         for (let i = 0; i < lines.length; i++) {

package/dist/core/parsers/code-fence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared fenced-code-block detection for the Markdown parsers.
+ *
+ * Several parsers need to ignore Markdown structure (headers, requirement
+ * blocks, scenarios, delta sections) that appears inside fenced code blocks.
+ * Keeping this logic in one place avoids the drift that previously left
+ * `requirement-blocks.ts` treating fenced `### Requirement:` lines as real
+ * requirements during validation and archiving.
+ */
+/**
+ * Builds a per-line mask where `true` marks a line that is part of a fenced
+ * code block (including the opening and closing fence lines themselves).
+ */
+export declare function buildCodeFenceMask(lines: string[]): boolean[];
+//# sourceMappingURL=code-fence.d.ts.map

package/dist/core/parsers/code-fence.js

@@ -0,0 +1,49 @@
+/**
+ * Shared fenced-code-block detection for the Markdown parsers.
+ *
+ * Several parsers need to ignore Markdown structure (headers, requirement
+ * blocks, scenarios, delta sections) that appears inside fenced code blocks.
+ * Keeping this logic in one place avoids the drift that previously left
+ * `requirement-blocks.ts` treating fenced `### Requirement:` lines as real
+ * requirements during validation and archiving.
+ */
+function getFenceMarker(line) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (!fenceMatch) {
+        return null;
+    }
+    return {
+        marker: fenceMatch[1][0],
+        length: fenceMatch[1].length,
+    };
+}
+function isClosingFence(line, activeFence) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
+    return Boolean(fenceMatch &&
+        fenceMatch[1][0] === activeFence.marker &&
+        fenceMatch[1].length >= activeFence.length);
+}
+/**
+ * Builds a per-line mask where `true` marks a line that is part of a fenced
+ * code block (including the opening and closing fence lines themselves).
+ */
+export function buildCodeFenceMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let activeFence = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (!activeFence) {
+            const fence = getFenceMarker(lines[i]);
+            if (fence) {
+                activeFence = fence;
+                mask[i] = true;
+            }
+            continue;
+        }
+        mask[i] = true;
+        if (isClosingFence(lines[i], activeFence)) {
+            activeFence = null;
+        }
+    }
+    return mask;
+}
+//# sourceMappingURL=code-fence.js.map

package/dist/core/parsers/markdown-parser.d.ts

@@ -11,9 +11,6 @@ export declare class MarkdownParser {
     private currentLine;
     constructor(content: string);
     protected static normalizeContent(content: string): string;
-    protected static buildCodeFenceMask(lines: string[]): boolean[];
-    private static getFenceMarker;
-    private static isClosingFence;
     parseSpec(name: string): Spec;
     parseChange(name: string): Change;
     protected parseSections(): Section[];

package/dist/core/parsers/markdown-parser.js

@@ -1,3 +1,4 @@
+import { buildCodeFenceMask, extractRequirementText } from './requirement-text.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -5,46 +6,12 @@ export class MarkdownParser {
     constructor(content) {
         const normalized = MarkdownParser.normalizeContent(content);
         this.lines = normalized.split('\n');
-        this.codeFenceLineMask = MarkdownParser.buildCodeFenceMask(this.lines);
+        this.codeFenceLineMask = buildCodeFenceMask(this.lines);
         this.currentLine = 0;
     }
     static normalizeContent(content) {
-        return content.replace(/\r\n?/g, '\n');
-    }
-    static buildCodeFenceMask(lines) {
-        const mask = new Array(lines.length).fill(false);
-        let activeFence = null;
-        for (let i = 0; i < lines.length; i++) {
-            const fence = MarkdownParser.getFenceMarker(lines[i]);
-            if (!activeFence) {
-                if (fence) {
-                    activeFence = fence;
-                    mask[i] = true;
-                }
-                continue;
-            }
-            mask[i] = true;
-            if (MarkdownParser.isClosingFence(lines[i], activeFence)) {
-                activeFence = null;
-            }
-        }
-        return mask;
-    }
-    static getFenceMarker(line) {
-        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
-        if (!fenceMatch) {
-            return null;
-        }
-        return {
-            marker: fenceMatch[1][0],
-            length: fenceMatch[1].length,
-        };
-    }
-    static isClosingFence(line, activeFence) {
-        const fenceMatch = line.match(/^\s*(`{3,}|~{3,})\s*$/);
-        return Boolean(fenceMatch &&
-            fenceMatch[1][0] === activeFence.marker &&
-            fenceMatch[1].length >= activeFence.length);
+        // Strip a UTF-8 BOM so a header on the first line still matches.
+        return content.replace(/^/, '').replace(/\r\n?/g, '\n');
     }
     parseSpec(name) {
         const sections = this.parseSections();
@@ -149,29 +116,9 @@ export class MarkdownParser {
     parseRequirements(section) {
         const requirements = [];
         for (const child of section.children) {
-            // Extract requirement text from first non-empty content line, fall back to heading
-            let text = child.title;
-            // Get content before any child sections (scenarios)
-            if (child.content.trim()) {
-                // Split content into lines and find content before any child headers
-                const lines = child.content.split('\n');
-                const contentBeforeChildren = [];
-                for (const line of lines) {
-                    // Stop at child headers (scenarios start with ####)
-                    if (line.trim().startsWith('#')) {
-                        break;
-                    }
-                    contentBeforeChildren.push(line);
-                }
-                // Find first non-empty line
-                const directContent = contentBeforeChildren.join('\n').trim();
-                if (directContent) {
-                    const firstLine = directContent.split('\n').find(l => l.trim());
-                    if (firstLine) {
-                        text = firstLine.trim();
-                    }
-                }
-            }
+            // Read the requirement text via the shared reader (multi-line, fence- and
+            // metadata-aware, with the shared header-title fallback for empty bodies).
+            const text = extractRequirementText(child.title, child.content.split('\n'));
             const scenarios = this.parseScenarios(child);
             requirements.push({
                 text,

package/dist/core/parsers/requirement-blocks.d.ts

@@ -11,10 +11,28 @@ export interface RequirementsSectionParts {
     after: string;
 }
 export declare function normalizeRequirementName(name: string): string;
+/**
+ * Case- and whitespace-insensitive fold of a requirement name. Requirement
+ * matching itself is case-sensitive (normalizeRequirementName); this fold
+ * exists only for typo detection - near-miss REMOVED headers and the
+ * RENAMED+REMOVED cross-section conflict - where two spellings that differ
+ * only in case or interior whitespace mean a mistake, never two requirements.
+ */
+export declare function foldRequirementName(name: string): string;
 /**
  * Extracts the Requirements section from a spec file and parses requirement blocks.
  */
 export declare function extractRequirementsSection(content: string): RequirementsSectionParts;
+/**
+ * A level-3 header inside `## ADDED`/`## MODIFIED Requirements` that is not a
+ * canonical `### Requirement:` header, recorded at the moment the delta reader
+ * skips over it. Surfaced as an INFO note by `validate <change>` (#498).
+ */
+export interface SkippedHeader {
+    header: string;
+    section: string;
+    line: number;
+}
 export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
@@ -23,6 +41,7 @@ export interface DeltaPlan {
         from: string;
         to: string;
     }>;
+    skippedHeaders: SkippedHeader[];
     sectionPresence: {
         added: boolean;
         modified: boolean;
@@ -34,4 +53,14 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+/**
+ * Scenario names the current requirement block has and the incoming
+ * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
+ * so every name reported here would be dropped from the main spec.
+ *
+ * Shared by archive (which refuses to apply the block) and validate (which
+ * reports the same loss at authoring time, #1477), so the two cannot disagree
+ * about what counts as a dropped scenario.
+ */
+export declare function findMissingCurrentScenarios(current: RequirementBlock, incoming: RequirementBlock): string[];
 //# sourceMappingURL=requirement-blocks.d.ts.map