@clawplays/ospec-cli 0.3.7 → 0.3.8

package/dist/services/QueueService.js

@@ -77,6 +77,7 @@ class QueueService {
         await this.fileService.writeJSON(statePath, state);
         await this.updateFrontmatterStatus(path_1.default.join(activePath, constants_1.FILE_NAMES.PROPOSAL), 'active');
         await this.updateFrontmatterStatus(path_1.default.join(activePath, constants_1.FILE_NAMES.VERIFICATION), 'verifying');
+        await this.projectService.rebaseMovedChangeMarkdownLinks(queuedPath, activePath);
         const item = await this.buildQueuedChangeStatusItem(rootDir, activePath);
         if (!item) {
             throw new Error(`Activated change state could not be read: ${changeName}`);

package/dist/services/TemplateGenerator.js

@@ -63,20 +63,20 @@ optional_steps: [${optionalSteps.map((s) => `"${s}"`).join(', ')}]
         // 添加核心任务
         if (coreRequiredSteps.length > 0) {
             coreRequiredSteps.forEach((step, index) => {
-                content += `- [ ] ${index + 1}. ${step}\n`;
+                content += `- [ ] ${step}\n`;
             });
         }
         else {
-            content += `- [ ] 1. 实现功能\n`;
-            content += `- [ ] 2. 更新文档\n`;
-            content += `- [ ] 3. 更新索引\n`;
-            content += `- [ ] 4. 运行测试\n`;
+            content += `- [ ] 实现功能\n`;
+            content += `- [ ] 更新文档\n`;
+            content += `- [ ] 更新索引\n`;
+            content += `- [ ] 运行测试\n`;
         }
         // 添加可选任务
         if (optionalSteps.length > 0) {
             content += `\n### 可选任务\n\n`;
             optionalSteps.forEach((step, index) => {
-                content += `- [ ] ${index + 1}. ${step}\n`;
+                content += `- [ ] ${step}\n`;
             });
         }
         return content;

package/dist/services/templates/ExecutionTemplateBuilder.js

@@ -9,6 +9,8 @@ class ExecutionTemplateBuilder extends TemplateBuilderBase_1.TemplateBuilderBase
     }
     generateProposalTemplate(input) {
         const context = this.inputs.normalizeFeatureTemplateInput(input);
+        this.setReferenceDocumentContext(context.projectRoot, context.documentPath);
+        try {
         const created = this.getCurrentDate();
         const projectDocs = context.projectContext.projectDocs ?? [];
         const moduleSkills = context.projectContext.moduleSkills ?? [];
@@ -156,30 +158,36 @@ ${this.formatChecklist(context.acceptanceCriteria, 'قيد التحديد')}`;
             affects: context.affects,
             flags: context.flags,
         }, this.copy(context.documentLanguage, zh, en, ja, ar));
+        }
+        finally {
+            this.clearReferenceDocumentContext();
+        }
     }
     generateTasksTemplate(input) {
         const context = this.inputs.normalizeFeatureTemplateInput(input);
+        this.setReferenceDocumentContext(context.projectRoot, context.documentPath);
+        try {
         const created = this.getCurrentDate();
         const projectDocs = context.projectContext.projectDocs ?? [];
         const moduleSkills = context.projectContext.moduleSkills ?? [];
         const optionalStepTasksZh = context.optionalSteps.length > 0
             ? context.optionalSteps
-                .map((step, index) => `- [ ] ${index + 7}. 完成可选步骤 \`${step}\` 的文档和验证`)
+                .map((step) => `- [ ] 完成可选步骤 \`${step}\` 的文档和验证`)
                 .join('\n')
             : '';
         const optionalStepTasksEn = context.optionalSteps.length > 0
             ? context.optionalSteps
-                .map((step, index) => `- [ ] ${index + 7}. Finish docs and verification for optional step \`${step}\``)
+                .map((step) => `- [ ] Finish docs and verification for optional step \`${step}\``)
                 .join('\n')
             : '';
         const optionalStepTasksJa = context.optionalSteps.length > 0
             ? context.optionalSteps
-                .map((step, index) => `- [ ] ${index + 7}. オプション手順 \`${step}\` の文書と検証を完了する`)
+                .map((step) => `- [ ] オプション手順 \`${step}\` の文書と検証を完了する`)
                 .join('\n')
             : '';
         const optionalStepTasksAr = context.optionalSteps.length > 0
             ? context.optionalSteps
-                .map((step, index) => `- [ ] ${index + 7}. أكمل التوثيق والتحقق للخطوة الاختيارية \`${step}\``)
+                .map((step) => `- [ ] أكمل التوثيق والتحقق للخطوة الاختيارية \`${step}\``)
                 .join('\n')
             : '';
         const zh = `## 上下文引用
@@ -192,12 +200,12 @@ ${this.formatReferenceList(moduleSkills, '待补充')}
 
 ## 任务清单
 
-- [ ] 1. 完成实现
-- [ ] 2. 对齐项目规划文档与本次 change 的边界
-- [ ] 3. 更新涉及模块的 \`SKILL.md\`
-- [ ] 4. 更新相关 API / 设计 / 计划文档
-- [ ] 5. 重新生成 \`SKILL.index.json\`
-- [ ] 6. 执行验证并更新 \`verification.md\`
+- [ ] 完成实现
+- [ ] 对齐项目规划文档与本次 change 的边界
+- [ ] 更新涉及模块的 \`SKILL.md\`
+- [ ] 更新相关 API / 设计 / 计划文档
+- [ ] 重新生成 \`SKILL.index.json\`
+- [ ] 执行验证并更新 \`verification.md\`
 ${optionalStepTasksZh}`.trim();
         const en = `## Context References
 
@@ -209,12 +217,12 @@ ${this.formatReferenceList(moduleSkills, 'TBD')}
 
 ## Task Checklist
 
-- [ ] 1. Implement the change
-- [ ] 2. Align project planning docs with this change boundary
-- [ ] 3. Update affected \`SKILL.md\` files
-- [ ] 4. Update related API / design / planning docs
-- [ ] 5. Rebuild \`SKILL.index.json\`
-- [ ] 6. Run verification and update \`verification.md\`
+- [ ] Implement the change
+- [ ] Align project planning docs with this change boundary
+- [ ] Update affected \`SKILL.md\` files
+- [ ] Update related API / design / planning docs
+- [ ] Rebuild \`SKILL.index.json\`
+- [ ] Run verification and update \`verification.md\`
 ${optionalStepTasksEn}`.trim();
         const ja = `## 参照コンテキスト
 
@@ -226,12 +234,12 @@ ${this.formatReferenceList(moduleSkills, '未定')}
 
 ## タスクチェックリスト
 
-- [ ] 1. change を実装する
-- [ ] 2. この change の境界に合わせてプロジェクト計画文書を揃える
-- [ ] 3. 影響を受ける \`SKILL.md\` を更新する
-- [ ] 4. 関連する API / 設計 / 計画文書を更新する
-- [ ] 5. \`SKILL.index.json\` を再生成する
-- [ ] 6. 検証を実行して \`verification.md\` を更新する
+- [ ] change を実装する
+- [ ] この change の境界に合わせてプロジェクト計画文書を揃える
+- [ ] 影響を受ける \`SKILL.md\` を更新する
+- [ ] 関連する API / 設計 / 計画文書を更新する
+- [ ] \`SKILL.index.json\` を再生成する
+- [ ] 検証を実行して \`verification.md\` を更新する
 ${optionalStepTasksJa}`.trim();
         const ar = `## مراجع السياق
 
@@ -243,21 +251,27 @@ ${this.formatReferenceList(moduleSkills, 'قيد التحديد')}
 
 ## قائمة المهام
 
-- [ ] 1. نفّذ التغيير
-- [ ] 2. وحّد وثائق تخطيط المشروع مع حدود هذا change
-- [ ] 3. حدّث ملفات \`SKILL.md\` المتأثرة
-- [ ] 4. حدّث وثائق API / التصميم / التخطيط ذات الصلة
-- [ ] 5. أعد بناء \`SKILL.index.json\`
-- [ ] 6. نفّذ التحقق وحدّث \`verification.md\`
+- [ ] نفّذ التغيير
+- [ ] وحّد وثائق تخطيط المشروع مع حدود هذا change
+- [ ] حدّث ملفات \`SKILL.md\` المتأثرة
+- [ ] حدّث وثائق API / التصميم / التخطيط ذات الصلة
+- [ ] أعد بناء \`SKILL.index.json\`
+- [ ] نفّذ التحقق وحدّث \`verification.md\`
 ${optionalStepTasksAr}`.trim();
         return this.withFrontmatter({
             feature: context.feature,
             created,
             optional_steps: context.optionalSteps,
         }, this.copy(context.documentLanguage, zh, en, ja, ar));
+        }
+        finally {
+            this.clearReferenceDocumentContext();
+        }
     }
     generateVerificationTemplate(input) {
         const context = this.inputs.normalizeFeatureTemplateInput(input);
+        this.setReferenceDocumentContext(context.projectRoot, context.documentPath);
+        try {
         const created = this.getCurrentDate();
         const projectDocs = context.projectContext.projectDocs ?? [];
         const moduleSkills = context.projectContext.moduleSkills ?? [];
@@ -365,9 +379,15 @@ ${this.formatChecklist(context.acceptanceCriteria, 'معيار قبول 1')}
             optional_steps: context.optionalSteps,
             passed_optional_steps: [],
         }, this.copy(context.documentLanguage, zh, en, ja, ar));
