@birdie_moblie/open_spec 2.1.7

package/dist/config/presets.js

@@ -0,0 +1,125 @@
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+import { exists, listFilesRecursive, readText, writeText } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { packageRoot } from '../shared/pkg.js';
+import { resolveInside } from '../shared/paths.js';
+import { PluginMinVersionSchema, ProjectConfigPatchSchema, ProjectConfigSchema } from './schema.js';
+import { compareVersions } from '../shared/version.js';
+const ScaffoldEntrySchema = z.object({
+    /** 项目内目标路径，通常与某个 required file hook 的 path 一致 */
+    path: z.string().min(1),
+    /** 相对 presets/ 目录的模板文件 */
+    template: z.string().min(1),
+    description: z.string().optional(),
+}).strict();
+export const TeamPresetSchema = z.object({
+    schemaVersion: z.literal('openspec.team-preset.v1'),
+    id: z.string(),
+    version: z.string(),
+    title: z.string(),
+    description: z.string().optional(),
+    marketplaces: z.array(z.object({
+        name: z.string(),
+        repo: z.string(),
+        ref: z.string(),
+    }).strict()).optional(),
+    plugins: z.array(z.object({
+        name: z.string(),
+        marketplace: z.string(),
+        minVersion: PluginMinVersionSchema.optional(),
+    }).strict()).optional(),
+    configPatch: ProjectConfigPatchSchema.optional(),
+    /** 应用 preset 时按需生成的项目文件：只创建、不覆盖 */
+    scaffold: z.array(ScaffoldEntrySchema).optional(),
+    notes: z.array(z.string()).optional(),
+    warnings: z.array(z.string()).optional(),
+}).strict();
+export function presetsDir() {
+    return path.join(packageRoot(), 'presets');
+}
+export function listPresets() {
+    return listFilesRecursive(presetsDir())
+        .filter((file) => file.endsWith('.yaml') || file.endsWith('.yml'))
+        .map((file) => loadPresetFile(file));
+}
+export function loadPreset(id) {
+    const file = path.join(presetsDir(), `${id}.yaml`);
+    if (!exists(file))
+        throw new AppError('preset_not_found', `找不到 preset: ${id}`);
+    return loadPresetFile(file);
+}
+export function mergePreset(base, preset) {
+    const patch = preset.configPatch ?? { schema: 'spec-product' };
+    const merged = {
+        schema: 'spec-product',
+        taskCategories: { ...base.taskCategories, ...patch.taskCategories },
+        hooks: upsertBy(base.hooks ?? [], patch.hooks ?? [], (item) => item.id),
+        verify: {
+            reviewScope: {
+                ...base.verify?.reviewScope,
+                ...patch.verify?.reviewScope,
+            },
+            failurePolicy: {
+                ...base.verify?.failurePolicy,
+                ...patch.verify?.failurePolicy,
+            },
+        },
+        plugins: mergePluginDependencies(base.plugins ?? [], preset.plugins ?? []),
+        // 宿主已声明的 marketplace 保留自己的 repo/ref：preset 的 ref 只是基线，不能把独立升级过的宿主降回去。
+        marketplaces: [
+            ...(base.marketplaces ?? []),
+            ...(preset.marketplaces ?? []).filter((item) => !(base.marketplaces ?? []).some((existing) => existing.name === item.name)),
+        ],
+        tools: base.tools,
+    };
+    return ProjectConfigSchema.parse(merged);
+}
+/**
+ * 把 preset 声明的模板文件放到项目里。已存在的文件一律不动——
+ * 团队填写后的内容不能被重复 init 覆盖；模板本身带 openspec:fill-me 标记，未填写时 file hook 不会放行。
+ */
+export function scaffoldPreset(projectRoot, preset) {
+    return (preset.scaffold ?? []).map((entry) => {
+        const source = resolveInside(presetsDir(), entry.template, 'preset_template_outside_presets');
+        if (!exists(source))
+            throw new AppError('preset_template_missing', `preset ${preset.id} 缺少模板文件: ${entry.template}`);
+        const target = resolveInside(projectRoot, entry.path, 'scaffold_path_outside_project');
+        if (exists(target))
+            return { path: entry.path, status: 'exists', description: entry.description };
+        writeText(target, readText(source));
+        return { path: entry.path, status: 'created', description: entry.description };
+    });
+}
+function upsertBy(base, patch, key) {
+    const values = new Map(base.map((item) => [key(item), item]));
+    for (const item of patch)
+        values.set(key(item), item);
+    return [...values.values()];
+}
+/** 合并时保留了宿主 ref、且与 preset 基线不同的 marketplace，供 init / preset apply 提示。 */
+export function keptMarketplaceRefs(base, preset) {
+    return (preset.marketplaces ?? []).flatMap((item) => {
+        const existing = (base.marketplaces ?? []).find((candidate) => candidate.name === item.name);
+        return existing && existing.ref !== item.ref ? [{ name: item.name, ref: existing.ref, presetRef: item.ref }] : [];
+    });
+}
+/** 同一插件取较高的 minVersion：宿主提高过的最低版本不被 preset 默认值调低。 */
+function mergePluginDependencies(base, patch) {
+    const previous = new Map(base.map((item) => [`${item.name}@${item.marketplace}`, item]));
+    return upsertBy(base, patch.map((item) => {
+        const existing = previous.get(`${item.name}@${item.marketplace}`)?.minVersion;
+        if (!existing || !item.minVersion)
+            return existing && !item.minVersion ? { ...item, minVersion: existing } : item;
+        return (compareVersions(existing, item.minVersion) ?? 0) > 0 ? { ...item, minVersion: existing } : item;
+    }), (item) => `${item.name}@${item.marketplace}`);
+}
+function loadPresetFile(file) {
+    const result = TeamPresetSchema.safeParse(parseYaml(readText(file)));
+    if (!result.success) {
+        throw new AppError('invalid_preset', `preset 不合法: ${file}`, result.error.issues);
+    }
+    return result.data;
+}
+//# sourceMappingURL=presets.js.map

