@clawplays/ospec-cli 0.3.4 → 0.3.7

package/README.md

@@ -31,15 +31,24 @@ OSpec is a document-driven workflow for AI-assisted development, helping you def
   <a href="https://github.com/clawplays/ospec/issues">Issues</a>
 </p>
 
+## Why OSpec?
+
+AI coding assistants are powerful, but requirements that live only in chat history are hard to inspect, review, and close out cleanly. OSpec adds a lightweight workflow layer so the repository can hold the change context before code is written and after the work ships.
+
+- Align before code — keep proposal, tasks, state, verification, and review visible in the repo
+- Keep each requirement explicit — the default path moves one requirement through one active change
+- Stay lightweight — keep the normal flow short with `init -> change -> verify/finalize`
+- Use the assistants you already have — OSpec is built for Codex, Claude Code, and direct CLI workflows
+
 ## Install With npm
 
 ```bash
 npm install -g @clawplays/ospec-cli
 ```
 
-## Recommended Prompts
+## Quick Start
 
-Most teams only need 3 steps to use OSpec:
+OSpec only takes 3 steps:
 
 1. initialize OSpec in your project directory
 2. create and advance one change for a requirement, document update, or bug fix
@@ -50,13 +59,13 @@ Most teams only need 3 steps to use OSpec:
 Recommended prompt:
 
 ```text
-Use OSpec to initialize this project.
+OSpec, initialize this project.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to initialize this project.
+$ospec initialize this project.
 ```
 
 <details>
@@ -90,17 +99,15 @@ Use this for requirement delivery, documentation updates, refactors, and bug fix
 Recommended prompt:
 
 ```text
-Use OSpec to create and advance a change for this requirement.
+OSpec, create and advance a change for this requirement.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec-change to create and advance a change for this requirement.
+$ospec-change create and advance a change for this requirement.
 ```
 
-![OSpec Change slash command example](docs/assets/ospecchange-slash-command.en.svg)
-
 <details>
 <summary>Command line</summary>
 
@@ -119,13 +126,13 @@ After the requirement has passed deployment, testing, QA, or other acceptance ch
 Recommended prompt:
 
 ```text
-Use OSpec to archive this accepted change.
+OSpec, archive this accepted change.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to archive this accepted change.
+$ospec archive this accepted change.
 ```
 
 <details>
@@ -141,15 +148,24 @@ Archive notes:
 - run your project-specific deploy, test, and QA flow first
 - use `ospec verify` to confirm the active change is ready
 - use `ospec finalize` to rebuild indexes and archive the accepted change
+- new projects archive under `changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>`; existing flat archives are reorganized by `ospec update`
 
 </details>
 
+## Update With npm
+
+For an existing OSpec project, after upgrading the CLI with npm, run this in the project directory to refresh the project's OSpec files:
+
+```bash
+ospec update
+```
+
 ## How The OSpec Workflow Works
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
 │  1. USER REQUEST                                               │
-│     "Use OSpec to create and advance a change for this task."  │
+│     "OSpec, create and advance a change for this task."       │
 └─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
@@ -217,13 +233,13 @@ Use Stitch for page design review and preview collaboration, especially for land
 AI conversation:
 
 ```text
-Use OSpec to enable the Stitch plugin.
+OSpec, enable the Stitch plugin and connect using Codex/Gemini.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to enable the Stitch plugin.
+$ospec enable the Stitch plugin and connect using Codex/Gemini.
 ```
 
 <details>
@@ -242,13 +258,13 @@ Use Checkpoint for app flow validation and automated checks, especially for subm
 AI conversation:
 
 ```text
-Use OSpec to enable the Checkpoint plugin.
+OSpec, enable the Checkpoint plugin.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to enable the Checkpoint plugin.
+$ospec enable the Checkpoint plugin.
 ```
 
 <details>

package/dist/cli.js

@@ -224,7 +224,7 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.3.4';
+const CLI_VERSION = '0.3.7';
 
 function showInitUsage() {
     console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language en-US|zh-CN|ja-JP|ar]');

package/dist/commands/ArchiveCommand.js

@@ -180,7 +180,7 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
                     this.success('Change is ready to archive');
                     return;
                 }
-                const archivePath = await this.performArchive(targetPath, projectRoot, featureState);
+                const archivePath = await this.performArchive(targetPath, projectRoot, featureState, config);
                 this.success(`Change archived to ${archivePath}`);
                 return archivePath;
             }
@@ -194,11 +194,10 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
             throw error;
         }
     }
