frontend-project-context 1.0.0

package/docs/00-PRODUCT-CONSTITUTION.md

@@ -0,0 +1,166 @@
+# Frontend Project Context — 产品宪法
+
+> 宪法版本：`1.1.1`
+>
+> 状态：`frozen`
+>
+> 生效日期：`2026-09-07`
+
+## 1. 文档权威
+
+本文档是本项目唯一的产品规范真源。它固定产品身份、边界、内核、完成条件和变更规则。
+
+其他文件的职责如下：
+
+- `PROJECT_STATE.json` 只记录当前事实、实现状态、授权和下一步；
+- `RTK.md` 只提供新窗口启动摘要；
+- `README.md` 只提供产品介绍和使用入口；
+- `docs/01` 至 `docs/05`、`docs/08`、`docs/11`、`docs/12` 是形成当前决定的设计或路线说明；
+- `docs/06`、`docs/07`、`docs/09`、`docs/10` 是历史或验证证据；
+- 任务讨论、实验结果和真实项目观察都是输入证据，不能自行改变本文档。
+
+发生冲突时以本文档为准。用户对一次任务的授权不等于修改产品定义；修改本文档必须明确说明要改变哪条宪法决定及原因，并获得用户对该产品变更的明确批准。
+
+## 2. 唯一产品定义
+
+Frontend Project Context 是一个**落在项目中的、位于项目与 AI 编程工具之间的模型无关上下文治理与编译层**。
+
+它把项目明确提供的事实、规则和来源治理为一份人工批准的 `Project Contract`，再针对目录和任务生成最小、可追溯的 `Context Bundle`，投影给已有 AI 编程工具，并检测来源、合同和投影漂移。
+
+```text
+项目显式来源 + 人工规则
+→ 候选项
+→ 人工批准的 Project Contract
+→ 按目录/任务编译的 Context Bundle
+→ AGENTS.md / Ruler / 其他 AI 工具
+→ 来源与投影漂移检查
+```
+
+本产品治理“项目希望 AI 知道什么”，不负责“AI 如何完成开发任务”。
+
+## 3. 固定用户问题
+
+同一项目的知识分散在设计资料、文档、配置、代码和团队约定中，不同 AI 工具会获得不完整、重复或互相冲突的指导，并且规则变化难以追溯。
+
+本产品提供的稳定价值只有三点：
+
+1. 一份有人批准、保留来源的项目合同；
+2. 针对目录和任务的确定性上下文编译；
+3. 同一合同面向多个 AI 消费者的一致投影和漂移检查。
+
+如果某项能力不能直接服务这三点，它默认不属于内核。
+
+## 4. 固定内核
+
+允许自研并长期维护的内核只有：
+
+1. **来源注册与追溯**：登记项目提供的文件、路径和人工决定，保留稳定身份与摘要；
+2. **人工治理的 Project Contract**：区分 fact、policy、reference、validation-description，只有显式人工动作可以批准；
+3. **Scope Compiler**：按 project、path-prefix、file 作用域选择、收窄和显式覆盖合同项；
+4. **Context Renderer**：生成包含必要批准内容和来源引用的稳定 Context Bundle，任务约束不写回合同；
+5. **Projection Boundary**：把同一合同投影为受管 Markdown、AGENTS 或 Ruler 输入，不重建完整工具适配矩阵；
+6. **Conflict and Drift Check**：报告来源、合同和受管投影变化，不自动修复或静默提升规则。
+
+自动 discovery 只是帮助项目首次接入的可选辅助，不是内核完整性的衡量标准。它可以保守地提出候选，但不承担理解所有前端技术和业务语义的责任。
+
+## 5. 永久边界
+
+本产品不负责：
+
+- 调用模型 Provider 或实现 Agent Runtime；
+- 规划、执行、验证或自动修复真实开发任务；
+- 修改业务代码；
+- 管理 Git 分支、提交、合并、推送、PR 或发布；
+- 自动安装依赖、访问网络或修改外部系统；
+- 重建 Kiro、Spec Kit、OpenSpec、Ruler、Rulesync 或成熟 Coding Agent 的完整能力；
+- 为每个框架、路由、状态库、UI 库、构建器、租户或发布平台维护不断增长的识别白名单；
+- 保存 candidate、DecisionRecord、DeliveryRecord 或形成自动修复循环。
+
+Vue、React、uni-app、Vuex、Element UI、路由、租户和发布方式等都是项目内容。内核不认识它们时，项目应通过通用来源与 authoring 能力表达，而不是要求内核新增专用逻辑。
+
+## 6. 不可破坏的不变量
+
+1. `Project Contract` 是项目指导的唯一批准真源；投影不是第二份真源。
+2. 扫描器和 AI 只能提出候选，不能自行批准或修改长期规范。
+3. 每个合同项必须有稳定 ID、类型、作用域、来源、状态和可选验证描述。
+4. 目录级内容只能显式收窄或覆盖上层内容；冲突必须报告，不能静默拼接。
+5. 临时任务约束不能反向改写长期合同。
+6. 默认只读；持久写入必须由当前命令的显式写入选项触发。
+7. 只能覆盖本产品创建且所有权未发生冲突的受管投影。
+8. 未知项目语义是待录入的项目数据，不自动成为产品缺陷。
+9. 真实项目只能验证预先定义的能力，不能直接产生内核需求。
+10. 新技术、新文件名或单个项目差异不能成为扩大 discovery 的充分理由。
+
+## 7. v1 完成定义
+
+v1 只有在以下闭环同时成立时才算产品完成：
+
+1. 可以安全初始化项目合同；
+2. 用户可以通过稳定接口注册任意受支持的文件、路径或人工决定来源；
+3. 用户可以在不直接编辑内部 JSON 的情况下创建 fact、policy、reference、validation-description，设置 project、path-prefix 或 file scope，并显式批准；
+4. Context Bundle 能为指定目标稳定选择合同项，保持 sibling 隔离，携带 AI 消费者完成理解所必需的已批准内容与来源；
+5. 可以生成受管 AGENTS/Markdown 和 Ruler 兼容投影，且不覆盖非受管文件；
+6. 可以阻断过期来源，报告合同冲突和受管投影漂移；
+7. 默认只读、零 Provider、零 Agent loop、零 Git 写入、零业务代码修改；
+8. 命令合同、安装方式、错误类别和自动化验收足以让另一个项目按文档独立使用。
+
+`0.6.0` 已完成通用来源与 scoped item authoring，`0.6.1` 已完成既有不变量审查修补，`0.7.0` 已完成来源变化审查、显式接受、同 ID 修订、废弃、重新批准和重新投影的知识维护闭环。A-01 至 A-30、B0-01、B0-02 和 CLI 测试共 34 项通过，因此 v1 及其知识维护闭环已满足以上完成定义。
+
+### 7.1 Knowledge Maintenance Closure 状态
+
+多人长期使用需要在发现来源漂移后，通过稳定接口完成来源复核、已有合同项修订或废弃、重新批准和重新投影。`0.7.0 — Knowledge Maintenance Closure` 已按 [12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md](./12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md) 完成本地实现和验收，不再需要直接编辑内部 JSON 完成维护闭环。
+
+该版本只扩展现有来源追溯、人工合同治理和漂移检查，没有改变第 2 至第 6 节的产品身份、内核、永久边界和不变量。
+
+## 8. 真实项目与实验规则
+
+`dtg-tmc-mobile` 和 `dtg-tmc-pc` 已经完成 B0。它们证明核心机制和首轮安全修补可以落在真实仓库结构中。
+
+从本宪法生效起：
+
+- 不再通过增加真实项目来枚举前端技术；
+- 不要求第三个项目才能完成 v1；
+- B0 报告只保留为证据，不再作为自动需求队列；
+- B1/Provider 对照属于可选价值评估，不是 v1 工程完成门槛；
+- 只有先写出固定、可证伪的产品假设，真实项目才可以再次用于验证该假设；
+- 验证失败先判断是内核不变量失败、项目数据缺失还是适配器问题，后两者不得进入内核修补循环。
+
+## 9. 需求分类与拒绝规则
+
+任何新增建议必须先归入且只能归入一类：
+
+- **内核缺陷**：违反第 6 节不变量或第 7 节既定完成条件，可以进入设计；
+- **项目数据**：某项目自己的技术、目录、规则和业务语义，由 Project Contract 表达；
+- **可选适配器**：减少某种来源导入或消费者输出成本，不改变内核；
+- **外部工具职责**：继续采用现成工具，本项目拒绝实现。
+
+无法证明属于内核缺陷的建议，不得进入核心实现。多个项目重复出现也只能提高审查优先级，不能绕过这一分类。
+
+## 10. 当前事实职责与阶段停止规则
+
+会随实施推进而变化的当前版本、实现结果、授权状态和唯一下一工作入口，只由 `PROJECT_STATE.json` 记录；`RTK.md` 可以提供等价摘要。本文不再冻结某个会过期的阶段为“当前下一步”，避免已完成阶段与最高权威文档产生冲突。
+
+`PROJECT_STATE.json` 中记录候选方向、路线或下一步，不等于授权其设计、实现或外部操作。任何新阶段都必须先按第 9 节分类，并获得与其影响相匹配的单独授权。
+
+每一阶段达到自身停止条件后都必须停止，先同步当前事实和证据，再等待下一阶段明确授权。路线批准不得被解释为产品实现、Git 写入、真实项目访问、Provider/网络使用或正式发布授权；第 5 至第 6 节的永久边界与不变量始终优先。
+
+## 11. 宪法变更规则
+
+修改本文档必须同时满足：
+
+1. 明确指出要改变的章节；
+2. 说明现有定义为什么无法表达真实用户问题，而不仅是无法识别某种技术；
+3. 说明对内核、非目标、完成条件和已有用户的影响；
+4. 获得用户对该产品方向变化的明确批准；
+5. 同步提升宪法版本，并更新 `PROJECT_STATE.json`。
+
+普通实现、Bug 修复、实验、项目接入和对话推断均无权修改宪法。
+
+## 12. `1.1.1` 治理一致性修订记录
+
+本次修订经用户于 `2026-09-07` 明确授权，只处理已经完成的 `0.7.0` 与本文旧阶段叙述之间的治理冲突：
+
+1. 第 7 节同步 `0.7.0` 已完成和 34 项验收事实；
+2. 第 10 节删除会随时间失效的具体“当前下一步”，把当前事实、授权和下一步的唯一记录职责交还给 `PROJECT_STATE.json`；
+3. 产品身份、固定用户问题、内核、永久边界、不变量、需求分类和已有用户数据合同均未改变；
+4. 本次修订不授权产品代码、Git、真实项目、自托管 Project Contract、看板、团队验收或发布工作。

