@birdie_moblie/open_spec 2.1.7 → 2.2.0

package/dist/config/presets.js

@@ -1,91 +1,180 @@
-import path from 'node:path';
-import { parse as parseYaml } from 'yaml';
+import { isDeepStrictEqual } from 'node:util';
 import { z } from 'zod';
-import { exists, listFilesRecursive, readText, writeText } from '../shared/fs.js';
+import { exists, 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 { ProjectConfigSchema } from './schema.js';
 import { compareVersions } from '../shared/version.js';
-const ScaffoldEntrySchema = z.object({
+export const ScaffoldEntrySchema = z.object({
     /** 项目内目标路径，通常与某个 required file hook 的 path 一致 */
     path: z.string().min(1),
-    /** 相对 presets/ 目录的模板文件 */
+    /** 模板文件，相对该 preset 所在目录 */
     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' };
+/**
+ * 生效配置 = preset 基线 + 项目层，项目层优先：分类按名覆盖（null 删除）；hook 同 ID 整条替换并保留基线位置，
+ * disableHooks 按 ID 去掉基线 hook，项目新增 hook 追加在后；验收设置按字段覆盖；插件取较高 minVersion；
+ * marketplace 以项目声明为准，基线只补缺；tools 只来自项目层。没有基线时项目层原样即生效配置。
+ */
+export function resolveEffectiveConfig(layer, baseline) {
+    const { disableHooks = [], hookOrder, ...project } = layer;
+    if (!baseline) {
+        if (disableHooks.length > 0) {
+            throw new AppError('disable_hooks_without_preset', `disableHooks 只能禁用 preset 中的 hook，当前未引用 preset: ${disableHooks.join(', ')}`);
+        }
+        if (!hookOrder)
+            return parseEffective(project, '项目配置不合法');
+        return parseEffective({ ...project, hooks: orderHooks(project.hooks ?? [], hookOrder) }, '项目配置不合法');
+    }
+    const base = baseline.patch;
+    const baseHooks = base.hooks ?? [];
+    const baseHookIds = new Set(baseHooks.map((hook) => hook.id));
+    const ownHooks = project.hooks ?? [];
+    const unknown = disableHooks.filter((id) => !baseHookIds.has(id));
+    if (unknown.length > 0) {
+        throw new AppError('unknown_disabled_hook', `disableHooks 引用了 preset ${baseline.id} 中不存在的 hook: ${unknown.join(', ')}`);
+    }
+    const conflicting = ownHooks.filter((hook) => disableHooks.includes(hook.id)).map((hook) => hook.id);
+    if (conflicting.length > 0) {
+        throw new AppError('hook_disabled_and_overridden', `hook 不能同时被禁用和覆盖: ${conflicting.join(', ')}`);
+    }
+    const overrides = new Map(ownHooks.map((hook) => [hook.id, hook]));
+    const hooks = orderHooks([
+        ...baseHooks.filter((hook) => !disableHooks.includes(hook.id)).map((hook) => overrides.get(hook.id) ?? hook),
+        ...ownHooks.filter((hook) => !baseHookIds.has(hook.id)),
+    ], hookOrder);
+    const reviewScope = { ...base.verify?.reviewScope, ...project.verify?.reviewScope };
+    const failurePolicy = { ...base.verify?.failurePolicy, ...project.verify?.failurePolicy };
+    const plugins = mergePluginDependencies(base.plugins ?? [], project.plugins ?? []);
+    const marketplaces = [
+        ...(project.marketplaces ?? []),
+        ...(base.marketplaces ?? []).filter((item) => !(project.marketplaces ?? []).some((existing) => existing.name === item.name)),
+    ];
+    const taskCategories = { ...base.taskCategories, ...project.taskCategories };
     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,
+        ...(Object.keys(taskCategories).length > 0 ? { taskCategories } : {}),
+        ...(hooks.length > 0 ? { hooks } : {}),
+        ...(base.verify || project.verify ? {
+            verify: {
+                ...(Object.keys(reviewScope).length > 0 ? { reviewScope } : {}),
+                ...(Object.keys(failurePolicy).length > 0 ? { failurePolicy } : {}),
             },
-            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,
+        } : {}),
+        ...(plugins.length > 0 ? { plugins } : {}),
+        ...(marketplaces.length > 0 ? { marketplaces } : {}),
+        ...(project.tools ? { tools: project.tools } : {}),
     };
-    return ProjectConfigSchema.parse(merged);
+    return parseEffective(merged, `preset ${baseline.id} 与项目配置合成后不合法`);
+}
+/** 逐项标注生效配置的来源，供查看生效配置、升级提示遮蔽与迁移使用。 */
+export function describeOrigins(layer, baseline) {
+    const base = baseline?.patch ?? {};
+    const classify = (inBase, inProject) => (inBase ? (inProject ? 'override' : 'preset') : 'project');
+    const taskCategories = {};
+    for (const id of new Set([...Object.keys(base.taskCategories ?? {}), ...Object.keys(layer.taskCategories ?? {})])) {
+        const own = layer.taskCategories?.[id];
+        taskCategories[id] = own === null ? 'removed' : classify(Boolean(base.taskCategories?.[id]), own !== undefined);
+    }
+    const hooks = {};
+    const ownHookIds = new Set((layer.hooks ?? []).map((hook) => hook.id));
+    for (const hook of base.hooks ?? []) {
+        hooks[hook.id] = (layer.disableHooks ?? []).includes(hook.id) ? 'removed' : classify(true, ownHookIds.has(hook.id));
+    }
+    for (const id of ownHookIds)
+        hooks[id] ??= 'project';
+    const selector = (item) => `${item.name}@${item.marketplace}`;
+    const plugins = {};
+    const ownPlugins = new Set((layer.plugins ?? []).map(selector));
+    // 同一插件取较高的最低版本：生效条目仍等于 preset 的条目时，项目的声明没有改变生效值。
+    const effectivePlugins = new Map(mergePluginDependencies(base.plugins ?? [], layer.plugins ?? []).map((item) => [selector(item), item]));
+    for (const item of base.plugins ?? []) {
+        const id = selector(item);
+        plugins[id] = ownPlugins.has(id) && !isDeepStrictEqual(effectivePlugins.get(id), item) ? 'override' : 'preset';
+    }
+    for (const id of ownPlugins)
+        plugins[id] ??= 'project';
+    const marketplaces = {};
+    const ownMarkets = new Set((layer.marketplaces ?? []).map((item) => item.name));
+    for (const item of base.marketplaces ?? [])
+        marketplaces[item.name] = classify(true, ownMarkets.has(item.name));
+    for (const name of ownMarkets)
+        marketplaces[name] ??= 'project';
+    const verifyFields = (value) => Object.entries(value ?? {})
+        .flatMap(([group, fields]) => Object.keys(fields ?? {}).map((field) => `${group}.${field}`));
+    const verify = {};
+    const ownVerify = new Set(verifyFields(layer.verify));
+    for (const id of verifyFields(base.verify))
+        verify[id] = classify(true, ownVerify.has(id));
+    for (const id of ownVerify)
+        verify[id] ??= 'project';
+    return { taskCategories, hooks, plugins, marketplaces, verify };
+}
+/**
+ * 按条目比较两个基线：分类按名、hook 按 ID、插件按 selector、marketplace 按名；
+ * 验收设置与合成一样按字段，条目为 `<分组>.<字段>`（如 reviewScope.excludeDirs）。
+ */
+export function diffBaselines(previous, next) {
+    const keyed = (patch) => ({
+        taskCategories: new Map(Object.entries(patch.taskCategories ?? {}).map(([id, value]) => [id, JSON.stringify(value)])),
+        hooks: new Map((patch.hooks ?? []).map((hook) => [hook.id, JSON.stringify(hook)])),
+        plugins: new Map((patch.plugins ?? []).map((item) => [`${item.name}@${item.marketplace}`, JSON.stringify(item)])),
+        marketplaces: new Map((patch.marketplaces ?? []).map((item) => [item.name, JSON.stringify(item)])),
+        verify: new Map(Object.entries(patch.verify ?? {}).flatMap(([group, fields]) => Object.entries(fields ?? {}).map(([field, value]) => [`${group}.${field}`, JSON.stringify(value)]))),
+    });
+    const before = keyed(previous);
+    const after = keyed(next);
+    const sections = Object.keys(before);
+    return Object.fromEntries(sections.map((section) => {
+        const old = before[section];
+        const now = after[section];
+        return [section, {
+                added: [...now.keys()].filter((id) => !old.has(id)),
+                changed: [...now.keys()].filter((id) => old.has(id) && old.get(id) !== now.get(id)),
+                removed: [...old.keys()].filter((id) => !now.has(id)),
+            }];
+    }));
+}
+/** 按 hookOrder 重排各阶段：列出的 ID 依次在前，其余保持原相对顺序；各阶段仍占原来的位置。 */
+function orderHooks(hooks, hookOrder) {
+    if (!hookOrder)
+        return hooks;
+    const result = [...hooks];
+    for (const [stage, ids] of Object.entries(hookOrder)) {
+        const slots = hooks.flatMap((hook, index) => (hook.stage === stage ? [index] : []));
+        const inStage = slots.map((index) => hooks[index]);
+        const unknown = ids.filter((id) => !inStage.some((hook) => hook.id === id));
+        if (unknown.length > 0) {
+            throw new AppError('unknown_ordered_hook', `hookOrder.${stage} 引用了该阶段不存在的 hook: ${unknown.join(', ')}`);
+        }
+        const ordered = [
+            ...ids.map((id) => inStage.find((hook) => hook.id === id)),
+            ...inStage.filter((hook) => !ids.includes(hook.id)),
+        ];
+        slots.forEach((slot, position) => { result[slot] = ordered[position]; });
+    }
+    return result;
+}
+function parseEffective(config, message) {
+    const result = ProjectConfigSchema.safeParse(config);
+    if (!result.success)
+        throw new AppError('invalid_config', message, result.error.issues);
+    return result.data;
 }
 /**
  * 把 preset 声明的模板文件放到项目里。已存在的文件一律不动——
- * 团队填写后的内容不能被重复 init 覆盖；模板本身带 openspec:fill-me 标记，未填写时 file hook 不会放行。
+ * 团队填写后的内容不能被重复引用或升级覆盖；模板本身带 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');
+export function scaffoldFrom(projectRoot, templateRoot, presetId, entries) {
+    const planned = entries.map((entry) => {
+        const source = resolveInside(templateRoot, 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');
+            throw new AppError('preset_template_missing', `preset ${presetId} 缺少模板文件: ${entry.template}`);
+        return { entry, source, target: resolveInside(projectRoot, entry.path, 'scaffold_path_outside_project') };
+    });
+    return planned.map(({ entry, source, target }) => {
         if (exists(target))
             return { path: entry.path, status: 'exists', description: entry.description };
         writeText(target, readText(source));
@@ -98,13 +187,6 @@ function upsertBy(base, patch, key) {
         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]));
@@ -115,11 +197,4 @@ function mergePluginDependencies(base, patch) {
         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

@@ -48,10 +48,21 @@ export declare const HookSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/** 团队 preset 引用：独立 Git 仓库中的一个 preset，ref 同样必须不可变。 */
+declare const PresetReferenceSchema: z.ZodObject<{
+    repo: z.ZodString;
+    ref: z.ZodString;
+    id: 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">;
+    preset: z.ZodOptional<z.ZodObject<{
+        repo: z.ZodString;
+        ref: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
     taskCategories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>;
@@ -123,12 +134,31 @@ declare const ProjectConfigObjectSchema: z.ZodObject<{
         codex: "codex";
         cursor: "cursor";
     }>>>;
+    disableHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hookOrder: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        collect: "collect";
+        parse: "parse";
+        tech: "tech";
+        plan: "plan";
+        execute: "execute";
+        verify: "verify";
+    }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
 }, z.core.$strict>;
 export declare const ProjectConfigPatchSchema: z.ZodObject<{
-    schema: z.ZodOptional<z.ZodLiteral<"spec-product">>;
+    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>>>;
     taskCategories: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>>;
+    schema: z.ZodOptional<z.ZodLiteral<"spec-product">>;
     hooks: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         stage: z.ZodEnum<{
@@ -172,7 +202,80 @@ export declare const ProjectConfigPatchSchema: z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>;
-    verify: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+    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>;
+/**
+ * 项目层：只做结构与重复校验。分类引用等跨层约束要在合成生效配置后才能判定，
+ * 因为 hook 引用的分类可能只由 preset 定义。
+ */
+export declare const ProjectConfigLayerSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"spec-product">;
+    preset: z.ZodOptional<z.ZodObject<{
+        repo: z.ZodString;
+        ref: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+    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>>;
@@ -181,25 +284,39 @@ export declare const ProjectConfigPatchSchema: 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<{
+    }, 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.ZodOptional<z.ZodArray<z.ZodObject<{
+    }, 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.ZodOptional<z.ZodArray<z.ZodEnum<{
+    }, z.core.$strict>>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         claude: "claude";
         codex: "codex";
         cursor: "cursor";
-    }>>>>;
+    }>>>;
+    disableHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hookOrder: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        collect: "collect";
+        parse: "parse";
+        tech: "tech";
+        plan: "plan";
+        execute: "execute";
+        verify: "verify";
+    }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
 }, z.core.$strict>;
 export declare const ProjectConfigSchema: z.ZodObject<{
     schema: z.ZodLiteral<"spec-product">;
+    preset: z.ZodOptional<z.ZodObject<{
+        repo: z.ZodString;
+        ref: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
     taskCategories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>>;
@@ -271,9 +388,19 @@ export declare const ProjectConfigSchema: z.ZodObject<{
         codex: "codex";
         cursor: "cursor";
     }>>>;
+    disableHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hookOrder: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        collect: "collect";
+        parse: "parse";
+        tech: "tech";
+        plan: "plan";
+        execute: "execute";
+        verify: "verify";
+    }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
 }, z.core.$strict>;
 export type ProjectConfig = z.infer<typeof ProjectConfigObjectSchema>;
 export type ProjectHook = z.infer<typeof HookSchema>;
+export type PresetReference = z.infer<typeof PresetReferenceSchema>;
 export declare function effectiveTaskCategories(config: Pick<ProjectConfig, 'taskCategories'>): Record<string, {
     notes: string;
 }>;

package/dist/config/schema.js

@@ -91,6 +91,12 @@ export const HookSchema = z.object({
 });
 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>');
+/** 团队 preset 引用：独立 Git 仓库中的一个 preset，ref 同样必须不可变。 */
+const PresetReferenceSchema = z.object({
+    repo: z.string().min(1),
+    ref: z.string().min(1).refine((value) => /^[0-9a-f]{40}$/i.test(value) || /^refs\/tags\/[^/]+$/.test(value), 'preset ref 必须是完整 Git SHA 或 refs/tags/<tag>'),
+    id: PathTokenSchema,
+}).strict();
 const MarketplaceSchema = z.object({
     name: PathTokenSchema,
     repo: z.string().min(1),
@@ -115,15 +121,22 @@ const VerifySchema = z.object({
 }).strict();
 const ProjectConfigObjectSchema = z.object({
     schema: z.literal('spec-product'),
+    /** 引用的团队 preset；其余字段是项目层，与 preset 基线合成生效配置。 */
+    preset: PresetReferenceSchema.optional(),
     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(),
+    /** 按 ID 禁用 preset 基线中的 hook；只属于项目层，不进入生效配置。 */
+    disableHooks: z.array(PathTokenSchema).optional(),
+    /** 按阶段指定 hook 顺序：列出的 ID 依次排在该阶段最前，其余保持原相对顺序；只属于项目层。 */
+    hookOrder: z.partialRecord(z.enum(HOOK_STAGES), z.array(PathTokenSchema)).optional(),
 }).strict();
-export const ProjectConfigPatchSchema = ProjectConfigObjectSchema.partial();
-export const ProjectConfigSchema = ProjectConfigObjectSchema.superRefine((config, ctx) => {
+export const ProjectConfigPatchSchema = ProjectConfigObjectSchema.omit({ preset: true, disableHooks: true, hookOrder: true }).partial();
+/** 单层内即可判定的约束：重复项。项目层与生效配置都要满足。 */
+function checkDuplicates(config, ctx) {
     const ids = new Set();
     const collectCapabilities = new Set();
     for (const [index, hook] of (config.hooks ?? []).entries()) {
@@ -155,6 +168,21 @@ export const ProjectConfigSchema = ProjectConfigObjectSchema.superRefine((config
     if (new Set(config.tools ?? []).size !== (config.tools ?? []).length) {
         ctx.addIssue({ code: 'custom', path: ['tools'], message: 'tools 不能重复' });
     }
+    if (new Set(config.disableHooks ?? []).size !== (config.disableHooks ?? []).length) {
+        ctx.addIssue({ code: 'custom', path: ['disableHooks'], message: 'disableHooks 不能重复' });
+    }
+    for (const [stage, ids] of Object.entries(config.hookOrder ?? {})) {
+        if (new Set(ids).size !== ids.length)
+            ctx.addIssue({ code: 'custom', path: ['hookOrder', stage], message: `hookOrder.${stage} 不能重复` });
+    }
+}
+/**
+ * 项目层：只做结构与重复校验。分类引用等跨层约束要在合成生效配置后才能判定，
+ * 因为 hook 引用的分类可能只由 preset 定义。
+ */
+export const ProjectConfigLayerSchema = ProjectConfigObjectSchema.superRefine(checkDuplicates);
+export const ProjectConfigSchema = ProjectConfigObjectSchema.superRefine((config, ctx) => {
+    checkDuplicates(config, ctx);
     const categories = new Set(Object.keys(effectiveTaskCategories(config)));
     for (const [index, hook] of (config.hooks ?? []).entries()) {
         for (const category of hook.taskCategories ?? []) {

package/dist/core/source-operations.js

@@ -1,10 +1,11 @@
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { configPathOf } from '../config/load.js';
+import { presetLockPath } from '../config/preset-repo.js';
 import { resolveAdapterEntry } from '../marketplace/adapters.js';
 import { readPluginInput, runPluginCommand, sameIdentity } from '../hooks/plugin-runtime.js';
 import { sha256File } from '../shared/hash.js';
-import { readText, writeJson } from '../shared/fs.js';
+import { exists, readText, writeJson } from '../shared/fs.js';
 import { AppError } from '../shared/errors.js';
 import { artifactPath, artifactRel, requireChange } from './change.js';
 import { loadLedger } from './sources.js';
@@ -19,6 +20,10 @@ export function operationContext(root, change, binding, outputDir, inputFile, wo
     const configPath = configPathOf(root);
     if (configPath)
         params.files.push(path.relative(root, configPath));
+    // 引用 preset 时生效规则还取决于锁定的 preset 快照，锁变化同样要让指纹失效。
+    const presetLock = presetLockPath(root);
+    if (exists(presetLock))
+        params.files.push(path.relative(root, presetLock));
     if (binding.kind === 'adapter') {
         if (state.sourceRevision !== state.collectedRevision)
             throw new AppError('source_not_collected', '来源尚未完成采集');

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { listPresets, loadPreset, type ScaffoldResult } from './config/presets.js';
+import { type ScaffoldResult } from './config/presets.js';
 import { effectiveTaskCategories, type ProjectConfig } from './config/schema.js';
 import { createChange, listChangeNames, requireChange, resolveChangeName } from './core/change.js';
 import { nextAction } from './core/flow.js';
@@ -22,6 +22,11 @@ export declare function project(cwd?: string): {
     projectRoot: string;
     config: {
         schema: "spec-product";
+        preset?: {
+            repo: string;
+            ref: string;
+            id: string;
+        } | undefined;
         taskCategories?: Record<string, {
             notes?: string | undefined;
         } | null> | undefined;
@@ -69,12 +74,19 @@ export declare function project(cwd?: string): {
             ref: string;
         }[] | undefined;
         tools?: ("claude" | "codex" | "cursor")[] | undefined;
+        disableHooks?: string[] | undefined;
+        hookOrder?: Partial<Record<"collect" | "parse" | "tech" | "plan" | "execute" | "verify", string[]>> | undefined;
     };
 };
 export declare function initProject(input: {
     cwd?: string;
     tools?: HostId[];
-    preset?: string;
+    /** 引用 preset 仓库中的 preset；等同于初始化后执行 preset use */
+    preset?: {
+        id: string;
+        repo: string;
+        ref: string;
+    };
     yes?: boolean;
     skipPlugins?: boolean;
     /** 每个耗时步骤开始前调用一次，供 CLI 在终端反馈进度；缺省静默。 */
@@ -92,7 +104,7 @@ export declare function initProject(input: {
     }>;
     scaffold: ScaffoldResult[];
 };
-export { createChange, listChangeNames, requireChange, resolveChangeName, nextAction, buildInstructions, addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg, createWorker, acceptWorker, answerWorker, cancelWorker, approveGate, rejectGate, isKnownGate, runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState, archiveChange, collectPendingWork, renderPendingWork, listPresets, loadPreset, addMarketplace, listMarketplaces, installPlugin, verifyDelivery, verifyInstallCli, effectiveTaskCategories, BUILTIN_MARKETPLACE, assertPluginsPresent, inspectMarketplaceDependencies, inspectHookEntries, };
+export { createChange, listChangeNames, requireChange, resolveChangeName, nextAction, buildInstructions, addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg, createWorker, acceptWorker, answerWorker, cancelWorker, approveGate, rejectGate, isKnownGate, runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState, archiveChange, collectPendingWork, renderPendingWork, addMarketplace, listMarketplaces, installPlugin, verifyDelivery, verifyInstallCli, effectiveTaskCategories, BUILTIN_MARKETPLACE, assertPluginsPresent, inspectMarketplaceDependencies, inspectHookEntries, };
 export type { HostId, GateId, WorkflowName, ProjectConfig };
 export { analyzeUsage, renderUsageMarkdown } from './usage/analyze.js';
 export type { UsageReport, UsageOptions, Tokens, RateCard, Billing } from './usage/types.js';