gmc-openspec 1.0.0

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

@@ -0,0 +1,17 @@
+import { type JiraValidationStage } from './constants.js';
+export interface JiraValidationIssue {
+    code: string;
+    message: string;
+    file?: string;
+}
+export interface JiraValidationReport {
+    ok: boolean;
+    jira: string;
+    stage: JiraValidationStage;
+    issueDir: string;
+    status?: string;
+    errors: JiraValidationIssue[];
+    warnings: JiraValidationIssue[];
+}
+export declare function validateJiraIntake(projectRoot: string, jiraId: string, stage: JiraValidationStage): JiraValidationReport;
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/jira/validation.js

@@ -0,0 +1,341 @@
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { JIRA_STAGE_MIN_STATUS, } from './constants.js';
+import { hashFileSha256 } from './hash.js';
+import { readJiraIntake, statusAtLeast } from './intake.js';
+import { normalizeJiraId, toDisplayPath, validateJiraId } from './paths.js';
+export function validateJiraIntake(projectRoot, jiraId, stage) {
+    const normalizedJira = normalizeJiraId(jiraId);
+    const errors = [];
+    const warnings = [];
+    const idValidation = validateJiraId(normalizedJira);
+    if (!idValidation.valid) {
+        errors.push({ code: 'invalid-jira-id', message: idValidation.error ?? 'Invalid Jira issue id' });
+    }
+    const intakeResult = readJiraIntake(projectRoot, normalizedJira);
+    warnings.push(...intakeResult.warnings.map((message) => ({ code: 'intake-warning', message, file: toDisplayPath(projectRoot, intakeResult.path) })));
+    if (!intakeResult.intake) {
+        errors.push({
+            code: 'missing-intake',
+            message: 'Missing jira intake.yaml. Run /opsx:jira-import first.',
+            file: toDisplayPath(projectRoot, intakeResult.path),
+        });
+        return buildReport(projectRoot, normalizedJira, stage, intakeResult.issueDir, undefined, errors, warnings);
+    }
+    const intake = intakeResult.intake;
+    const requiredStatus = JIRA_STAGE_MIN_STATUS[stage];
+    if (!statusAtLeast(intake.status, requiredStatus)) {
+        errors.push({
+            code: 'status-not-ready',
+            message: `Stage ${stage} requires status ${requiredStatus} or later, but intake is ${intake.status}.`,
+            file: toDisplayPath(projectRoot, intakeResult.path),
+        });
+    }
+    validateSource(projectRoot, intakeResult.issueDir, intake.sourceHashSha256, errors);
+    if (stage === 'requirement' || stage === 'stories' || stage === 'propose') {
+        validateRequirementFiles(projectRoot, intakeResult.issueDir, errors);
+        validateBlockingQuestions(projectRoot, intakeResult.issueDir, errors);
+        validateAssumptions(projectRoot, intakeResult.issueDir, errors);
+    }
+    if (stage === 'stories' || stage === 'propose') {
+        validateStories(projectRoot, intakeResult.issueDir, errors);
+        validateMapping(projectRoot, intakeResult.issueDir, stage, errors, warnings);
+    }
+    return buildReport(projectRoot, normalizedJira, stage, intakeResult.issueDir, intake.status, errors, warnings);
+}
+function buildReport(projectRoot, jira, stage, issueDir, status, errors, warnings) {
+    return {
+        ok: errors.length === 0,
+        jira,
+        stage,
+        issueDir: toDisplayPath(projectRoot, issueDir),
+        status,
+        errors,
+        warnings,
+    };
+}
+function validateSource(projectRoot, issueDir, expectedHash, errors) {
+    const sourcePath = path.join(issueDir, 'source.md');
+    if (!existsSync(sourcePath)) {
+        errors.push({ code: 'missing-source', message: 'Missing source.md.', file: toDisplayPath(projectRoot, sourcePath) });
+        return;
+    }
+    if (!expectedHash) {
+        errors.push({
+            code: 'missing-source-hash',
+            message: 'intake.yaml must record sourceHashSha256 so source.md remains an auditable read-only snapshot.',
+            file: toDisplayPath(projectRoot, path.join(issueDir, 'intake.yaml')),
+        });
+        return;
+    }
+    const actualHash = hashFileSha256(sourcePath);
+    if (actualHash !== expectedHash) {
+        errors.push({
+            code: 'source-hash-drift',
+            message: 'source.md has changed since import. Re-import or restore the original Jira snapshot.',
+            file: toDisplayPath(projectRoot, sourcePath),
+        });
+    }
+}
+function validateRequirementFiles(projectRoot, issueDir, errors) {
+    const requirementPath = path.join(issueDir, 'requirement.md');
+    if (!existsSync(requirementPath)) {
+        errors.push({ code: 'missing-requirement', message: 'Missing reviewed requirement.md.', file: toDisplayPath(projectRoot, requirementPath) });
+    }
+}
+function validateStories(projectRoot, issueDir, errors) {
+    const storiesPath = path.join(issueDir, 'stories.md');
+    if (!existsSync(storiesPath)) {
+        errors.push({ code: 'missing-stories', message: 'Missing reviewed stories.md.', file: toDisplayPath(projectRoot, storiesPath) });
+    }
+}
+function validateBlockingQuestions(projectRoot, issueDir, errors) {
+    const questionsPath = path.join(issueDir, 'questions.md');
+    if (!existsSync(questionsPath))
+        return;
+    const unresolved = findUnresolvedQuestionBlocks(readFileSync(questionsPath, 'utf8'));
+    for (const question of unresolved) {
+        errors.push({
+            code: 'blocking-question-open',
+            message: `Blocking question is unresolved: ${question}`,
+            file: toDisplayPath(projectRoot, questionsPath),
+        });
+    }
+}
+function validateAssumptions(projectRoot, issueDir, errors) {
+    const assumptionsPath = path.join(issueDir, 'assumptions.md');
+    if (!existsSync(assumptionsPath))
+        return;
+    const unresolved = findUnapprovedAssumptionBlocks(readFileSync(assumptionsPath, 'utf8'));
+    for (const assumption of unresolved) {
+        errors.push({
+            code: 'assumption-not-approved',
+            message: `Assumption is not approved: ${assumption}`,
+            file: toDisplayPath(projectRoot, assumptionsPath),
+        });
+    }
+}
+function validateMapping(projectRoot, issueDir, stage, errors, warnings) {
+    const mappingPath = path.join(issueDir, 'mapping.yaml');
+    if (!existsSync(mappingPath)) {
+        errors.push({ code: 'missing-mapping', message: 'Missing mapping.yaml traceability matrix.', file: toDisplayPath(projectRoot, mappingPath) });
+        return;
+    }
+    let mapping;
+    try {
+        mapping = parseYaml(readFileSync(mappingPath, 'utf8')) ?? {};
+    }
+    catch (error) {
+        errors.push({
+            code: 'invalid-mapping',
+            message: `Failed to parse mapping.yaml: ${error instanceof Error ? error.message : String(error)}`,
+            file: toDisplayPath(projectRoot, mappingPath),
+        });
+        return;
+    }
+    const acIds = collectAcceptanceCriteriaIds(mapping);
+    if (acIds.length === 0) {
+        warnings.push({
+            code: 'no-acceptance-criteria-mapped',
+            message: 'mapping.yaml does not list Jira acceptance criteria; story coverage cannot be proven.',
+            file: toDisplayPath(projectRoot, mappingPath),
+        });
+    }
+    for (const acId of acIds) {
+        if (!isAcceptanceCriteriaCovered(mapping, acId)) {
+            errors.push({
+                code: 'acceptance-criteria-uncovered',
+                message: `Acceptance criterion ${acId} is not mapped to any story.`,
+                file: toDisplayPath(projectRoot, mappingPath),
+            });
+        }
+    }
+    const storiesWithoutRequirementSource = findStoriesWithoutRequirementSource(mapping);
+    for (const storyId of storiesWithoutRequirementSource) {
+        errors.push({
+            code: 'story-without-requirement-source',
+            message: `Story ${storyId} must trace back to at least one requirement.`,
+            file: toDisplayPath(projectRoot, mappingPath),
+        });
+    }
+    if (stage === 'propose') {
+        const storyIssues = findStoriesWithoutChange(mapping);
+        for (const storyId of storyIssues) {
+            errors.push({
+                code: 'story-without-openspec-change',
+                message: `Story ${storyId} must have an OpenSpec change or be marked deferred.`,
+                file: toDisplayPath(projectRoot, mappingPath),
+            });
+        }
+        const storiesWithoutSpecFiles = findStoriesWithoutSpecFiles(mapping);
+        for (const storyId of storiesWithoutSpecFiles) {
+            errors.push({
+                code: 'story-without-spec-file',
+                message: `Story ${storyId} must map to at least one OpenSpec spec file.`,
+                file: toDisplayPath(projectRoot, mappingPath),
+            });
+        }
+    }
+}
+function findUnresolvedQuestionBlocks(content) {
+    const blocking = sectionContent(content, 'Blocking');
+    return itemBlocks(blocking).filter((block) => {
+        if (/\bstatus\s*:\s*(answered|resolved|accepted|closed)\b/i.test(block))
+            return false;
+        return /\bstatus\s*:\s*(unanswered|open|pending|needs|unresolved)\b/i.test(block) || block.trim().length > 0;
+    }).map(firstLineText);
+}
+function findUnapprovedAssumptionBlocks(content) {
+    return itemBlocks(content).filter((block) => {
+        if (/\bstatus\s*:\s*(accepted|approved)\b/i.test(block))
+            return false;
+        return /\bstatus\s*:/i.test(block) || block.trim().length > 0;
+    }).map(firstLineText);
+}
+function sectionContent(content, heading) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex((line) => new RegExp(`^##\\s+${heading}\\s*$`, 'i').test(line.trim()));
+    if (start === -1)
+        return '';
+    const end = lines.findIndex((line, index) => index > start && /^##\s+/.test(line));
+    return lines.slice(start + 1, end === -1 ? undefined : end).join('\n');
+}
+function itemBlocks(content) {
+    const lines = content.split(/\r?\n/);
+    const blocks = [];
+    let current = [];
+    for (const line of lines) {
+        if (/^-\s+/.test(line)) {
+            if (current.length > 0)
+                blocks.push(current.join('\n'));
+            current = [line];
+        }
+        else if (current.length > 0) {
+            current.push(line);
+        }
+    }
+    if (current.length > 0)
+        blocks.push(current.join('\n'));
+    return blocks.filter((block) => block.trim().length > 0);
+}
+function firstLineText(block) {
+    return block.split(/\r?\n/)[0].replace(/^\s*-\s+/, '').trim();
+}
+function collectAcceptanceCriteriaIds(mapping) {
+    const ids = new Set();
+    const acObject = mapping?.acceptanceCriteria ?? mapping?.acceptance_criteria;
+    if (acObject && typeof acObject === 'object' && !Array.isArray(acObject)) {
+        for (const key of Object.keys(acObject))
+            ids.add(key);
+    }
+    for (const requirement of Object.values(mapping?.requirements ?? {})) {
+        const source = requirement?.source;
+        const acValues = Array.isArray(source?.ac) ? source.ac : source?.ac ? [source.ac] : [];
+        for (const ac of acValues)
+            ids.add(String(ac));
+    }
+    return [...ids].sort();
+}
+function isAcceptanceCriteriaCovered(mapping, acId) {
+    const acObject = mapping?.acceptanceCriteria ?? mapping?.acceptance_criteria;
+    const acEntry = acObject?.[acId];
+    if (hasNonEmptyArray(acEntry?.stories))
+        return true;
+    for (const requirement of Object.values(mapping?.requirements ?? {})) {
+        const source = requirement?.source;
+        const acValues = Array.isArray(source?.ac) ? source.ac : source?.ac ? [source.ac] : [];
+        if (acValues.map(String).includes(acId) && hasNonEmptyArray(requirement?.stories)) {
+            return true;
+        }
+    }
+    return false;
+}
+function findStoriesWithoutChange(mapping) {
+    const stories = mapping?.stories;
+    if (!stories || typeof stories !== 'object' || Array.isArray(stories))
+        return [];
+    return Object.entries(stories)
+        .filter(([, value]) => {
+        const story = value;
+        if (story?.deferred === true || story?.status === 'deferred')
+            return false;
+        return !(story?.openspecChange || story?.openSpecChange || story?.openspec_change);
+    })
+        .map(([key]) => key)
+        .sort();
+}
+function findStoriesWithoutRequirementSource(mapping) {
+    const stories = mapping?.stories;
+    if (!stories || typeof stories !== 'object' || Array.isArray(stories))
+        return [];
+    return Object.entries(stories)
+        .filter(([storyId, value]) => {
+        const story = value;
+        if (isDeferredStory(story))
+            return false;
+        if (hasTraceValue(story?.requirements) || hasTraceValue(story?.requirement))
+            return false;
+        if (hasTraceValue(story?.source?.requirements) || hasTraceValue(story?.source?.requirement))
+            return false;
+        if (hasTraceValue(story?.sources?.requirements) || hasTraceValue(story?.sources?.requirement))
+            return false;
+        return !isStoryReferencedByRequirement(mapping, storyId);
+    })
+        .map(([key]) => key)
+        .sort();
+}
+function findStoriesWithoutSpecFiles(mapping) {
+    const stories = mapping?.stories;
+    if (!stories || typeof stories !== 'object' || Array.isArray(stories))
+        return [];
+    return Object.entries(stories)
+        .filter(([storyId, value]) => {
+        const story = value;
+        if (isDeferredStory(story))
+            return false;
+        if (hasTraceValue(story?.specFiles) || hasTraceValue(story?.specs) || hasTraceValue(story?.spec_files))
+            return false;
+        if (hasTraceValue(story?.specFile) || hasTraceValue(story?.spec))
+            return false;
+        const changeName = story?.openspecChange ?? story?.openSpecChange ?? story?.openspec_change;
+        if (typeof changeName !== 'string' || changeName.trim().length === 0)
+            return true;
+        const change = mapping?.openspecChanges?.[changeName] ?? mapping?.openSpecChanges?.[changeName] ?? mapping?.openspec_changes?.[changeName] ?? mapping?.changes?.[changeName];
+        return !(hasTraceValue(change?.specFiles) ||
+            hasTraceValue(change?.specs) ||
+            hasTraceValue(change?.spec_files) ||
+            hasTraceValue(change?.specFile) ||
+            hasTraceValue(change?.spec));
+    })
+        .map(([key]) => key)
+        .sort();
+}
+function isStoryReferencedByRequirement(mapping, storyId) {
+    for (const requirement of Object.values(mapping?.requirements ?? {})) {
+        if (hasTraceValue(requirement?.stories) && traceValues(requirement.stories).includes(storyId)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isDeferredStory(story) {
+    return story?.deferred === true || story?.status === 'deferred';
+}
+function hasTraceValue(value) {
+    return traceValues(value).length > 0;
+}
+function traceValues(value) {
+    if (Array.isArray(value)) {
+        return value.map(String).map((item) => item.trim()).filter(Boolean);
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    return [];
+}
+function hasNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+//# sourceMappingURL=validation.js.map

package/dist/core/legacy-cleanup.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Legacy cleanup module for detecting and removing OpenSpec artifacts
+ * from previous init versions during the migration to the skill-based workflow.
+ */
+/**
+ * Legacy config file names from the old ToolRegistry.
+ * These were config files created at project root with OpenSpec markers.
+ */
+export declare const LEGACY_CONFIG_FILES: readonly ["CLAUDE.md", "CLINE.md", "CODEBUDDY.md", "COSTRICT.md", "QODER.md", "IFLOW.md", "AGENTS.md", "QWEN.md"];
+/**
+ * Legacy slash command patterns from the old SlashCommandRegistry.
+ * These map toolId to the path pattern where legacy commands were created.
+ * Some tools used a directory structure, others used individual files.
+ */
+export declare const LEGACY_SLASH_COMMAND_PATHS: Record<string, LegacySlashCommandPattern>;
+/**
+ * Pattern types for legacy slash commands
+ */
+export interface LegacySlashCommandPattern {
+    type: 'directory' | 'files';
+    path?: string;
+    pattern?: string | string[];
+}
+/**
+ * Result of legacy artifact detection
+ */
+export interface LegacyDetectionResult {
+    /** Config files with OpenSpec markers detected */
+    configFiles: string[];
+    /** Config files to update (remove markers only, never delete) */
+    configFilesToUpdate: string[];
+    /** Legacy slash command directories found */
+    slashCommandDirs: string[];
+    /** Legacy slash command files found (for file-based tools) */
+    slashCommandFiles: string[];
+    /** Whether openspec/AGENTS.md exists */
+    hasOpenspecAgents: boolean;
+    /** Whether openspec/project.md exists (preserved, migration hint only) */
+    hasProjectMd: boolean;
+    /** Whether root AGENTS.md has OpenSpec markers */
+    hasRootAgentsWithMarkers: boolean;
+    /** Whether any legacy artifacts were found */
+    hasLegacyArtifacts: boolean;
+}
+/**
+ * Detects all legacy OpenSpec artifacts in a project.
+ *
+ * @param projectPath - The root path of the project
+ * @returns Detection result with all found legacy artifacts
+ */
+export declare function detectLegacyArtifacts(projectPath: string): Promise<LegacyDetectionResult>;
+/**
+ * Detects legacy config files with OpenSpec markers.
+ * All config files with markers are candidates for update (marker removal only).
+ * Config files are NEVER deleted - they belong to the user's project root.
+ *
+ * @param projectPath - The root path of the project
+ * @returns Object with all files found and files to update
+ */
+export declare function detectLegacyConfigFiles(projectPath: string): Promise<{
+    allFiles: string[];
+    filesToUpdate: string[];
+}>;
+/**
+ * Detects legacy slash command directories and files.
+ *
+ * @param projectPath - The root path of the project
+ * @returns Object with directories and individual files found
+ */
+export declare function detectLegacySlashCommands(projectPath: string): Promise<{
+    directories: string[];
+    files: string[];
+}>;
+/**
+ * Detects legacy OpenSpec structure files (AGENTS.md and project.md).
+ *
+ * @param projectPath - The root path of the project
+ * @returns Object with detection results for structure files
+ */
+export declare function detectLegacyStructureFiles(projectPath: string): Promise<{
+    hasOpenspecAgents: boolean;
+    hasProjectMd: boolean;
+    hasRootAgentsWithMarkers: boolean;
+}>;
+/**
+ * Checks if content contains OpenSpec markers.
+ *
+ * @param content - File content to check
+ * @returns True if both start and end markers are present
+ */
+export declare function hasOpenSpecMarkers(content: string): boolean;
+/**
+ * Checks if file content is 100% OpenSpec content (only markers and whitespace outside).
+ *
+ * @param content - File content to check
+ * @returns True if content outside markers is only whitespace
+ */
+export declare function isOnlyOpenSpecContent(content: string): boolean;
+/**
+ * Removes the OpenSpec marker block from file content.
+ * Only removes markers that are on their own lines (ignores inline mentions).
+ * Cleans up double blank lines that may result from removal.
+ *
+ * @param content - File content with OpenSpec markers
+ * @returns Content with marker block removed
+ */
+export declare function removeMarkerBlock(content: string): string;
+/**
+ * Result of cleanup operation
+ */
+export interface CleanupResult {
+    /** Files that were deleted entirely */
+    deletedFiles: string[];
+    /** Files that had marker blocks removed */
+    modifiedFiles: string[];
+    /** Directories that were deleted */
+    deletedDirs: string[];
+    /** Whether project.md exists and needs manual migration */
+    projectMdNeedsMigration: boolean;
+    /** Error messages if any operations failed */
+    errors: string[];
+}
+/**
+ * Cleans up legacy OpenSpec artifacts from a project.
+ * Preserves openspec/project.md (shows migration hint instead of deleting).
+ *
+ * @param projectPath - The root path of the project
+ * @param detection - Detection result from detectLegacyArtifacts
+ * @returns Cleanup result with summary of actions taken
+ */
+export declare function cleanupLegacyArtifacts(projectPath: string, detection: LegacyDetectionResult): Promise<CleanupResult>;
+/**
+ * Generates a cleanup summary message for display.
+ *
+ * @param result - Cleanup result from cleanupLegacyArtifacts
+ * @returns Formatted summary string for console output
+ */
+export declare function formatCleanupSummary(result: CleanupResult): string;
+/**
+ * Generates a detection summary message for display before cleanup.
+ * Groups files by action type: removals, updates, and manual migration.
+ *
+ * @param detection - Detection result from detectLegacyArtifacts
+ * @returns Formatted summary string showing what was found
+ */
+export declare function formatDetectionSummary(detection: LegacyDetectionResult): string;
+/**
+ * Extract tool IDs from detected legacy artifacts.
+ * Uses LEGACY_SLASH_COMMAND_PATHS to map paths back to tool IDs.
+ *
+ * @param detection - Detection result from detectLegacyArtifacts
+ * @returns Array of tool IDs that had legacy artifacts
+ */
+export declare function getToolsFromLegacyArtifacts(detection: LegacyDetectionResult): string[];
+/**
+ * Generates a migration hint message for project.md.
+ * This is shown when project.md exists and needs manual migration to config.yaml.
+ *
+ * @returns Formatted migration hint string for console output
+ */
+export declare function formatProjectMdMigrationHint(): string;
+//# sourceMappingURL=legacy-cleanup.d.ts.map