本项目默认且明确规定：不要使用工作树（git worktree）作为日常开发方式。
后续所有常规开发、联调、验证、服务启动、数据检查，默认都在仓库根目录进行：
- 仓库根目录：
/home/wgw/CodexProject/CodeFactoryV2 - 运行数据根目录：
.data/ - 前端、后端、本地知识产物，统一以当前根目录工作区为准
本项目包含大量本地运行态文件与生成产物，例如：
.data/knowledge_output/.data/source_archives/- 前后端本地启动环境
- 验证过程中的临时产物
这些内容很容易在不同工作树之间分叉，导致出现以下问题：
- 代码在一个工作区，服务却从另一个工作区启动
- 页面展示的知识数量与预期不一致
- 新生成的知识库、抽取结果、审核结果没有同步到当前验证环境
- 用户看到的内容与开发者以为的内容不是同一套
因此，本项目为了降低运行态分叉风险，明确采用单工作区优先策略。
- 默认只在仓库根目录工作，不新建
.worktrees/* - 默认直接在当前主工作区完成开发、测试、启动与验证
- 若历史文档、旧计划、旧命令中出现
.worktrees/...路径，一律视为历史遗留，不作为当前执行依据 - 本项目中的
.data/目录内容，默认视为当前主工作区上下文的一部分，不应拆分到多个工作树分别维护
只有在以下极少数情况下，才允许重新讨论是否启用工作树：
- 用户明确要求做高风险隔离实验
- 需要并行维护两个互相独立、且会长期并存的开发现场
- 当前任务若在同一工作区执行，明确会破坏正在验收的稳定版本
- 用户明确批准采用“主线持续验收 + 次线并行开发”的双现场模式，例如
P1知识库优化与P4工具仓库并行推进
即使出现上述情况，也不能默认直接启用，必须先明确说明原因，再单独确认。
从现在开始，CodeFactoryV2 项目采用以下统一规则：
- 默认不用工作树
- 默认在仓库根目录开发和启动服务
- 默认以根目录
.data/作为唯一有效的本地运行数据上下文 - 只有在用户明确批准的并行多流开发场景下，才允许受控启用工作树
这条规则优先级高于历史计划文档中的工作树命令示例。
本节只适用于“用户明确批准的并行开发”场景，不改变“默认不用工作树”的总原则。
当前项目若进入 P1 与 P4 并行推进，统一采用如下规则：
- 主工作区：继续承担当前主线、稳定验收和对外演示职责
- 工作树：承担次线并行开发，不直接替代主工作区的验收职责 当前推荐分工：
- 主工作区负责
P1知识库链路持续优化与用户验收 - 工作树负责
P4工具仓库/工具中台并行开发
- 主工作区继续使用当前主分支现场，作为稳定基线
- 并行工作树必须绑定独立功能分支，例如
feat/p4-tool-hub - 工作树目录命名必须能直接反映用途，例如
.worktrees/p4-tool-hub - 禁止在同一分支上同时维护主工作区与并行工作树
- 主工作区继续使用当前稳定端口
- 工作树必须使用不同端口，避免用户混淆与进程互相覆盖 推荐约定：
- 主工作区后端
8020，前端5173 P4工作树后端8010，前端5180- 若后续再开新的并行流，继续按固定偏移量递增，不允许随机占用端口
- 主工作区的
.data/仍然是当前项目唯一权威的本地验收数据上下文 - 工作树不得把自身
.data/误认为主线验收结果 - 工作树允许存在本地
.data/，但只能视为临时验证数据，不得覆盖主工作区运行态 P4若需要消费P1的知识结果，只允许采用以下两种方式：- 方式一：调用主工作区已启动后端提供的只读 API
- 方式二：使用主工作区导出的冻结知识快照或契约样例
- 禁止
P4直接依赖主工作区未发布的中间 JSON、临时脚本输出、治理工作态细节或手工修改中的本地文件
P4 与 P1 的关系定义为“弱耦合并行”，不是“完全独立”。
P4可以并行启动P4最终仍要消费P1的标准知识出口- 因此两条线之间只允许通过版本化契约耦合，不允许通过内部实现耦合
当前建议冻结的 P1 -> P4 消费面如下：
- 已发布知识摘要接口
- 实体列表接口
- 事件列表接口
- 流程列表接口
- 单项详情接口
- 图谱查询接口
- 搜索接口
- 版本化知识快照 JSON
只要这些输入契约不变，P1 内部继续调整解析器、抽取器、治理方式、存储方式，都不应阻塞 P4 并行开发。
并行期间，P4 工作树应尽量避免修改以下主线高冲突区域：
- 当前知识图谱页
- 当前知识库管理页
- 主导航与首页信息架构
- 运行中的知识库验收数据
- 通用依赖文件，如
package.json、pnpm-lock.yaml、pyproject.toml、uv.lock
若确需修改上述区域，必须满足以下条件：
- 先说明修改原因
- 明确是否会影响主工作区验收
- 优先延后到集成阶段统一处理
- 工作树分支只在达到阶段性里程碑后回合到主线，不做高频碎片化回合
- 回合前必须先确认
P1 -> P4契约仍兼容 - 回合前必须在工作树内完成独立验证，不允许把“未验证状态”带回主线
- 若主线在并行期间发生契约升级，必须先在工作树中完成兼容修订，再发起回合
针对当前 CodeFactoryV2，推荐采用以下并行策略：
- 主工作区：继续作为
P1验收与知识链路优化现场 - 新工作树：专门承载
P4工具仓库/工具中台开发 P4首批工作只做工具描述模型、工具注册/查询、工具分类标签、工具匹配规则、工具验证页- 暂不在
P4中直接接入主线知识图谱页面或治理工作台 - 等
P4形成稳定最小闭环后，再通过版本化契约接入主线
“知识库正式抽取/重建”与“文档预览、调试、单文件排查”不是同一条链路。
从现在开始，正式知识库抽取/重建必须满足以下规则：
- 必须使用
Docling完成正式文档解析 - 必须使用结构化大模型完成正式知识抽取
- 不允许在正式抽取链路中静默降级到
PyMuPDF、python-docx、规则-only 抽取或其他轻量 fallback - 如果
Docling未生效、结构化大模型未生效、或执行元数据缺失，正式抽取必须直接失败 - 每次正式抽取必须生成执行报告，明确记录实际解析器、实际大模型 provider/model、关系数量和失败原因
- 正式知识全集必须由“文档级正式抽取产物仓”聚合生成，不允许直接在旧
knowledge.json上做无账本补丁 - 单文档正式并入当前知识库时，必须替换该文档旧正式产物并重算全集，不允许以“只追加不移除”的方式更新
补充说明：
- 上述硬约束只作用于知识库正式抽取/重建
- 文档页预览、解析调试、开发期故障排查，可保留非正式链路，不受该硬约束直接限制
- 若某知识库尚未建立文档级正式产物仓，首次单文档正式并入应先完成一次正式产物仓初始化，再进入后续增量模式
本项目的 GitHub 规划层不是“随手建 issue 列表”，而是 WBS 树的远端投影。
从现在开始，远端 Issue + Project 必须满足以下规则：
- 新节点必须挂到真实父节点下，不能只写在 Project 字段或 issue 正文里冒充父子关系
- 必须优先使用 GitHub 原生父子 issue 关系（sub-issue），不能只做文本引用
- 禁止直接插入跳号子节点
- 例如远端当前若还没有
P1.3.1 ~ P1.3.4，就不能直接创建P1.3.5 - 必须先补齐该分支的中间层级，或先完成编号体系重排，再创建新节点
- 例如远端当前若还没有
- 本地设计编号不等于远端 issue 树已存在
- 若本地设计文档已经定义了
P1.3.1 ~ P1.3.5 - 但远端 issue 树还只有
P1.3 - 则在远端新增节点前，必须先核对并同步缺失层级
- 若本地设计文档已经定义了
- Project 只是展示层，不是父子关系事实来源
WBS Node / Parent Node / Status字段只用于投影和筛选- 真正的树结构必须以 GitHub issue parent/sub-issue 关系为准
执行要求：
- 每次新增 WBS 节点时，必须同时检查：
- 远端是否已有对应父节点
- 同层前序编号是否已经存在
- 新节点是否已挂为真实 sub-issue
- 若三者任一不满足，不允许提交该远端节点同步结果
从现在开始，前端页面中的关键结构节点必须提供稳定、可沟通的 DOM id，不能只依赖视觉位置、文案或自动生成的类名。
适用范围：
- 页面根节点
- 一级工作区容器
- 核心指标区父容器与关键指标项
- 主要操作入口，如主 Tab、主表单区、主结果区
- 评审、联调、验收时高频需要定位的可视化区块
执行规则：
id命名必须语义化，优先使用页面-模块-节点结构，例如xx-p4-workspaces- 同一页面内
id必须稳定，不因样式调整而随意改名 - 需要让用户快速指出“这一块”的父容器时，父容器本身必须有
id - 不允许把“后续可以靠截图描述位置”作为替代方案
当前并行开发阶段，XX-P4 及其后续新增前端页面默认遵守这条规则。
从现在开始，CodeFactoryV2 的研发节点必须显式绑定文档，不能只在聊天记录里口头约定。
- 每个 WBS 节点至少要有一个对应的设计文档
- 每个进入实施的叶子节点，至少要有一个对应的执行文档或实施计划
- 节点与文档的映射必须能在本地镜像文档中直接查到
- 设计过程文档可先放在
docs/superpowers/specs/ - 但用户阅读、审阅、确认与长期引用只认
DOC/CODEX_DOC/ - 允许多个节点共享一份上层设计文档，但必须在节点映射中显式写清楚
- 协议型、对象型、生命周期型、高约束节点，优先使用专属设计文档，不应长期埋在上层总规格里
- 任何已经被采纳或已作为实现依据的核心设计细节，都必须整理回
DOC/CODEX_DOC/，不能只停留在superpowers时间稿中
- 执行文档默认放在
docs/superpowers/issues/或docs/superpowers/plans/ - 叶子节点进入开发前，执行文档至少要明确：
- 工作目标
- 工作内容
- Depends On
- 成果物
- 验收方法
- 当前状态
- 如果节点还没有对应设计文档，不应直接进入编码
- 如果节点已经发现关键约束独立性不足，应先拆出专属设计文档，再继续实现
- 不允许用“代码已经写出来了，后面再补文档”替代节点契约建设
P4.2.1必须有独立的工单生命周期与协议对象设计文档P4本地 issue 树镜像需要维护节点到设计文档、执行文档的映射- 像
P3 / P4 / P5工单流这样的跨节点主干协议，不能只出现在单页说明里，必须在总设计、节点设计和 issue 树镜像里都可追溯 - 后续新增
P4.x.y节点时，若没有对应设计文档，不应直接标记为可开发
从现在开始，CodeFactoryV2 若使用 GitHub Project 作为排程与状态投影层，统一采用以下规则：
Status字段应显式提供Hum Check选项Hum Check推荐使用蓝色- 处于
已自测 / 待人工验收的节点，ProjectStatus应标记为Hum Check Done只允许用于用户已经明确验收通过的节点In Progress只用于仍在开发或仍在返修的节点- issue 正文里的
当前状态、本地正式文档里的节点状态、ProjectStatus必须在同一轮同步，不允许长期分裂 - 如果对正在使用的 Project
Status选项做了增删改，必须立即复查既有项目项状态是否被清空或漂移，再完成重新标记
从现在开始，CodeFactoryV2 的本地正式文档根明确为：
DOC/CODEX_DOC/
对应说明如下：
DOC/CODEX_DOC/：正式权威文档层docs/superpowers/：工作文档层.superpowers/brainstorm/：临时 brainstorming 产物层
执行规则：
- 新的设计草案、计划、issue mirror 可以先产生在
docs/superpowers/ - 只要方案被用户确认、被项目采纳、或需要作为后续稳定基线复用，就必须同步回
DOC/CODEX_DOC/ - 即使用户没有单独审阅
superpowers草稿，只要本轮工作已按其结论推进，也必须回写根目录正式文档 - 远端 GitHub 协作面引用正式设计或正式计划时，优先引用
DOC/CODEX_DOC/ .superpowers/brainstorm/一类临时内容不应被当作正式规范路径引用- 不能要求用户进入
docs/superpowers/按时间文件名寻找设计结论 superpowers -> CODEX_DOC的映射关系只是来源台账，不等于迁移完成- 只有核心正文已经按逻辑顺序归入
DOC/CODEX_DOC/，才算正式落版完成
后续本项目采用“superpowers 快速推演 + DOC/CODEX_DOC 正式落版”的双层协同方式，而不是让同一目录同时承担工作草案和正式规范职责。