package/docs/01-PRODUCT-CORE.md

@@ -0,0 +1,143 @@
+# 01 — 产品核心
+
+> 权威说明：本文记录产品定义的形成过程；当前唯一规范真源是 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)。
+
+> 状态：`Accepted`
+>
+> 本文只回答“为什么存在、解决什么、最终拥有哪类资产”。
+
+## 1. 一句话定义
+
+Frontend Project Context 是位于**设计、代码与 AI 编程工具之间**的模型无关项目上下文与规范中间层。
+
+它把分散的项目知识变成一份有来源、有人批准的 `Project Contract`，再为不同 Coding Agent 编译一致且与当前目录相关的上下文。
+
+## 2. 用户与问题
+
+用户是使用 Codex、Claude Code、Kiro、Gemini、Cursor、Copilot 或其他成熟 Coding Agent 的前端开发者和团队。
+
+真实项目的知识通常分散在：
+
+- 产品和设计文档；
+- Figma 链接、设计 token、组件库和交互说明；
+- README、架构文档和目录约定；
+- `package.json`、TypeScript、lint、format、build 和 test 配置；
+- 已有代码模式和参考组件；
+- `AGENTS.md`、`CLAUDE.md`、`.kiro/steering/` 等工具专用文件；
+- 开发者临时补充给 AI 的聊天说明。
+
+由此产生四个稳定问题：
+
+1. 每次任务都要重新解释项目。
+2. 不同 AI 工具拿到的规则不一致。
+3. 代码和设计变化后，旧规则继续误导模型。
+4. AI 从代码中观察到的偶然模式容易被误当成团队规范。
+
+## 3. 产品承诺
+
+```text
+给定一个已有前端项目，
+产品能够发现有来源的项目事实，
+由人确认长期规则，
+为任意成熟 Coding Agent 生成一致的作用域上下文，
+并在事实、合同或投影变化时报告漂移。
+```
+
+产品不承诺模型一定写出正确代码；它承诺模型接收到的项目事实和原则来自同一份可审查真源。
+
+## 4. 产品内核
+
+### 4.1 Discover — 发现
+
+从项目自身读取可验证事实，例如技术栈、脚本、目录、设计 token、组件入口、代码模式和现有 AI 规则。
+
+发现结果只是 `proposal`，必须保留来源，不能自动成为长期规范。
+
+### 4.2 Govern — 治理
+
+将内容明确区分为：
+
+- `fact`：可以从当前项目直接观察或验证的事实；
+- `policy`：由负责人批准、要求未来修改遵守的规范；
+- `reference`：推荐模仿的真实文件、组件或文档；
+- `validation-description`：项目已有的验证入口及其适用范围。
+
+批准、废弃和显式覆盖属于人的责任。AI 和扫描器只能提出建议。
+
+### 4.3 Compile — 编译
+
+根据目标目录和显式任务范围，选择适用的合同项，形成最小 `Context Bundle`。编译是确定性的：同一合同、同一作用域和同一版本必须得到相同结果。
+
+### 4.4 Project — 投影
+
+把同一 Context Bundle 表达为通用 Markdown、`AGENTS.md` 或现成分发工具能消费的输入。生成文件只是投影，不得反向成为第二份项目真源。
+
+### 4.5 Check — 检查
+
+检测：
+
+- 被引用来源是否改变或消失；
+- 同一作用域是否存在互相冲突的规则；
+- 生成投影是否落后于当前合同；
+- 未经批准的 proposal 是否被错误发布；
+- 目录级覆盖是否越过声明范围。
+
+检查只报告问题，不自动改写合同。
+
+## 5. 长期产品资产
+
+产品只长期拥有三类资产：
+
+1. `Project Contract`：人批准的模型无关项目合同。
+2. `Source Index`：合同项与真实设计、配置、文档和代码来源的关系及指纹。
+3. `Projection Manifest`：哪些生成文件由产品管理，以及它们对应的合同版本。
+
+任务描述、模型会话、Provider 授权、模型推理、代码 candidate 和 Git 交付状态不是产品长期资产。
+
+## 6. 设计、代码与 AI 的连接
+
+```text
+设计侧
+产品原则 / Design Token / 组件与交互参考
+             │
+             ▼
+       Project Contract
+             ▲
+             │
+代码侧
+技术栈 / 架构 / 目录 / 代码模式 / 验证入口
+             │
+             ▼
+       Context Compiler
+             │
+             ▼
+AI 侧
+AGENTS.md / Ruler / Kiro / Context Bundle
+```
+
+合同不复制全部设计和代码内容，而是保存规范结论、作用域和可追溯来源。
+
+## 7. 产品成功标准
+
+产品只有在以下结果成立时才有独立价值：
+
+1. 开发者维护一份合同即可服务至少两个独立 Coding Agent。
+2. Agent 获得的规则能按目录正确收窄，不需要把整个项目知识塞入每次任务。
+3. 每条重要规则可以回答“谁批准、来自哪里、适用于哪里”。
+4. 项目配置或参考代码变化后，工具能指出需要复核的合同项。
+5. 相比只手写 `AGENTS.md` 或只使用 Ruler，确实减少了事实收集、冲突检查或上下文准备成本。
+
+第 5 条如果不能证明，产品应降级为 Ruler 配置、仓库模板或 Coding Agent Skill，而不是维持独立程序。
+
+## 8. 非目标
+
+产品不建设：
+
+- 模型、Provider、Agent loop、会话或工具执行器；
+- 自动代码生成、任务运行器或验证执行器；
+- Git 分支、提交、合并、推送、PR 和部署；
+- 自动修复、自动重试或候选版本生命周期；
+- Spec Kit/OpenSpec 的 feature spec 流程；
+- Ruler/Rulesync 的完整 Agent 格式适配矩阵；
+- Kiro IDE、CLI、Hooks、Permissions 或 Agent Harness；
+- 企业知识图谱、向量数据库或通用项目管理平台。

