# 项目配置规则

`.craftkit/project.json` 是可共享的结构化项目元数据，不是依赖锁文件或秘密配置中心。

## 字段原则

- `initialization.mode` 使用 `existing` 或 `new`。
- `project` 记录名称、用途和项目类型。
- `technology` 记录语言、框架、构建工具和数据库类型，不记录连接信息。每个框架使用 `name`、`version`、`profile` 对象；精确版本未知或公共 profile 不存在时不得猜测。
- `code` 记录相对源码根、包根和模块。
- `dependencies.internal` 只记录用户确认可在当前仓库共享的依赖标识和用途。
- `frontend` 记录前端框架、组件库、组件根和文档入口；路径必须是项目相对路径，版本必须有依赖清单、锁文件或用户确认作为证据。
- `commands` 只记录经过项目文件或用户确认的命令。
- `documents` 区分过程文档、共享设计和归档目录，字段及回退行为见下方“文档目录”；归档规则不写入公司固定目录或外部系统凭据。
- `guidance` 指向 `.craftkit/` 内的索引入口。
- `initialization.references` 记录参考项目名称、用途、允许提炼范围和可共享的相对位置。

## Schema 兼容

- Schema 1 没有顶层 `modules` 时，将顶层技术栈和 `code` 边界作为根模块候选，不自动改写文件。
- Schema 2 保留顶层 `technology` 原有字段类型，增加 `modules[].technology` 表达模块级精确信息。
- `modules[].technology.preferredProfiles` 是项目确认的偏好，不表示当前机器已安装对应插件。
- 插件发现、匹配状态和本机路径属于运行时信息，只存在于任务上下文或 `.craftkit/local/`。
- 所有读取方完成 Schema 1/2 双读后，`init` 才能在用户确认差异后写入 Schema 2。

模块根使用项目相对正斜线路径。目标路径命中多个模块时采用最长根；同长度重复根视为配置冲突。

## 文档目录

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| `workRoot` | `.craftkit/local/tasks` | 开发中的需求、计划、设计草稿和验证记录，默认不提交 |
| `designRoot` | `.craftkit/designs` | 用户明确要求共享或正式交付的设计文档 |
| `archiveRoot` | `docs/archive` | 用户按归档规则处理的历史或正式归档文档 |
| `archiveRules` | `[]` | 归档匹配、目标、转换和校验规则 |
| `lifecycle.onTaskComplete` | `preview` | 任务完成时生成关闭预览，不自动删除文件 |
| `lifecycle.localRetentionDays` | `7` | 本地过程文档建议保留天数，超期仍需进入关闭预览 |
| `lifecycle.trackedFiles` | `review-required` | 已跟踪文档必须逐项评审后才能删除 |
| `lifecycle.personalConfig` | `retain` | 本地个人配置不属于任务清理范围 |

- 路径使用项目相对路径和正斜杠，不能包含 `..`、用户目录或其他个人机器绝对路径。
- 初始化只写入配置，不预建空任务目录、设计目录或归档目录。
- 成熟项目已有明确的过程文档或正式设计目录时优先延续，并展示证据；根目录中的 README、CHANGELOG 或总体工作流不能单独证明根目录是任务文档目录。
- 用户未指定共享用途时，Skill 生成的过程文档使用 `workRoot`；用户明确要求共享或正式交付时使用 `designRoot`。
- `archiveRoot` 不作为开发中内容的默认写入位置，归档必须按归档 Skill 的规则另行执行。
- `workRoot/<task>/task.json` 记录任务状态、可见性和文件归属；字段结构及关闭规则由 `knowledge:document-output` 维护。
- 生命周期配置缺失时按表中默认值解释，不为读取兼容性强制改写旧项目配置。
- `localRetentionDays` 只用于提示，不构成删除授权；`personalConfig` 当前仅允许 `retain`。
- 旧配置只有 `archiveRoot` 时继续兼容读取；初始化更新时展示新增字段及用途，确认后保守合并。

## 前端组件信息

- `frontend.framework` 引用 `technology.frameworks` 中已确认的前端框架名称。
- `frontend.componentLibraries` 使用 `name`、`version`、`source` 对象；`source` 说明依赖清单或锁文件等证据入口。
- `frontend.componentRoots` 记录项目自研或封装组件的相对目录。
- `frontend.documentation` 记录项目内组件文档、类型、示例或 Storybook 的相对入口。
- 未确认的数组保持为空；不得写入私有仓库认证地址或个人绝对路径。

## 合并规则

- 未在本次扫描中验证的既有字段不得删除。
- 新证据与旧值冲突时保留旧值并展示差异，用户确认后修改。
- 数组按语义去重，不因大小写或路径分隔符制造重复项。
- 所有项目路径使用正斜杠相对路径。
- 模板中的空值表示待补充，不代表扫描失败。

## 框架版本

```json
{
  "name": "framework-name",
  "version": "已确认的精确版本或空字符串",
  "profile": "已存在且匹配的公共 profile 或空字符串"
}
```

- 先从构建清单和锁文件探测，再由用户确认。
- 普通项目只选择当前 profile，不登记无关版本。
- 升级计划中的目标版本属于项目决策或迁移资料，不得冒充当前运行版本。
- 内部框架可以记录名称和版本，但其规则只能位于项目 `.craftkit/standards/`。