+        }
+        finally {
+            this.clearReferenceDocumentContext();
+        }
     }
     generateReviewTemplate(input) {
         const context = this.inputs.normalizeFeatureTemplateInput(input);
+        this.setReferenceDocumentContext(context.projectRoot, context.documentPath);
+        try {
         const created = this.getCurrentDate();
         const projectDocs = context.projectContext.projectDocs ?? [];
         const moduleSkills = context.projectContext.moduleSkills ?? [];
@@ -520,6 +540,10 @@ ${this.formatReferenceList(linkedKnowledgeDocs, 'قيد التحديد')}
             created,
             status: 'pending_review',
         }, this.copy(context.documentLanguage, zh, en, ja, ar));
+        }
+        finally {
+            this.clearReferenceDocumentContext();
+        }
     }
 }
 exports.ExecutionTemplateBuilder = ExecutionTemplateBuilder;

package/dist/services/templates/TemplateBuilderBase.d.ts

@@ -1,6 +1,10 @@
 import { FeatureProjectReference, TemplateDocumentLanguage } from './templateTypes';
 type FrontmatterValue = string | number | boolean | string[];
 export declare abstract class TemplateBuilderBase {
+    private referenceProjectRoot?;
+    private referenceDocumentPath?;
+    protected setReferenceDocumentContext(projectRoot: string | undefined, documentPath: string | undefined): void;
+    protected clearReferenceDocumentContext(): void;
     protected getCurrentDate(): string;
     protected isEnglish(language: TemplateDocumentLanguage): boolean;
     protected copy(language: TemplateDocumentLanguage, zh: string, en: string, ja?: string, ar?: string): string;
@@ -13,6 +17,7 @@ export declare abstract class TemplateBuilderBase {
     protected formatReferenceList(items: FeatureProjectReference[], emptyFallback: string): string;
     protected formatReferenceChecklist(items: FeatureProjectReference[], emptyFallback: string): string;
     protected withFrontmatter(fields: Record<string, FrontmatterValue | undefined>, body: string): string;
+    private resolveReferenceHref;
     private toYamlValue;
 }
 export {};

package/dist/services/templates/TemplateBuilderBase.js

@@ -1,7 +1,19 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TemplateBuilderBase = void 0;
+const path_1 = __importDefault(require("path"));
 class TemplateBuilderBase {
+    setReferenceDocumentContext(projectRoot, documentPath) {
+        this.referenceProjectRoot = typeof projectRoot === 'string' && projectRoot.trim().length > 0 ? projectRoot : undefined;
+        this.referenceDocumentPath = typeof documentPath === 'string' && documentPath.trim().length > 0 ? documentPath : undefined;
+    }
+    clearReferenceDocumentContext() {
+        this.referenceProjectRoot = undefined;
+        this.referenceDocumentPath = undefined;
+    }
     getCurrentDate() {
         return new Date().toISOString().slice(0, 10);
     }
@@ -40,13 +52,17 @@ class TemplateBuilderBase {
         if (items.length === 0) {
             return `- ${emptyFallback}`;
         }
-        return items.map(item => `- ${item.title}: \`${item.path}\``).join('\n');
+        return items
+            .map(item => `- ${item.title}: [${item.path}](${this.resolveReferenceHref(item.path)})`)
+            .join('\n');
     }
     formatReferenceChecklist(items, emptyFallback) {
         if (items.length === 0) {
             return `- [ ] ${emptyFallback}`;
         }
-        return items.map(item => `- [ ] ${item.path}`).join('\n');
+        return items
+            .map(item => `- [ ] ${item.title}: [${item.path}](${this.resolveReferenceHref(item.path)})`)
+            .join('\n');
     }
     withFrontmatter(fields, body) {
         const frontmatter = Object.entries(fields)
@@ -55,6 +71,19 @@ class TemplateBuilderBase {
             .join('\n');
         return `---\n${frontmatter}\n---\n\n${body.trim()}\n`;
     }
+    resolveReferenceHref(referencePath) {
+        const normalizedReferencePath = String(referencePath || '').replace(/\\/g, '/');
+        if (!normalizedReferencePath) {
+            return normalizedReferencePath;
+        }
+        if (!this.referenceProjectRoot || !this.referenceDocumentPath) {
+            return normalizedReferencePath;
+        }
+        const targetPath = path_1.default.resolve(this.referenceProjectRoot, normalizedReferencePath);
+        const documentDir = path_1.default.dirname(this.referenceDocumentPath);
+        const relativePath = path_1.default.relative(documentDir, targetPath).replace(/\\/g, '/');
+        return relativePath || '.';
+    }
     toYamlValue(value) {
         if (Array.isArray(value)) {
             return `[${value.map(item => JSON.stringify(item)).join(', ')}]`;

package/dist/services/templates/TemplateInputFactory.js

@@ -20,6 +20,8 @@ class TemplateInputFactory {
                 acceptanceCriteria: [...englishDefaults.acceptanceCriteria],
                 projectContext: this.normalizeFeatureProjectContext(),
                 documentLanguage: 'en-US',
+                projectRoot: undefined,
+                documentPath: undefined,
             };
         }
         const documentLanguage = this.normalizeDocumentLanguage(input.documentLanguage);
@@ -38,6 +40,8 @@ class TemplateInputFactory {
             acceptanceCriteria: input.acceptanceCriteria?.map(item => item.trim()).filter(Boolean) ?? [...localizedDefaults.acceptanceCriteria],
             projectContext: this.normalizeFeatureProjectContext(input.projectContext),
             documentLanguage,
+            projectRoot: typeof input.projectRoot === 'string' && input.projectRoot.trim().length > 0 ? input.projectRoot.trim() : undefined,
+            documentPath: typeof input.documentPath === 'string' && input.documentPath.trim().length > 0 ? input.documentPath.trim() : undefined,
         };
         if (!input.background?.trim()) {
             normalized.background = localizedDefaults.background;

package/dist/services/templates/templateTypes.d.ts

@@ -15,6 +15,8 @@ export interface FeatureTemplateInput {
     acceptanceCriteria?: string[];
     projectContext?: FeatureProjectContext;
     documentLanguage?: TemplateDocumentLanguage;
+    projectRoot?: string;
+    documentPath?: string;
 }
 export interface NormalizedFeatureTemplateInput {
     feature: string;
@@ -30,6 +32,8 @@ export interface NormalizedFeatureTemplateInput {
     acceptanceCriteria: string[];
     projectContext: FeatureProjectContext;
     documentLanguage: TemplateDocumentLanguage;
+    projectRoot?: string;
+    documentPath?: string;
 }
 export interface FeatureProjectReference {
     title: string;

package/dist/tools/build-index.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const fsp = require('fs/promises');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const matter = require('gray-matter');
 
 const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', 'changes', 'for-ai']);
 const INDEX_FILE = 'SKILL.index.json';
@@ -282,46 +283,31 @@ async function buildChangeSummary(rootDir, changeName, config) {
   }
 
   if (tasksExists) {
-    const tasks = parseFrontmatter(await fsp.readFile(tasksPath, 'utf8'));
-    const optionalSteps = ensureArray(tasks.data.optional_steps);
-    const missing = activatedSteps.filter(step => !optionalSteps.includes(step));
-    const checklistComplete = !/- \[ \]/.test(tasks.body);
-    checks.push({
-      name: 'tasks.md.optional_steps',
-      status: missing.length === 0 ? 'pass' : 'fail',
-      message:
-        missing.length === 0
-          ? 'All activated optional steps are present in tasks.md'
-          : `Missing optional steps in tasks.md: ${missing.join(', ')}`,
-    });
-    checks.push({
-      name: 'tasks.md.checklist',
-      status: checklistComplete ? 'pass' : 'warn',
-      message: checklistComplete ? 'tasks.md checklist is complete' : 'tasks.md still has unchecked items',
+    const tasks = analyzeWorkflowChecklistDocument(await fsp.readFile(tasksPath, 'utf8'), {
+      name: 'tasks.md',
+      activatedSteps,
+      requiredFields: [
+        ['feature', 'string'],
+        ['created', 'string_or_date'],
+        ['optional_steps', 'array'],
+      ],
     });
+    checks.push(...tasks.checks);
   }
 
   if (verificationExists) {
-    const verification = parseFrontmatter(await fsp.readFile(verificationPath, 'utf8'));
-    const optionalSteps = ensureArray(verification.data.optional_steps);
-    const missing = activatedSteps.filter(step => !optionalSteps.includes(step));
-    const checklistComplete = !/- \[ \]/.test(verification.body);
-    checks.push({
-      name: 'verification.md.optional_steps',
-      status: missing.length === 0 ? 'pass' : 'fail',
-      message:
-        missing.length === 0
-          ? 'All activated optional steps are present in verification.md'
-          : `Missing optional steps in verification.md: ${missing.join(', ')}`,
-    });
-    checks.push({
-      name: 'verification.md.checklist',
-      status: checklistComplete ? 'pass' : 'warn',
-      message:
-        checklistComplete
-          ? 'verification.md checklist is complete'
-          : 'verification.md still has unchecked items',
+    const verification = analyzeWorkflowChecklistDocument(await fsp.readFile(verificationPath, 'utf8'), {
+      name: 'verification.md',
+      activatedSteps,
+      requiredFields: [
+        ['feature', 'string'],
+        ['created', 'string_or_date'],
+        ['status', 'string'],
+        ['optional_steps', 'array'],
+        ['passed_optional_steps', 'array'],
+      ],
     });
+    checks.push(...verification.checks);
   }
 
   const hasProtocolIssues = checks.some(check => check.status !== 'pass');
@@ -476,6 +462,93 @@ function parseSkillFile(content) {
   };
 }
 
+function analyzeWorkflowChecklistDocument(content, options) {
+  const hasFrontmatter = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.test(content);
+  let parsed = null;
+  let parseError = null;
+
+  if (hasFrontmatter) {
+    try {
+      parsed = matter(content);
+    } catch (error) {
+      parseError = error;
+    }
+  }
+
+  const data = parsed?.data ?? {};
+  const optionalStepsFieldValid = Array.isArray(data.optional_steps);
+  const optionalSteps = optionalStepsFieldValid ? ensureArray(data.optional_steps) : [];
+  const invalidRequiredFields = options.requiredFields
+    .filter(([fieldName, fieldType]) => !isValidFrontmatterField(data[fieldName], fieldType))
+    .map(([fieldName]) => fieldName);
+  const missingActivatedSteps = optionalStepsFieldValid
+    ? options.activatedSteps.filter(step => !optionalSteps.includes(step))
+    : [...options.activatedSteps];
+  const checklistItems = parsed?.content.match(/^\s*-\s+\[(?: |x|X)\]\s+.+$/gm) ?? [];
+  const uncheckedItems = parsed?.content.match(/^\s*-\s+\[ \]\s+.+$/gm) ?? [];
+  const checklistStructureValid = checklistItems.length > 0;
+
+  let frontmatterMessage = `${options.name} frontmatter parsed successfully`;
+  if (!hasFrontmatter) {
+    frontmatterMessage = `${options.name} is missing a valid frontmatter block`;
+  } else if (parseError) {
+    frontmatterMessage = `${options.name} frontmatter cannot be parsed: ${parseError.message}`;
+  }
+
+  let requiredFieldsMessage = `${options.name} has all required frontmatter fields`;
+  if (!hasFrontmatter || parseError) {
+    requiredFieldsMessage = `Cannot validate required fields in ${options.name} because frontmatter is invalid`;
+  } else if (invalidRequiredFields.length > 0) {
+    requiredFieldsMessage = `Missing or invalid required fields in ${options.name}: ${invalidRequiredFields.join(', ')}`;
+  }
+
+  let optionalStepsMessage = `All activated optional steps are present in ${options.name}`;
+  if (!optionalStepsFieldValid) {
+    optionalStepsMessage = `${options.name} frontmatter field optional_steps must be an array`;
+  } else if (missingActivatedSteps.length > 0) {
+    optionalStepsMessage = `Missing optional steps in ${options.name}: ${missingActivatedSteps.join(', ')}`;
+  }
+
+  let checklistStatus = 'pass';
+  let checklistMessage = `${options.name} checklist is complete`;
+  if (!hasFrontmatter || parseError) {
+    checklistStatus = 'fail';
+    checklistMessage = `${options.name} checklist cannot be validated because frontmatter is invalid`;
+  } else if (!checklistStructureValid) {
+    checklistStatus = 'fail';
+    checklistMessage = `${options.name} must contain at least one Markdown checklist item`;
+  } else if (uncheckedItems.length > 0) {
+    checklistStatus = 'warn';
+    checklistMessage = `${options.name} still has unchecked items`;
+  }
+
+  return {
+    optionalSteps,
+    checks: [
+      {
+        name: `${options.name}.frontmatter`,
+        status: hasFrontmatter && parseError === null ? 'pass' : 'fail',
+        message: frontmatterMessage,
+      },
+      {
+        name: `${options.name}.required_fields`,
+        status: hasFrontmatter && parseError === null && invalidRequiredFields.length === 0 ? 'pass' : 'fail',
+        message: requiredFieldsMessage,
+      },
+      {
+        name: `${options.name}.optional_steps`,
+        status: optionalStepsFieldValid && missingActivatedSteps.length === 0 ? 'pass' : 'fail',
+        message: optionalStepsMessage,
+      },
+      {
+        name: `${options.name}.checklist`,
+        status: checklistStatus,
+        message: checklistMessage,
+      },
+    ],
+  };
+}
+
 function normalizeLineEndings(content) {
   return String(content || '').replace(/\r\n?/g, '\n');
 }
@@ -517,6 +590,25 @@ function parseFrontmatter(content) {
   };
 }
 
+function isValidFrontmatterField(value, type) {
+  if (type === 'string') {
+    return typeof value === 'string' && value.trim().length > 0;
+  }
+
+  if (type === 'string_or_date') {
+    return (
+      (typeof value === 'string' && value.trim().length > 0) ||
+      (value instanceof Date && !Number.isNaN(value.getTime()))
+    );
+  }
+
+  if (type === 'array') {
+    return Array.isArray(value);
+  }
+
+  return false;
+}
+
 function parseValue(rawValue) {
   if (rawValue === '') {
     return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,10 @@
     "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
     "index:rebuild": "node dist/tools/build-index.js",
     "validate": "node dist/cli/commands/validate.js",
+    "release:cut": "node scripts/release-cut.js",
+    "release:cut:patch": "node scripts/release-cut.js patch",
+    "release:cut:minor": "node scripts/release-cut.js minor",
+    "release:cut:major": "node scripts/release-cut.js major",
     "release:smoke": "node scripts/release-smoke.js",
     "release:notes": "node scripts/release-notes.js",
     "release:sync-version": "node scripts/sync-version.js",