LTJT 项目文件治理规则

本文件约束所有后续维护会话。用户指令优先；在没有新的明确指令时，必须遵守以下位置、协作、同步和归档规则。

开始工作前

运行 git status --short，保留所有既有未提交改动；禁止 git reset --hard、git clean 或批量回退。
运行 git branch --show-current、git rev-parse --show-toplevel 和 git worktree list --porcelain，按 .project-docs/05-agent-entry/concurrent-task-gate.md 完成仓库内自包含的 worktree 安全检查。
按 .project-docs/05-agent-entry/read-before-planning.md 的顺序加载当前任务和 canonical 项目记忆；Feature 与 Integration 写入边界以 .project-docs/90-maintenance/doc-update-policy.md 为准。
通过 agent设计规范/business-adaptation-registry.md 定位业务，再读取对应业务页、Skill、Schema、mapping 和实现代码。
archive/ 只供追溯，不能反向覆盖当前业务规则；若历史文件与活动源码冲突，以活动源码及当前契约为准。

仓库不依赖外部项目文档 Skill。已删除的 maintain-project-docs、task_context.py 或其专属检查脚本不得作为开始、编辑、验证或完成任务的前置条件。

并发与子智能体

原则上不创建子智能体；确有必要时必须先取得用户明确同意。
一个 worktree 同一时间只承载一个活动任务的编辑；不得在已被其他任务占用或归属不明的 dirty worktree 中继续。
.project-docs/ 的任务记录用于持久上下文和交接，不充当进程锁或外部所有权注册表；并发判断以当前 Git worktree、branch、status 和可见任务范围为准。
未知改动不得自动 stash、reset、移动、删除或认领；若与当前目标重叠且无法安全绕开，必须先询问用户。

根目录边界

允许的长期文件和目录只有：

项目入口与约束：README.md、AGENTS.md；
项目记忆：.project-docs/；
构建与部署配置：package.json、锁文件、TypeScript、Docker、Compose、Git/Docker ignore 和环境示例；
下表登记的活动源码、发布、报告、隔离与历史目录；
本地秘密配置 .env 可以存在，但必须被 Git 忽略，不得读取、复制、归档或输出其内容。

旧根目录 task_plan.md、findings.md、progress.md 已退役并冻结在 archive/project-history/2026-08-28/；不得恢复为活动入口或与 .project-docs/ 并行维护。

禁止在根目录新增临时说明、交接副本、测试输出、ZIP、DOCX、截图、日志、浏览器状态或一次性脚本。新增内容必须进入下表规定的位置。

唯一目录职责

位置	唯一职责	禁止内容
`.project-docs/`	任务作用域记录、canonical 项目记忆、证据索引、反思、承诺和文档维护状态	运行日志、秘密、业务附件、把任务记录当作并发锁的共享进度
`agent设计规范/`	Agent Prompt、五个 Skill、业务模板、业务入口与稳定测试夹具的可编辑源	发布包、运行日志、历史版本副本
`schemas/`	当前解析态、执行态和 ERP 表单 Schema	历史 Schema、运行结果
`mappings/`	当前 ERP 字段与生命周期 mapping	探针输出、旧版本副本
`chrome-extension/`	当前 Chrome ERP 适配器源码	打包 ZIP、浏览器 profile
`control-plane/`	当前 TypeScript 控制面源码、迁移和测试	编译后的 JavaScript
`LianSyn-platform/`	当前平台页面与 Agent 解析适配器源码	本地任务输出、发布包
`tools/`	可复用构建器、测试、只读诊断与受控写入工具	工具运行结果、临时 JSON
`infra/`	当前部署、备份、恢复和网关配置	本地秘密、数据库备份文件
`samples/`	脱敏且稳定的测试输入样例	真实客户资料、运行输出
`.build/`	TypeScript 可重建编译输出；Git 忽略	人工维护文件、发布物
`dist/`	当前版本化交付物及机器可读发布清单	编译输出、无版本别名、松散 Prompt/示例副本、旧版本
`reports/`	当前会话临时验证输出；除 README 外应为空	长期证据、业务规则
`quarantine/`	无法安全解析的外部输入隔离边界	当前源码或已信任 fixture
`archive/`	日期化、只读、可恢复的历史实现、证据、规划和发布物	当前入口或需要运行时读取的文件

项目记忆维护

.project-docs/30-worklog/tasks/<task_id>.md 是任务局部范围、约束、结果、验证、后续项和 Promotion Candidates 的唯一记录。
Feature 模式只写当前 task ID 所属记录和允许的 task-prefixed supporting records；不得更新 current-state.md、共享索引、accepted ADR、canonical 架构、业务规则或共享聚合。
Integration 模式必须使用无冲突的独立 worktree，或在用户明确要求直接更新当前分支时确认既有改动均已知且不重叠，才能把已接受事实写入 canonical 项目记忆；冲突的产品行为、架构方向或真相源必须由用户决定。
current-state.md 是上次集成快照，不代表其他并行任务的实时状态；其他任务只通过其 task record 做只读范围评估。
仓库变更任务完成前必须更新当前任务记录并执行本仓库已有、与改动相关的验证；不要求外部完成命令或状态注册。
历史 Planning with Files 只供追溯；不得从归档复制回活动项目记忆。

单一源与同步矩阵

Prompt 只编辑 agent设计规范/agent-prompt.md；不得在 dist/、桌面或其他目录维护文本副本。
运营输入 Markdown 只编辑 agent设计规范/templates/business-input-templates.md；修改后使用 tools/build_business_instruction_docx.py 同步重建当前 DOCX，并按 Documents skill 渲染检查全部页面。macOS 的 bundled LibreOffice 若未加载中文字体，先通过 workspace dependencies 定位并设置其 dependencies/native/poppler/poppler/etc/fonts/fonts.conf 为 FONTCONFIG_FILE，不得接受方框字渲染。
Skill 只编辑 agent设计规范/skills/<skill>/；发布 .skill 必须由当前源重新打包并逐文件核对。
Chrome 插件只编辑 chrome-extension/ltjt-order-assistant/；任何代码改动都必须递增扩展版本，同步平台最低版本、mapping、测试、版本化 ZIP 和 dist/release-manifest.json。
控制面只编辑 TypeScript 源；.build/ 由 node --run build（或等价包管理器命令）生成，不得手改。
当前交付物及哈希只由 dist/release-manifest.json 定义；README 只链接清单，不重复维护哈希。
真实验证证据进入 archive/evidence/<日期>/；活动 release gate 只保存当前结论并链接不可变证据。

历史与生成物处理

旧版本、旧交接、旧发布说明和退役文档按日期移动到相应 archive/ 分类，并更新该日期 README。
可重建编译产物、完全相同的别名包、.DS_Store、日志和临时输出不进入历史上下文；确认无唯一信息后清理。
不把桌面作为当前源或发布源。桌面只允许用户主动需要的临时交付副本，项目内 dist/ 才是当前交付位置。
移动前必须做引用扫描；移动后必须修复活动链接。归档内部允许保留原始历史措辞，但归档 README 必须声明其非当前规则。

验证

项目文档或仓库文件调整后，至少运行仓库内已有的以下检查：

node --run check:repo
node --run check
node --run test:control-plane
node --run test:legacy
node --run build

涉及 Skill 时执行官方 Skill 校验和包/源码逐文件比对；涉及 DOCX 时按 Documents skill 完成 render → 全页 PNG 检查；涉及插件时校验版本化 ZIP 与源码逐文件一致。真实 ERP 写入、部署、重启和外部发送仍需用户另行明确授权。

7.9 KiB Raw Permalink Blame History Unescape Escape