package/docs/02-MARKET-BOUNDARY.md

@@ -0,0 +1,88 @@
+# 02 — 市场与自研边界
+
+> 权威说明：本文记录市场边界的形成过程；当前唯一规范真源是 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)。
+
+> 状态：`Accepted`
+>
+> 规则：现成工具已经稳定解决的能力优先采用；只有明确差异允许进入自研程序。
+
+## 1. 现实产品对照
+
+| 产品 | 已解决的核心问题 | 本项目决定 |
+| --- | --- | --- |
+| [Kiro Steering](https://kiro.dev/docs/steering/) | 用项目级 Markdown 保存 product、tech、structure 和自定义规则，并在 Kiro 各入口复用 | 作为完整体验参照和可选消费者；不绑定 Kiro Runtime |
+| [Ruler](https://github.com/intellectronica/ruler) | 以 `.ruler/` 作为规则真源，向大量 Coding Agent 分发规则、MCP、Skills 和 Subagents | 直接复用其分发能力；不重新建设 Agent 适配矩阵 |
+| [Rulesync](https://github.com/dyoshikawa/rulesync) | 在多种 AI Coding Tool 格式之间生成和导入 rules、commands、skills、subagents 等 | 作为替代分发实现和兼容性参照 |
+| [GitHub Spec Kit](https://github.com/github/spec-kit) | Constitution、Specification、Plan、Tasks、Analyze、Implement 等规格驱动流程 | 作为下游 feature lifecycle；Project Contract 可以为其提供项目原则 |
+| [OpenSpec](https://openspec.dev/) | 轻量、仓库内的规格驱动开发和多 AI 工具接入 | 作为可选下游；不复制 change/spec/apply 流程 |
+| 成熟 Coding Agent | 模型调用、Agent loop、会话、工具、sandbox、approval 和业务代码修改 | 完全复用；本产品不调用或包装 Runtime |
+
+## 2. 已被市场覆盖、禁止重复建设
+
+### 2.1 多工具规则格式转换
+
+Ruler 和 Rulesync 已经证明“一份指令分发给多个 Agent”是独立成熟能力。维护几十个工具的文件位置、格式和版本变化不是本产品的差异。
+
+v1 只需：
+
+- 输出通用、稳定的 Markdown Context Bundle；
+- 能生成一个明确受管的 `AGENTS.md` 投影；
+- 能输出 Ruler 可接收的 Markdown 源文件；
+- 将更多工具适配交给 Ruler/Rulesync。
+
+### 2.2 规格驱动任务流程
+
+Spec Kit 和 OpenSpec 已经拥有 specification、plan、tasks、implementation 等语义。Project Contract 只提供稳定的项目原则和事实，不再定义另一套 Task、Run、Candidate、Decision 或 Delivery。
+
+### 2.3 Agent 执行环境
+
+Kiro、Codex、Claude Code 等已经拥有完整 Runtime。项目不再固定 Provider 参数、解析事件、创建隔离 candidate 或接管验证/修复循环。
+
+## 3. 现成工具仍留下的缺口
+
+### 3.1 Ruler / Rulesync 的上游缺口
+
+它们擅长分发已经写好的规则，但不负责判断：
+
+- 某条规则是否来自真实配置、设计或代码；
+- 观察到的代码模式是不是团队批准的规范；
+- 来源变化后规则是否仍然成立；
+- 多个来源冲突时谁有权决定；
+- 当前目录到底需要哪些最小上下文。
+
+### 3.2 Kiro 的可移植性缺口
+
+Kiro 可以生成和使用 Steering，但其最佳体验属于 Kiro 产品边界。本项目需要合同在不启动 Kiro、也不选择具体模型时仍然可审查、可编译、可验证。
+
+### 3.3 Spec Kit / OpenSpec 的项目真源缺口
+
+它们围绕一次 feature/change 的意图与实施组织材料，不替代长期项目事实、设计系统、目录约束和参考代码的来源治理。
+
+## 4. 允许自研的唯一差异
+
+```text
+Project Discovery
++ Provenance
++ Human Governance
++ Scope-aware Context Compilation
++ Source / Contract / Projection Drift Check
+```
+
+如果某项新需求不属于这五部分，应先交给现成工具，不得扩展产品核心。
+
+## 5. 采用与集成决定
+
+1. 合同格式保持模型和工具无关。
+2. v1 自带的投影能力只覆盖通用 Markdown、受管 `AGENTS.md` 和 Ruler 源文件。
+3. Kiro、Claude、Gemini、Cursor 等专用格式通过 Ruler/Rulesync 获得，不在本项目逐一维护。
+4. Spec Kit/OpenSpec 可以读取生成的项目原则，但本项目不触发其命令或管理其任务状态。
+5. 不自动安装、下载或运行任何第三方工具；集成只生成兼容输出，由用户决定是否使用。
+
+## 6. Build / Buy 停止条件
+
+实现前和 Beta 后都执行同一判断：
+
+- 如果 Ruler 加一份手工 `AGENTS.md` 已经达到同样效果，停止独立产品实现；
+- 如果 Kiro 自动生成 Steering 已满足目标团队且不需要跨工具治理，直接采用 Kiro；
+- 如果问题只是 feature specification，直接采用 Spec Kit 或 OpenSpec；
+- 只有真实项目证明“来源治理与漂移检查”提供额外净价值时，才保留独立程序。

package/docs/03-FINAL-SOLUTION.md

@@ -0,0 +1,203 @@
+# 03 — 最终产品方案
+
+> 权威说明：本文是历史冻结方案；当前唯一规范真源是 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)。
+
+> 状态：`Accepted and frozen`
+>
+> 本文冻结产品语义。后续程序设计只能实现本文，不能通过增加运行流程改写它。
+
+## 1. 最终方案摘要
+
+产品最终形态是一个本地、模型无关的 **Project Contract Compiler**：
+
+```text
+Project Sources
+  ├─ Design docs / tokens / component references
+  ├─ README / architecture / team decisions
+  ├─ package / TypeScript / lint / test configuration
+  ├─ code and directory references
+  └─ existing Agent instructions
+          │
+          ▼
+Read-only Discovery
+          │ proposals + provenance
+          ▼
+Human Review
+          │ approved items
+          ▼
+Project Contract  ← 唯一长期规范真源
+          │
+          ├─ Scope Compiler ─→ Context Bundle
+          ├─ Projection ─────→ AGENTS.md / Ruler source
+          └─ Drift Checker ──→ Findings
+
+现有 Coding Agent 消费输出并完成开发任务；不经过本产品 Runtime。
+```
+
+## 2. 核心对象
+
+### 2.1 Source Evidence
+
+一个可重新定位的项目来源，例如：
+
+- 某个配置字段；
+- 某份设计或架构文档；
+- 某个 token 文件；
+- 某个目录或 scope 目标路径的存在与类型；
+- 某个参考组件或测试；
+- 一次明确记录的人工决策。
+
+来源至少记录 `type`、位置和内容指纹。来源不是规范，只是支持合同项的证据。
+
+### 2.2 Contract Item
+
+合同最小单元。每项必须具有：
+
+```text
+id
+kind: fact | policy | reference | validation-description
+statement
+scope
+status: proposed | approved | deprecated
+sources[]
+owner / approval
+optional verification
+```
+
+- `fact` 描述当前真实状态；来源失效后需要复核。
+- `policy` 描述未来工作必须遵守的要求；只能由人批准。
+- `reference` 指向应当优先模仿的真实实现，不复制完整代码。
+- `validation-description` 说明项目已有验证入口，但产品不执行它。
+
+### 2.3 Project Contract
+
+所有 `approved` 合同项的版本化集合，是唯一规范真源。
+
+它不保存模型 prompt、聊天记录、Provider 授权、任务执行状态或业务代码副本。
+
+### 2.4 Context Bundle
+
+由合同、目标路径和显式任务约束确定性生成的短生命周期 Markdown：
+
+- 只包含适用于目标路径的 approved 项；
+- 保留规则 ID 和来源引用；
+- 任务约束可以进一步收窄目标，但不能覆盖长期 policy；
+- 不写回 Project Contract。
+
+它既可以被复制到聊天，也可以由 Coding Agent 原生规则文件引用。
+
+### 2.5 Projection
+
+面向消费者的生成文件。v1 只承诺：
+
+- 通用 Markdown Context Bundle；
+- 受管的 `AGENTS.md` 投影；
+- Ruler 可消费的 Markdown 源文件。
+
+Projection 带生成标记和合同摘要。用户手写或第三方拥有的文件不得被接管。
+
+### 2.6 Drift Finding
+
+当来源、合同或投影不一致时产生的可审查结果：
+
+- `source-changed`；
+- `source-missing`；
+- `contract-conflict`；
+- `projection-stale`；
+- `unapproved-content`；
+- `scope-override-invalid`。
+
+Finding 不自动修改合同，也不启动 AI 修复。
+
+## 3. 作用域与冲突语义
+
+1. 根作用域合同项适用于整个项目。
+2. 子目录合同项只有在明确声明 scope 后才生效。
+3. 子作用域可以对允许覆盖的上层项进行显式替换；替换必须引用被覆盖 item ID。
+4. 两条 approved policy 在同一有效作用域冲突时，编译失败并报告，不按文件顺序静默决定。
+5. task constraint 只能收窄当前 bundle，不得废弃或放宽 approved policy。
+6. generated projection 永远没有高于 Project Contract 的优先级。
+
+## 4. 生命周期
+
+### 4.1 首次接入
+
+```text
+只读扫描项目
+→ 输出事实与冲突提案
+→ 开发者审阅、修改和批准
+→ 建立 Project Contract
+→ 生成第一份投影
+```
+
+扫描器不能直接生成 `approved policy`。
+
+### 4.2 日常使用
+
+```text
+给定目标路径和可选任务说明
+→ 生成 Context Bundle
+→ 交给任意 Coding Agent
+→ Agent 在自己的 Runtime 中工作
+```
+
+本产品到“生成上下文”结束，不观察或管理 Agent 后续代码执行。
+
+### 4.3 项目变化
+
+```text
+重新检查来源
+→ 报告 drift
+→ 人工判断合同是否仍成立
+→ 批准合同变更
+→ 重新生成投影
+```
+
+没有自动学习和自动修正规则。
+
+## 5. v1 范围
+
+v1 只支持已有本地前端项目，并完成：
+
+1. 从文档、JSON 配置、常见前端配置文件、目录和现有 Agent 规则中只读发现事实。
+2. 允许用户建立和审阅结构化 Project Contract。
+3. 按路径 scope 生成 Context Bundle。
+4. 生成受管 `AGENTS.md` 和 Ruler 源投影。
+5. 检查来源指纹、合同冲突和投影漂移。
+
+v1 不直接连接 Figma API。设计链接、token 文件、组件文档和人工批准的设计原则可以作为来源；真实 Figma 读取只有在后续证明需要时才通过现成连接器扩展。
+
+## 6. 产品安全边界
+
+- 默认操作只读。
+- 写操作只涉及合同目录和明确受管投影。
+- 覆盖文件前必须验证 ownership marker 和上一版本指纹。
+- 不执行 shell、项目脚本、测试或构建。
+- 不执行任何 Git 写操作，也不要求知道当前分支。
+- 不访问网络、不安装依赖、不调用 Provider。
+- 失败只留下报告，不自动重试、回滚或修复。
+
+## 7. 为什么这不是另一个 Ruler
+
+Ruler 从“规则已经写好”开始；本产品从“项目事实散落且可能冲突”开始。
+
+```text
+本产品：来源 → 审阅 → Project Contract → scoped context
+Ruler： 已有规则 → 多 Agent 文件分发
+```
+
+二者可以串联。本产品不以支持 Agent 数量竞争，而以来源可追溯、人工治理和漂移发现证明价值。
+
+## 8. 最终完成定义
+
+最终产品成立必须同时满足：
+
+- 项目合同不依赖任何具体模型或 Runtime；
+- 同一合同能服务至少两个独立 Coding Agent；
+- 规则范围、来源和批准状态可以被程序检查；
+- 配置或参考来源变化能触发明确复核；
+- 不复制现成多 Agent 分发和 Spec 流程；
+- 不接管真实开发、Git 和交付；
+- 相比手工规则文件存在可测量的净收益。
+
+不满足最后一项时，最终方案主动降级为一份规范模板和 Ruler/Coding Agent Skill。