package/dist/config/schema.d.ts

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+export declare const HOOK_STAGES: readonly ["collect", "parse", "tech", "plan", "execute", "verify"];
+export declare const HOOK_TYPES: readonly ["command", "skill", "notes", "file", "check"];
+export declare const SOURCE_CAPABILITIES: readonly ["requirements", "interfaces", "design"];
+export declare const DEFAULT_TASK_CATEGORIES: Record<string, {
+    notes: string;
+}>;
+export declare const HookSchema: z.ZodObject<{
+    id: z.ZodString;
+    stage: z.ZodEnum<{
+        collect: "collect";
+        parse: "parse";
+        tech: "tech";
+        plan: "plan";
+        execute: "execute";
+        verify: "verify";
+    }>;
+    type: z.ZodOptional<z.ZodEnum<{
+        command: "command";
+        skill: "skill";
+        notes: "notes";
+        file: "file";
+        check: "check";
+    }>>;
+    capability: z.ZodOptional<z.ZodEnum<{
+        requirements: "requirements";
+        interfaces: "interfaces";
+        design: "design";
+    }>>;
+    use: z.ZodOptional<z.ZodString>;
+    operation: z.ZodOptional<z.ZodLiteral<"preview">>;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    name: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    taskCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    command: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodEnum<{
+        project: "project";
+        inScopeChangedFiles: "inScopeChangedFiles";
+    }>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowEmpty: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    purpose: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** 插件最低版本：与插件 manifest 的 version 比较，只接受 major.minor.patch。 */
+export declare const PluginMinVersionSchema: z.ZodString;
+declare const ProjectConfigObjectSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"spec-product">;
+    taskCategories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        stage: z.ZodEnum<{
+            collect: "collect";
+            parse: "parse";
+            tech: "tech";
+            plan: "plan";
+            execute: "execute";
+            verify: "verify";
+        }>;
+        type: z.ZodOptional<z.ZodEnum<{
+            command: "command";
+            skill: "skill";
+            notes: "notes";
+            file: "file";
+            check: "check";
+        }>>;
+        capability: z.ZodOptional<z.ZodEnum<{
+            requirements: "requirements";
+            interfaces: "interfaces";
+            design: "design";
+        }>>;
+        use: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodLiteral<"preview">>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        name: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+        taskCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodEnum<{
+            project: "project";
+            inScopeChangedFiles: "inScopeChangedFiles";
+        }>>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowEmpty: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        purpose: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    verify: z.ZodOptional<z.ZodObject<{
+        reviewScope: z.ZodOptional<z.ZodObject<{
+            includeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        failurePolicy: z.ZodOptional<z.ZodObject<{
+            failOnHookFailure: z.ZodOptional<z.ZodBoolean>;
+            failOnRequiredCommandFailure: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        marketplace: z.ZodString;
+        minVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    marketplaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        repo: z.ZodString;
+        ref: z.ZodString;
+    }, z.core.$strict>>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+    }>>>;
+}, z.core.$strict>;
+export declare const ProjectConfigPatchSchema: z.ZodObject<{
+    schema: z.ZodOptional<z.ZodLiteral<"spec-product">>;
+    taskCategories: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>>;
+    hooks: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        stage: z.ZodEnum<{
+            collect: "collect";
+            parse: "parse";
+            tech: "tech";
+            plan: "plan";
+            execute: "execute";
+            verify: "verify";
+        }>;
+        type: z.ZodOptional<z.ZodEnum<{
+            command: "command";
+            skill: "skill";
+            notes: "notes";
+            file: "file";
+            check: "check";
+        }>>;
+        capability: z.ZodOptional<z.ZodEnum<{
+            requirements: "requirements";
+            interfaces: "interfaces";
+            design: "design";
+        }>>;
+        use: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodLiteral<"preview">>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        name: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+        taskCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodEnum<{
+            project: "project";
+            inScopeChangedFiles: "inScopeChangedFiles";
+        }>>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowEmpty: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        purpose: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    verify: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        reviewScope: z.ZodOptional<z.ZodObject<{
+            includeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        failurePolicy: z.ZodOptional<z.ZodObject<{
+            failOnHookFailure: z.ZodOptional<z.ZodBoolean>;
+            failOnRequiredCommandFailure: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    plugins: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        marketplace: z.ZodString;
+        minVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    marketplaces: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        repo: z.ZodString;
+        ref: z.ZodString;
+    }, z.core.$strict>>>>;
+    tools: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+    }>>>>;
+}, z.core.$strict>;
+export declare const ProjectConfigSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"spec-product">;
+    taskCategories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        stage: z.ZodEnum<{
+            collect: "collect";
+            parse: "parse";
+            tech: "tech";
+            plan: "plan";
+            execute: "execute";
+            verify: "verify";
+        }>;
+        type: z.ZodOptional<z.ZodEnum<{
+            command: "command";
+            skill: "skill";
+            notes: "notes";
+            file: "file";
+            check: "check";
+        }>>;
+        capability: z.ZodOptional<z.ZodEnum<{
+            requirements: "requirements";
+            interfaces: "interfaces";
+            design: "design";
+        }>>;
+        use: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodLiteral<"preview">>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        name: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+        taskCategories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodEnum<{
+            project: "project";
+            inScopeChangedFiles: "inScopeChangedFiles";
+        }>>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowEmpty: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        purpose: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    verify: z.ZodOptional<z.ZodObject<{
+        reviewScope: z.ZodOptional<z.ZodObject<{
+            includeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludeDirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        failurePolicy: z.ZodOptional<z.ZodObject<{
+            failOnHookFailure: z.ZodOptional<z.ZodBoolean>;
+            failOnRequiredCommandFailure: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        marketplace: z.ZodString;
+        minVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    marketplaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        repo: z.ZodString;
+        ref: z.ZodString;
+    }, z.core.$strict>>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        cursor: "cursor";
+    }>>>;
+}, z.core.$strict>;
+export type ProjectConfig = z.infer<typeof ProjectConfigObjectSchema>;
+export type ProjectHook = z.infer<typeof HookSchema>;
+export declare function effectiveTaskCategories(config: Pick<ProjectConfig, 'taskCategories'>): Record<string, {
+    notes: string;
+}>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.js

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+export const HOOK_STAGES = ['collect', 'parse', 'tech', 'plan', 'execute', 'verify'];
+export const HOOK_TYPES = ['command', 'skill', 'notes', 'file', 'check'];
+export const SOURCE_CAPABILITIES = ['requirements', 'interfaces', 'design'];
+export const DEFAULT_TASK_CATEGORIES = {
+    ui: { notes: '遵循项目 UI 约定，优先复用现有组件与设计 token。' },
+    logic: { notes: '保持业务逻辑内聚，避免跨边界改动。' },
+    'api-codegen': { notes: '仅通过已声明的接口源生成客户端或模型代码。' },
+    test: { notes: '覆盖本次变更的可观察行为与回归路径。' },
+    infra: { notes: '基础设施改动需可回滚，并写明影响范围。' },
+};
+const PathTokenSchema = z.string().min(1).refine((value) => value !== '.' && value !== '..' && !/[\\/\0]/.test(value), '标识不能包含路径语义');
+const CategoryIdSchema = PathTokenSchema.refine((value) => !['__proto__', 'prototype', 'constructor'].includes(value), '分类 ID 不能使用保留对象键');
+const RelativePathSchema = z.string().min(1).refine((value) => {
+    const normalized = value.replace(/\\/g, '/');
+    return !normalized.startsWith('/')
+        && !/^[A-Za-z]:\//.test(normalized)
+        && !normalized.includes('\0')
+        && !normalized.split('/').includes('..');
+}, '必须是未越界的相对路径');
+export const HookSchema = z.object({
+    id: PathTokenSchema,
+    stage: z.enum(HOOK_STAGES),
+    type: z.enum(HOOK_TYPES).optional(),
+    capability: z.enum(SOURCE_CAPABILITIES).optional(),
+    use: z.string().min(1).optional(),
+    operation: z.literal('preview').optional(),
+    input: z.record(z.string(), z.unknown()).optional(),
+    inputFiles: z.array(RelativePathSchema).optional(),
+    name: z.string().min(1).optional(),
+    notes: z.string().min(1).optional(),
+    taskCategories: z.array(CategoryIdSchema).optional(),
+    command: z.string().min(1).optional(),
+    target: z.enum(['project', 'inScopeChangedFiles']).optional(),
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+    allowEmpty: z.boolean().optional(),
+    required: z.boolean().optional(),
+    purpose: z.string().optional(),
+    path: RelativePathSchema.optional(),
+    category: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+}).strict().superRefine((hook, ctx) => {
+    const type = hook.type;
+    const allowedByStage = {
+        collect: [undefined, 'skill'],
+        parse: [...HOOK_TYPES],
+        tech: [...HOOK_TYPES],
+        plan: [...HOOK_TYPES],
+        execute: [...HOOK_TYPES],
+        verify: ['command', 'skill', 'file', 'check'],
+    };
+    if (!allowedByStage[hook.stage].includes(type)) {
+        ctx.addIssue({ code: 'custom', message: `${hook.stage} stage 不支持 type: ${String(type)}` });
+    }
+    if (hook.stage === 'collect' && !hook.use && type !== 'skill') {
+        ctx.addIssue({ code: 'custom', message: `collect hook ${hook.id} 需要 use 或 type: skill` });
+    }
+    if (hook.stage !== 'collect' && !type) {
+        ctx.addIssue({ code: 'custom', message: `${hook.stage} hook ${hook.id} 需要 type` });
+    }
+    if (type === 'notes' && !hook.notes)
+        ctx.addIssue({ code: 'custom', message: `notes hook ${hook.id} 需要 notes` });
+    if (type === 'command' && !hook.command && !hook.use)
+        ctx.addIssue({ code: 'custom', message: `command hook ${hook.id} 需要 command` });
+    if (type === 'skill' && !hook.name && !hook.use)
+        ctx.addIssue({ code: 'custom', message: `skill hook ${hook.id} 需要 name` });
+    if (type === 'file' && !hook.path)
+        ctx.addIssue({ code: 'custom', message: `file hook ${hook.id} 需要 path` });
+    if (type === 'check' && (!hook.category || !hook.description)) {
+        ctx.addIssue({ code: 'custom', message: `check hook ${hook.id} 需要 category 与 description` });
+    }
+    if (hook.use && [hook.name, hook.command, hook.path, hook.notes, hook.category, hook.description].some((value) => value !== undefined)) {
+        ctx.addIssue({ code: 'custom', message: `hook ${hook.id} 的 use 与内联实现互斥` });
+    }
+    if (hook.use && hook.stage !== 'collect' && type !== 'command' && type !== 'skill') {
+        ctx.addIssue({ code: 'custom', message: `插件 Hook 仅支持 command/skill: ${hook.id}` });
+    }
+    if (hook.operation && (!hook.use || hook.type !== 'command' || hook.stage === 'collect')) {
+        ctx.addIssue({ code: 'custom', message: `preview 需要非 collect 的 command use: ${hook.id}` });
+    }
+    if (!hook.use && (hook.input || hook.inputFiles)) {
+        ctx.addIssue({ code: 'custom', message: `结构化参数需要插件 use: ${hook.id}` });
+    }
+    if (hook.stage === 'collect' && (hook.input || hook.inputFiles)) {
+        ctx.addIssue({ code: 'custom', message: `collect 沿用旧来源协议，不接受结构化操作参数: ${hook.id}` });
+    }
+    if (hook.taskCategories && hook.stage !== 'execute') {
+        ctx.addIssue({ code: 'custom', message: `taskCategories 只允许用于 execute hook: ${hook.id}` });
+    }
+});
+const TaskCategorySchema = z.object({ notes: z.string().optional() }).strict();
+const ImmutableMarketplaceRefSchema = z.string().min(1).refine((value) => /^[0-9a-f]{40}$/i.test(value) || /^refs\/tags\/[^/]+$/.test(value), 'marketplace ref 必须是完整 Git SHA 或 refs/tags/<tag>');
+const MarketplaceSchema = z.object({
+    name: PathTokenSchema,
+    repo: z.string().min(1),
+    ref: ImmutableMarketplaceRefSchema,
+}).strict();
+/** 插件最低版本：与插件 manifest 的 version 比较，只接受 major.minor.patch。 */
+export const PluginMinVersionSchema = z.string().regex(/^\d+\.\d+\.\d+$/, 'minVersion 必须是 major.minor.patch');
+const PluginDependencySchema = z.object({
+    name: PathTokenSchema,
+    marketplace: PathTokenSchema,
+    minVersion: PluginMinVersionSchema.optional(),
+}).strict();
+const VerifySchema = z.object({
+    reviewScope: z.object({
+        includeDirs: z.array(z.string()).optional(),
+        excludeDirs: z.array(z.string()).optional(),
+    }).strict().optional(),
+    failurePolicy: z.object({
+        failOnHookFailure: z.boolean().optional(),
+        failOnRequiredCommandFailure: z.boolean().optional(),
+    }).strict().optional(),
+}).strict();
+const ProjectConfigObjectSchema = z.object({
+    schema: z.literal('spec-product'),
+    taskCategories: z.record(CategoryIdSchema, TaskCategorySchema.nullable()).optional(),
+    hooks: z.array(HookSchema).optional(),
+    verify: VerifySchema.optional(),
+    plugins: z.array(PluginDependencySchema).optional(),
+    marketplaces: z.array(MarketplaceSchema).optional(),
+    tools: z.array(z.enum(['claude', 'codex', 'cursor'])).optional(),
+}).strict();
+export const ProjectConfigPatchSchema = ProjectConfigObjectSchema.partial();
+export const ProjectConfigSchema = ProjectConfigObjectSchema.superRefine((config, ctx) => {
+    const ids = new Set();
+    const collectCapabilities = new Set();
+    for (const [index, hook] of (config.hooks ?? []).entries()) {
+        if (ids.has(hook.id))
+            ctx.addIssue({ code: 'custom', path: ['hooks', index, 'id'], message: `重复 hook id: ${hook.id}` });
+        ids.add(hook.id);
+        if (hook.stage === 'collect' && hook.capability) {
+            if (collectCapabilities.has(hook.capability)) {
+                ctx.addIssue({ code: 'custom', path: ['hooks', index, 'capability'], message: `重复 collect capability: ${hook.capability}` });
+            }
+            collectCapabilities.add(hook.capability);
+        }
+    }
+    const marketplaceNames = new Set();
+    for (const [index, marketplace] of (config.marketplaces ?? []).entries()) {
+        if (marketplaceNames.has(marketplace.name)) {
+            ctx.addIssue({ code: 'custom', path: ['marketplaces', index, 'name'], message: `重复 marketplace: ${marketplace.name}` });
+        }
+        marketplaceNames.add(marketplace.name);
+    }
+    const pluginSelectors = new Set();
+    for (const [index, plugin] of (config.plugins ?? []).entries()) {
+        const selector = `${plugin.name}@${plugin.marketplace}`;
+        if (pluginSelectors.has(selector)) {
+            ctx.addIssue({ code: 'custom', path: ['plugins', index], message: `重复 plugin: ${selector}` });
+        }
+        pluginSelectors.add(selector);
+    }
+    if (new Set(config.tools ?? []).size !== (config.tools ?? []).length) {
+        ctx.addIssue({ code: 'custom', path: ['tools'], message: 'tools 不能重复' });
+    }
+    const categories = new Set(Object.keys(effectiveTaskCategories(config)));
+    for (const [index, hook] of (config.hooks ?? []).entries()) {
+        for (const category of hook.taskCategories ?? []) {
+            if (!categories.has(category)) {
+                ctx.addIssue({ code: 'custom', path: ['hooks', index, 'taskCategories'], message: `未知 task category: ${category}` });
+            }
+        }
+    }
+});
+export function effectiveTaskCategories(config) {
+    const merged = Object.assign(Object.create(null), DEFAULT_TASK_CATEGORIES);
+    for (const [id, value] of Object.entries(config.taskCategories ?? {})) {
+        if (value === null) {
+            delete merged[id];
+            continue;
+        }
+        merged[id] = { notes: value.notes ?? merged[id]?.notes ?? '' };
+    }
+    return merged;
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/archive.d.ts

@@ -0,0 +1,5 @@
+export declare function archiveChange(projectRoot: string, changeName: string): {
+    from: string;
+    to: string;
+};
+//# sourceMappingURL=archive.d.ts.map

package/dist/core/archive.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { exists, ensureDir, removePath, writeText } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { changeRoot, stampArchivePath } from './change.js';
+import { appendEvent } from './state.js';
+import { NODES } from './types.js';
+import { requireChange } from './change.js';
+import { renameSync } from 'node:fs';
+import { loadVerifiedReport } from './verify.js';
+import { collectPendingWork, renderPendingWork } from './todo.js';
+import { loadConfig } from '../config/load.js';
+import { resolveInside } from '../shared/paths.js';
+export function archiveChange(projectRoot, changeName) {
+    const state = requireChange(projectRoot, changeName);
+    if (state.node !== NODES.COMPLETED) {
+        throw new AppError('not_completed', '只有 completed 的 change 才能归档');
+    }
+    const from = changeRoot(projectRoot, changeName);
+    const toRel = stampArchivePath(projectRoot, changeName);
+    const to = resolveInside(projectRoot, toRel, 'archive_path_outside_project');
+    if (!exists(from))
+        throw new AppError('change_not_found', `找不到 change: ${changeName}`);
+    const report = state.verifyRunId ? loadVerifiedReport(projectRoot, changeName, state.verifyRunId) : undefined;
+    const pending = report?.pendingWork ?? collectPendingWork(projectRoot, changeName, loadConfig(projectRoot));
+    writeText(resolveInside(from, 'reports/pending-work.md'), renderPendingWork(pending));
+    ensureDir(path.dirname(to));
+    appendEvent(projectRoot, changeName, 'change.archived', { to: toRel });
+    removePath(path.join(from, '.opsx', 'workers'));
+    removePath(path.join(from, '.opsx', 'source-update-backup'));
+    renameSync(from, to);
+    return { from: path.relative(projectRoot, from), to: toRel };
+}
+//# sourceMappingURL=archive.js.map

package/dist/core/change.d.ts

@@ -0,0 +1,12 @@
+import type { ChangeState } from './types.js';
+export declare function changeRoot(projectRoot: string, changeName: string): string;
+export declare function createChange(projectRoot: string, name: string, description?: string): ChangeState;
+export declare function listChangeNames(projectRoot: string): string[];
+export declare function requireChange(projectRoot: string, changeName: string): ChangeState;
+export declare function resolveChangeName(projectRoot: string, requested?: string): string;
+export declare function artifactPath(projectRoot: string, changeName: string, relative: string): string;
+export declare function artifactRel(changeName: string, relative: string): string;
+export declare function stampArchivePath(projectRoot: string, changeName: string): string;
+export declare function assertChangeName(name: string): void;
+export declare function readOptional(projectRoot: string, changeName: string, relative: string): string | null;
+//# sourceMappingURL=change.d.ts.map