-    async performArchive(targetPath, projectRoot, featureState) {
+    async performArchive(targetPath, projectRoot, featureState, config) {
         const archivedRoot = path.join(projectRoot, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ARCHIVED);
         await services_1.services.fileService.ensureDir(archivedRoot);
-        const archiveDirName = await this.resolveArchiveDirName(archivedRoot, featureState.feature);
-        const archivePath = path.join(archivedRoot, archiveDirName);
+        const archivePath = await this.resolveArchivePath(archivedRoot, featureState.feature, config);
         const nextState = {
             ...featureState,
             status: 'archived',
@@ -222,9 +221,29 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
         proposal.data.status = status;
         await services_1.services.fileService.writeFile(proposalPath, gray_matter_1.default.stringify(proposal.content, proposal.data));
     }
-    async resolveArchiveDirName(archivedRoot, featureName) {
-        const datePrefix = new Date().toISOString().slice(0, 10);
-        const baseName = `${datePrefix}-${featureName}`;
+    async resolveArchivePath(archivedRoot, featureName, config) {
+        const archiveLayout = config?.archive?.layout === 'month-day' ? 'month-day' : 'flat';
+        const archiveDate = this.getLocalArchiveDateParts();
+        if (archiveLayout === 'month-day') {
+            const archiveDayRoot = path.join(archivedRoot, archiveDate.month, archiveDate.day);
+            await services_1.services.fileService.ensureDir(archiveDayRoot);
+            const archiveLeafName = await this.resolveArchiveLeafName(archiveDayRoot, featureName);
+            return path.join(archiveDayRoot, archiveLeafName);
+        }
+        const archiveDirName = await this.resolveLegacyArchiveDirName(archivedRoot, archiveDate.day, featureName);
+        return path.join(archivedRoot, archiveDirName);
+    }
+    async resolveArchiveLeafName(archiveDayRoot, featureName) {
+        let candidate = featureName;
+        let index = 2;
+        while (await services_1.services.fileService.exists(path.join(archiveDayRoot, candidate))) {
+            candidate = `${featureName}-${index}`;
+            index += 1;
+        }
+        return candidate;
+    }
+    async resolveLegacyArchiveDirName(archivedRoot, archiveDay, featureName) {
+        const baseName = `${archiveDay}-${featureName}`;
         let candidate = baseName;
         let index = 2;
         while (await services_1.services.fileService.exists(path.join(archivedRoot, candidate))) {
@@ -233,6 +252,16 @@ class ArchiveCommand extends BaseCommand_1.BaseCommand {
         }
         return candidate;
     }
+    getLocalArchiveDateParts() {
+        const now = new Date();
+        const year = String(now.getFullYear());
+        const monthNumber = String(now.getMonth() + 1).padStart(2, '0');
+        const dayNumber = String(now.getDate()).padStart(2, '0');
+        return {
+            month: `${year}-${monthNumber}`,
+            day: `${year}-${monthNumber}-${dayNumber}`,
+        };
+    }
     toRelativePath(rootDir, targetPath) {
         return path.relative(rootDir, targetPath).replace(/\\/g, '/');
     }

package/dist/commands/ChangesCommand.js

@@ -21,6 +21,9 @@ class ChangesCommand extends BaseCommand_1.BaseCommand {
                     console.log(`Total: ${report.totalActiveChanges}`);
                     console.log(`Queued: ${queuedChanges.length}`);
                     console.log(`PASS ${report.totals.pass} | WARN ${report.totals.warn} | FAIL ${report.totals.fail}`);
+                    if (report.totalActiveChanges > 1) {
+                        console.log('WORKFLOW WARN multiple active changes detected. The default workflow expects one active change, and queue runner commands will fail until the repository is back to single-active mode.');
+                    }
                     console.log('');
                     if (report.changes.length === 0) {
                         console.log('No active changes.');

package/dist/commands/InitCommand.js

@@ -37,6 +37,7 @@ exports.InitCommand = void 0;
 const os_1 = require("os");
 const path = __importStar(require("path"));
 const services_1 = require("../services");
+const helpers_1 = require("../utils/helpers");
 const BaseCommand_1 = require("./BaseCommand");
 const SkillCommand_1 = require("./SkillCommand");
 class InitCommand extends BaseCommand_1.BaseCommand {
@@ -73,7 +74,7 @@ class InitCommand extends BaseCommand_1.BaseCommand {
             if (result.firstChangeSuggestion) {
                 this.info(`  Suggested first change: ${result.firstChangeSuggestion.name}`);
             }
-            this.info(`  Next: ospec new <change-name> ${targetDir}`);
+            this.info(`  Next: ${(0, helpers_1.formatCliCommand)('ospec', 'new', '<change-name>', targetDir)}`);
         }
         catch (error) {
             this.error(`Failed to initialize project: ${error}`);

package/dist/commands/NewCommand.js

@@ -37,6 +37,7 @@ exports.NewCommand = void 0;
 const path = __importStar(require("path"));
 const constants_1 = require("../core/constants");
 const services_1 = require("../services");
+const helpers_1 = require("../utils/helpers");
 const PathUtils_1 = require("../utils/PathUtils");
 const PluginWorkflowComposer_1 = require("../workflow/PluginWorkflowComposer");
 const BaseCommand_1 = require("./BaseCommand");
@@ -50,6 +51,7 @@ class NewCommand extends BaseCommand_1.BaseCommand {
             const featureDir = PathUtils_1.PathUtils.getChangeDir(targetDir, placement, featureName);
             this.logger.info(`Creating ${placement === constants_1.DIR_NAMES.QUEUED ? 'queued change' : 'change'}: ${featureName}`);
             await this.ensureChangeNameAvailable(targetDir, featureName);
+            await this.ensureSingleActiveMode(targetDir, placement, featureName);
             await services_1.services.fileService.ensureDir(path.join(targetDir, constants_1.DIR_NAMES.CHANGES, placement));
             await services_1.services.fileService.ensureDir(featureDir);
             const config = await services_1.services.configManager.loadConfig(targetDir);
@@ -229,6 +231,24 @@ class NewCommand extends BaseCommand_1.BaseCommand {
         }
         throw new Error(`Change ${featureName} already exists in ${conflicts.join(' and ')}. Continue the existing change instead of creating a duplicate.`);
     }
+    async ensureSingleActiveMode(targetDir, placement, featureName) {
+        if (placement !== constants_1.DIR_NAMES.ACTIVE) {
+            return;
+        }
+        const activeNames = await services_1.services.projectService.listActiveChangeNames(targetDir);
+        if (activeNames.length === 0) {
+            return;
+        }
+        if (activeNames.length === 1) {
+            const activeName = activeNames[0];
+            const activeChangePath = path.join(targetDir, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ACTIVE, activeName);
+            const progressCommand = (0, helpers_1.formatCliCommand)('ospec', 'progress', activeChangePath);
+            const queueCommand = (0, helpers_1.formatCliCommand)('ospec', 'queue', 'add', featureName, targetDir);
+            throw new Error(`A single active change is the default workflow, but "${activeName}" is already active. Continue it with "${progressCommand}" or create queued work explicitly with "${queueCommand}".`);
+        }
+        const queueCommand = (0, helpers_1.formatCliCommand)('ospec', 'queue', 'add', featureName, targetDir);
+        throw new Error(`A single active change is the default workflow, but ${activeNames.length} active changes already exist: ${activeNames.join(', ')}. Resolve the repository back to one active change before creating another, or add new work with "${queueCommand}".`);
+    }
     async writePluginArtifacts(featureDir, activatedSteps) {
         const checkpointSteps = activatedSteps.filter(step => step === 'checkpoint_ui_review' || step === 'checkpoint_flow_check');
         if (checkpointSteps.length > 0) {

package/dist/commands/PluginsCommand.js

@@ -5,6 +5,7 @@ const child_process_1 = require("child_process");
 const path = require("path");
 const gray_matter_1 = require("gray-matter");
 const constants_1 = require("../core/constants");
+const helpers_1 = require("../utils/helpers");
 const BaseCommand_1 = require("./BaseCommand");
 const services_1 = require("../services");
 const subcommandHelp_1 = require("../utils/subcommandHelp");
@@ -162,7 +163,7 @@ class PluginsCommand extends BaseCommand_1.BaseCommand {
                 if (plugin.runner.extraEnvCount > 0) {
                     console.log(`    Extra env entries: ${plugin.runner.extraEnvCount}`);
                 }
-                console.log(`    Doctor: ospec plugins doctor ${plugin.name} ${projectPath}`);
+                console.log(`    Doctor: ${(0, helpers_1.formatCliCommand)('ospec', 'plugins', 'doctor', plugin.name, projectPath)}`);
             }
             console.log();
         });
@@ -231,7 +232,7 @@ class PluginsCommand extends BaseCommand_1.BaseCommand {
                 this.info(`  codex model: ${this.getStitchCodexConfig(nextConfig.plugins.stitch).model || '(cli default)'}`);
                 if (enabled) {
                     this.info(`  token env: ${nextConfig.plugins.stitch.runner.token_env || '(not required)'}`);
-                    this.info(`  doctor: ospec plugins doctor stitch ${projectPath}`);
+                    this.info(`  doctor: ${(0, helpers_1.formatCliCommand)('ospec', 'plugins', 'doctor', 'stitch', projectPath)}`);
                 }
                 this.info('  Affects new changes by default; update existing changes manually if needed');
                 return;
@@ -311,7 +312,7 @@ class PluginsCommand extends BaseCommand_1.BaseCommand {
                 this.info(`  runner.command: ${nextConfig.plugins.checkpoint.runner.command || '(built-in adapter)'}`);
                 this.info(`  stitch integration: ${nextConfig.plugins.checkpoint.stitch_integration.enabled ? 'enabled' : 'disabled'}`);
                 if (enabled) {
-                    this.info(`  doctor: ospec plugins doctor checkpoint ${projectPath}`);
+                    this.info(`  doctor: ${(0, helpers_1.formatCliCommand)('ospec', 'plugins', 'doctor', 'checkpoint', projectPath)}`);
                 }
                 this.info('  Affects new changes by default; update existing changes manually if needed');
                 return;

package/dist/commands/SkillCommand.js

@@ -16,6 +16,8 @@ const path_1 = __importDefault(require("path"));
 
 const services_1 = require("../services");
 
+const helpers_1 = require("../utils/helpers");
+
 const subcommandHelp_1 = require("../utils/subcommandHelp");
 
 const BaseCommand_1 = require("./BaseCommand");
@@ -554,7 +556,7 @@ class SkillCommand extends BaseCommand_1.BaseCommand {
 
                     if (!result.inSync) {
 
-                        console.log(`\nRecommendation: run "ospec skill ${this.getInstallAction(provider)} ${result.skillName}${selection.targetDir ? ` ${selection.targetDir}` : ''}" to sync this skill.`);
+                        console.log(`\nRecommendation: run "${(0, helpers_1.formatCliCommand)('ospec', 'skill', this.getInstallAction(provider), result.skillName, selection.targetDir)}" to sync this skill.`);
 
                     }
 

package/dist/commands/StatusCommand.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StatusCommand = void 0;
+const path = require("path");
 const services_1 = require("../services");
+const helpers_1 = require("../utils/helpers");
 const BaseCommand_1 = require("./BaseCommand");
 class StatusCommand extends BaseCommand_1.BaseCommand {
     async execute(projectPath) {
@@ -85,6 +87,9 @@ class StatusCommand extends BaseCommand_1.BaseCommand {
                 console.log(`  ${status}: ${count}`);
             }
             console.log(`Protocol summary: PASS ${changes.totals.pass} | WARN ${changes.totals.warn} | FAIL ${changes.totals.fail}`);
+            if (execution.totalActiveChanges > 1) {
+                console.log('Workflow warning: multiple active changes detected. The default workflow expects one active change unless you are explicitly managing extra work as queued changes.');
+            }
             if (execution.activeChanges.length > 0) {
                 console.log('\nCurrent changes:');
                 for (const change of execution.activeChanges) {
@@ -120,37 +125,46 @@ class StatusCommand extends BaseCommand_1.BaseCommand {
         }
     }
     getRecommendedNextSteps(projectPath, structure, docs, execution, queuedChanges, runReport) {
+        const formatCommand = (...args) => (0, helpers_1.formatCliCommand)('ospec', ...args);
         if (!structure.initialized) {
             return [
-                `Run "ospec init ${projectPath}" to initialize the repository to a change-ready state.`,
+                `Run "${formatCommand('init', projectPath)}" to initialize the repository to a change-ready state.`,
             ];
         }
         if (docs.missingRequired.length > 0 || docs.coverage < 100) {
             return [
                 'The repository is initialized, but the project knowledge layer is still incomplete.',
-                `Run "ospec init ${projectPath}" to reconcile the repository back to change-ready state and regenerate missing project knowledge docs.`,
-                `If you only want to refresh or repair docs without rerunning full init messaging, use "ospec docs generate ${projectPath}".`,
+                `Run "${formatCommand('init', projectPath)}" to reconcile the repository back to change-ready state and regenerate missing project knowledge docs.`,
+                `If you only want to refresh or repair docs without rerunning full init messaging, use "${formatCommand('docs', 'generate', projectPath)}".`,
             ];
         }
         if (execution.totalActiveChanges === 0 && queuedChanges.length === 0) {
             return [
-                `Or run "ospec new <change-name> ${projectPath}" if you want to create the first change from CLI.`,
+                `Or run "${formatCommand('new', '<change-name>', projectPath)}" if you want to create the first change from CLI.`,
             ];
         }
         if (execution.totalActiveChanges === 0 && queuedChanges.length > 0) {
             return [
                 `There is no active change right now, but ${queuedChanges.length} queued change(s) are waiting.`,
-                `Run "ospec queue next ${projectPath}" if you want to activate the next queued change manually.`,
-                `Or run "ospec run start ${projectPath}" to begin explicit queue tracking.`,
+                `Run "${formatCommand('queue', 'next', projectPath)}" if you want to activate the next queued change manually.`,
+                `Or run "${formatCommand('run', 'start', projectPath)}" to begin explicit queue tracking.`,
+            ];
+        }
+        if (execution.totalActiveChanges > 1) {
+            return [
+                `Multiple active changes are present. The default workflow expects one active change, but ${execution.totalActiveChanges} were found.`,
+                `Resolve the repository back to a single active change before using "${formatCommand('run', 'start', projectPath)}".`,
+                `For additional work, create queued changes explicitly with "${formatCommand('queue', 'add', '<change-name>', projectPath)}".`,
             ];
         }
         const currentChange = execution.activeChanges[0];
+        const currentChangePath = path.join(projectPath, 'changes', 'active', currentChange.name);
         const nextSteps = [
-            `Continue the active change "${currentChange.name}" with "ospec progress ${projectPath}/changes/active/${currentChange.name}".`,
-            `Run "ospec verify ${projectPath}/changes/active/${currentChange.name}" before trying to archive it.`,
+            `Continue the active change "${currentChange.name}" with "${formatCommand('progress', currentChangePath)}".`,
+            `Run "${formatCommand('verify', currentChangePath)}" before trying to archive it.`,
         ];
         if (queuedChanges.length > 0) {
-            nextSteps.push(`There are ${queuedChanges.length} queued change(s) waiting behind the active one. Use "ospec run ${runReport.currentRun ? 'step' : 'start'} ${projectPath}" when you want explicit queue progression.`);
+            nextSteps.push(`There are ${queuedChanges.length} queued change(s) waiting behind the active one. Use "${formatCommand('run', runReport.currentRun ? 'step' : 'start', projectPath)}" when you want explicit queue progression.`);
         }
         return nextSteps;
     }

package/dist/commands/UpdateCommand.js

@@ -18,8 +18,14 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         const protocolResult = await services_1.services.projectService.syncProtocolGuidance(targetPath);
         const toolingResult = await this.syncProjectTooling(targetPath, protocolResult.documentLanguage);
         const pluginResult = await this.syncEnabledPluginAssets(targetPath);
+        const archiveResult = await this.syncArchiveLayout(targetPath);
         const skillResult = await this.syncInstalledSkills();
-        const refreshedFiles = [...protocolResult.refreshedFiles, ...toolingResult.refreshedFiles, ...pluginResult.refreshedFiles];
+        const refreshedFiles = Array.from(new Set([
+            ...protocolResult.refreshedFiles,
+            ...toolingResult.refreshedFiles,
+            ...pluginResult.refreshedFiles,
+            ...(archiveResult.configSaved ? ['.skillrc'] : []),
+        ]));
         const createdFiles = [...protocolResult.createdFiles, ...toolingResult.createdFiles, ...pluginResult.createdFiles];
         const skippedFiles = [...protocolResult.skippedFiles, ...toolingResult.skippedFiles, ...pluginResult.skippedFiles];
         this.success(`Updated OSpec assets for ${protocolResult.projectName}`);
@@ -40,8 +46,14 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         if (pluginResult.configSaved) {
             this.info('  plugin config normalized: .skillrc');
         }
-        this.info('  note: update refreshes protocol docs, tooling, hooks, managed skills, and managed assets for already-enabled plugins');
-        this.info('  note: it does not enable, disable, or migrate existing changes automatically');
+        if (archiveResult.configSaved) {
+            this.info('  archive layout normalized: .skillrc');
+        }
+        if (archiveResult.migratedChanges.length > 0) {
+            this.info(`  archived changes migrated: ${archiveResult.migratedChanges.length}`);
+        }
+        this.info('  note: update refreshes protocol docs, tooling, hooks, managed skills, managed assets for already-enabled plugins, and the archive layout when needed');
+        this.info('  note: it does not enable, disable, or migrate active or queued changes automatically');
     }
     async syncProjectTooling(rootDir, documentLanguage) {
         const toolingPaths = [
@@ -222,6 +234,100 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         }
         return { createdFiles, skippedFiles };
     }
+    async syncArchiveLayout(rootDir) {
+        const rawConfig = await services_1.services.fileService.readJSON((0, path_1.join)(rootDir, '.skillrc'));
+        const config = await services_1.services.configManager.loadConfig(rootDir);
+        const nextConfig = JSON.parse(JSON.stringify(config));
+        const archivedRoot = (0, path_1.join)(rootDir, 'changes', 'archived');
+        const migratedChanges = [];
+        if (await services_1.services.fileService.exists(archivedRoot)) {
+            const entryNames = (await services_1.services.fileService.readDir(archivedRoot)).sort((left, right) => left.localeCompare(right));
+            for (const entryName of entryNames) {
+                const entryPath = (0, path_1.join)(archivedRoot, entryName);
+                const stat = await services_1.services.fileService.stat(entryPath);
+                if (!stat.isDirectory()) {
+                    continue;
+                }
+                const parsed = this.parseLegacyArchiveDirName(entryName);
+                if (!parsed) {
+                    continue;
+                }
+                const archivedState = await this.readArchivedChangeState(entryPath);
+                if (!archivedState) {
+                    continue;
+                }
+                const archiveDayRoot = (0, path_1.join)(archivedRoot, parsed.month, parsed.day);
+                await services_1.services.fileService.ensureDir(archiveDayRoot);
+                const targetPath = await this.resolveArchiveMigrationTarget(archiveDayRoot, archivedState.feature);
+                await services_1.services.fileService.move(entryPath, targetPath);
+                migratedChanges.push({
+                    from: `changes/archived/${entryName}`,
+                    to: this.toRelativePath(rootDir, targetPath),
+                });
+            }
+        }
+        let configSaved = false;
+        if (nextConfig.archive?.layout !== 'month-day') {
+            nextConfig.archive = {
+                ...(nextConfig.archive || {}),
+                layout: 'month-day',
+            };
+            await services_1.services.configManager.saveConfig(rootDir, nextConfig);
+            configSaved = true;
+        }
+        else if (!rawConfig?.archive || rawConfig.archive.layout !== 'month-day') {
+            await services_1.services.configManager.saveConfig(rootDir, nextConfig);
+            configSaved = true;
+        }
+        return {
+            configSaved,
+            migratedChanges,
+        };
+    }
+    parseLegacyArchiveDirName(entryName) {
+        const match = /^(\d{4}-\d{2}-\d{2})-(.+)$/.exec(entryName);
+        if (!match) {
+            return null;
+        }
+        return {
+            month: match[1].slice(0, 7),
+            day: match[1],
+            leafName: match[2],
+        };
+    }
+    async resolveArchiveMigrationTarget(archiveDayRoot, leafName) {
+        let candidate = leafName;
+        let index = 2;
+        while (await services_1.services.fileService.exists((0, path_1.join)(archiveDayRoot, candidate))) {
+            candidate = `${leafName}-${index}`;
+            index += 1;
+        }
+        return (0, path_1.join)(archiveDayRoot, candidate);
+    }
+    async readArchivedChangeState(entryPath) {
+        const statePath = (0, path_1.join)(entryPath, 'state.json');
+        if (!(await services_1.services.fileService.exists(statePath))) {
+            return null;
+        }
+        try {
+            const state = await services_1.services.fileService.readJSON(statePath);
+            if (typeof state?.feature !== 'string' || state.feature.trim().length === 0) {
+                return null;
+            }
+            if (state.status !== 'archived') {
+                return null;
+            }
+            return {
+                feature: state.feature.trim(),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    toRelativePath(rootDir, targetPath) {
+        return (0, path_1.relative)(rootDir, targetPath).replace(/\\/g, '/');
+    }
     getManagedSkillNames() {
         return ['ospec', 'ospec-change'];
     }

package/dist/core/types.d.ts

@@ -89,6 +89,9 @@ export interface CheckpointPluginConfig {
         auto_pass_stitch_review: boolean;
     };
 }
+export interface ArchiveConfig {
+    layout: 'flat' | 'month-day';
+}
 export interface SkillrcConfig {
     version: string;
     mode: ProjectMode;
@@ -104,6 +107,7 @@ export interface SkillrcConfig {
         include?: string[];
         exclude?: string[];
     };
+    archive?: ArchiveConfig;
     plugins?: {
         stitch?: StitchPluginConfig;
         checkpoint?: CheckpointPluginConfig;

package/dist/services/ConfigManager.js

@@ -81,6 +81,9 @@ class ConfigManager {
             index: {
                 exclude: ['node_modules/**', 'dist/**', '*.test.*'],
             },
+            archive: {
+                layout: 'month-day',
+            },
             plugins: this.createDefaultPluginsConfig(),
             workflow,
         };
@@ -345,6 +348,7 @@ class ConfigManager {
     }
     normalizeConfig(config) {
         const mode = ['lite', 'standard', 'full'].includes(config.mode) ? config.mode : 'full';
+        const archive = config.archive && typeof config.archive === 'object' ? config.archive : {};
         const hooks = config.hooks || {
             'pre-commit': true,
             'post-merge': true,
@@ -370,6 +374,9 @@ class ConfigManager {
             version: config.version === '3.0' ? '4.0' : config.version,
             mode,
             documentLanguage: this.normalizeDocumentLanguage(config.documentLanguage),
+            archive: {
+                layout: archive.layout === 'month-day' ? 'month-day' : 'flat',
+            },
             hooks: {
                 ...normalizedHooks,
                 ...(legacyWarnDefaults

package/dist/services/ProjectService.js

@@ -4385,71 +4385,15 @@ class ProjectService {
 
 
 
-        const archivedRoot = path_1.default.join(projectRoot, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ARCHIVED);
-
-
-
-
-
-
-
-        await this.fileService.ensureDir(archivedRoot);
-
-
-
-
-
-
-
-        const datePrefix = new Date().toISOString().slice(0, 10);
-
-
+        const config = await this.configManager.loadConfig(projectRoot);
 
 
 
 
 
-        const baseName = `${datePrefix}-${featureState.feature}`;
-
-
-
-
-
-
-
-        let archiveDirName = baseName;
-
-
-
-
-
-
-
-        let archiveIndex = 2;
-
-
 
 
-
-
-
-        while (await this.fileService.exists(path_1.default.join(archivedRoot, archiveDirName))) {
-
-
-
-
-
-
-
-            archiveDirName = `${baseName}-${archiveIndex}`;
-
-
-
-
-
-
-
-            archiveIndex += 1;
+        const archivedRoot = path_1.default.join(projectRoot, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ARCHIVED);
 
 
 
@@ -4457,7 +4401,7 @@ class ProjectService {
 
 
 
-        }
+        await this.fileService.ensureDir(archivedRoot);
 
 
 
@@ -4465,7 +4409,7 @@ class ProjectService {
 
 
 
-        const archivePath = path_1.default.join(archivedRoot, archiveDirName);
+        const archivePath = await this.resolveArchivePath(archivedRoot, featureState.feature, config);
 
 
 
@@ -12449,6 +12393,252 @@ ${formatSuggestion()}
 
 
 
+    async resolveArchivePath(archivedRoot, featureName, config) {
+
+
+
+
+
+        const archiveLayout = config?.archive?.layout === 'month-day' ? 'month-day' : 'flat';
+
+
+
+
+
+        const archiveDate = this.getLocalArchiveDateParts();
+
+
+
+
+
+        if (archiveLayout === 'month-day') {
+
+
+
+
+
+            const archiveDayRoot = path_1.default.join(archivedRoot, archiveDate.month, archiveDate.day);
+
+
+
+
+
+            await this.fileService.ensureDir(archiveDayRoot);
+
+
+
+
+
+            const archiveLeafName = await this.resolveArchiveLeafName(archiveDayRoot, featureName);
+
+
+
+
+
+            return path_1.default.join(archiveDayRoot, archiveLeafName);
+
+
+
+
+
+        }
+
+
+
+
+
+        const archiveDirName = await this.resolveLegacyArchiveDirName(archivedRoot, archiveDate.day, featureName);
+
+
+
+
+
+        return path_1.default.join(archivedRoot, archiveDirName);
+
+
+
+
+
+    }
+
+
+
+
+
+    async resolveArchiveLeafName(archiveDayRoot, featureName) {
+
+
+
+
+
+        let candidate = featureName;
+
+
+
+
+
+        let archiveIndex = 2;
+
+
+
+
+
+        while (await this.fileService.exists(path_1.default.join(archiveDayRoot, candidate))) {
+
+
+
+
+
+            candidate = `${featureName}-${archiveIndex}`;
+
+
+
+
+
+            archiveIndex += 1;
+
+
+
+
+
+        }
+
+
+
+
+
+        return candidate;
+
+
+
+
+
+    }
+
+
+
+
+
+    async resolveLegacyArchiveDirName(archivedRoot, archiveDay, featureName) {
+
+
+
+
+
+        const baseName = `${archiveDay}-${featureName}`;
+
+
+
+
+
+        let candidate = baseName;
+
+
+
+
+
+        let archiveIndex = 2;
+
+
+
+
+
+        while (await this.fileService.exists(path_1.default.join(archivedRoot, candidate))) {
+
+
+
+
+
+            candidate = `${baseName}-${archiveIndex}`;
+
+
+
+
+
+            archiveIndex += 1;
+
+
+
+
+
+        }
+
+
+
+
+
+        return candidate;
+
+
+
+
+
+    }
+
+
+
+
+
+    getLocalArchiveDateParts() {
+
+
+
+
+
+        const now = new Date();
+
+
+
+
+
+        const year = String(now.getFullYear());
+
+
+
+
+
+        const monthNumber = String(now.getMonth() + 1).padStart(2, '0');
+
+
+
+
+
+        const dayNumber = String(now.getDate()).padStart(2, '0');
+
+
+
+
+
+        return {
+
+
+
+
+
+            month: `${year}-${monthNumber}`,
+
+
+
+
+
+            day: `${year}-${monthNumber}-${dayNumber}`,
+
+
+
+
+
+        };
+
+
+
+
+
+    }
+
+
+
+
+
     toRelativePath(rootDir, filePath) {
 
 

package/dist/services/RunService.js

@@ -350,13 +350,59 @@ class RunService {
         if (!(await this.fileService.exists(archivedDir))) {
             return null;
         }
+        const candidatePaths = await this.listArchivedChangeDirectories(archivedDir);
+        const matches = [];
+        for (const candidatePath of candidatePaths) {
+            const statePath = path_1.default.join(candidatePath, constants_1.FILE_NAMES.STATE);
+            if (!(await this.fileService.exists(statePath))) {
+                continue;
+            }
+            try {
+                const state = await this.fileService.readJSON(statePath);
+                if (state?.feature === changeName && state?.status === 'archived') {
+                    matches.push(this.toArchivedRelativePath(archivedDir, candidatePath));
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return matches.sort().at(-1) || null;
+    }
+    async listArchivedChangeDirectories(archivedDir) {
         const entries = await fs_extra_1.default.readdir(archivedDir, { withFileTypes: true });
-        const matched = entries
-            .filter(entry => entry.isDirectory() && entry.name.endsWith(`-${changeName}`))
-            .map(entry => entry.name)
-            .sort()
-            .at(-1);
-        return matched ? `changes/archived/${matched}` : null;
+        const candidates = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const entryPath = path_1.default.join(archivedDir, entry.name);
+            if (/^\d{4}-\d{2}-\d{2}-.+/.test(entry.name)) {
+                candidates.push(entryPath);
+                continue;
+            }
+            if (!/^\d{4}-\d{2}$/.test(entry.name)) {
+                continue;
+            }
+            const dayEntries = await fs_extra_1.default.readdir(entryPath, { withFileTypes: true });
+            for (const dayEntry of dayEntries) {
+                if (!dayEntry.isDirectory() || !/^\d{4}-\d{2}-\d{2}$/.test(dayEntry.name)) {
+                    continue;
+                }
+                const dayPath = path_1.default.join(entryPath, dayEntry.name);
+                const changeEntries = await fs_extra_1.default.readdir(dayPath, { withFileTypes: true });
+                for (const changeEntry of changeEntries) {
+                    if (changeEntry.isDirectory()) {
+                        candidates.push(path_1.default.join(dayPath, changeEntry.name));
+                    }
+                }
+            }
+        }
+        return candidates;
+    }
+    toArchivedRelativePath(archivedDir, candidatePath) {
+        const relativePath = path_1.default.relative(archivedDir, candidatePath).replace(/\\/g, '/');
+        return `changes/archived/${relativePath}`;
     }
     async ensureRunDirectories(rootDir) {
         await Promise.all([

package/dist/utils/helpers.d.ts

@@ -1,5 +1,3 @@
-/**
- * 工具函数
- * TODO: 实现辅助函数
- */
-//# sourceMappingURL=helpers.d.ts.map
+export declare function quoteCliArg(value: string): string;
+export declare function formatCliCommand(...args: Array<string | null | undefined>): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/utils/helpers.js

@@ -1,6 +1,22 @@
 "use strict";
-/**
- * 工具函数
- * TODO: 实现辅助函数
- */
-//# sourceMappingURL=helpers.js.map
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCliCommand = exports.quoteCliArg = void 0;
+function quoteCliArg(value) {
+    const text = String(value ?? '');
+    if (text.length === 0) {
+        return '""';
+    }
+    return /\s/.test(text) ? `"${text.replace(/"/g, '\\"')}"` : text;
+}
+exports.quoteCliArg = quoteCliArg;
+function formatCliCommand(...args) {
+    return args
+        .filter((arg) => arg !== undefined && arg !== null && arg !== '')
+        .map((arg, index) => {
+        const text = String(arg);
+        return index === 0 ? text : quoteCliArg(text);
+    })
+        .join(' ');
+}
+exports.formatCliCommand = formatCliCommand;
+//# sourceMappingURL=helpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,7 @@
     "index:rebuild": "node dist/tools/build-index.js",
     "validate": "node dist/cli/commands/validate.js",
     "release:smoke": "node scripts/release-smoke.js",
+    "release:notes": "node scripts/release-notes.js",
     "release:sync-version": "node scripts/sync-version.js",
     "release:bump:patch": "npm version patch --no-git-tag-version",
     "release:bump:minor": "npm version minor --no-git-tag-version",