AGENTS.md

操作红线

• 未经用户对具体执行逐次明确授权，禁止在宿主机或容器中运行 ruby、gem、bundle、bundler 或 jekyll。禁止项包括安装依赖、拉取 Ruby 镜像、构建站点和启动本地服务。仓库工具、验证要求或部署请求均不构成授权。

仓库状态协议（repo-state）

• 文档分层：frontmatter role: state（现状唯一权威，原地重写，历史在 git）/ process（docs/sessions/ 等，带日期 append-only，不维护）/ reference（docs/ref/、archive，只读）。任何思想只有一个现状住址；其他文档只许引用，不许复述。整目录归层用目录内 .role 文件（一行，process 或 reference）。
• state 文档设「未决」「出界」两个常设区：能精确表述但没答案的问题住未决（拍板后入台账并从未决删除）；有意识划出 scope 的事住出界，一行为什么 + 引对应的”不做”决策。开放问题不长住 session log。空区写 - 无。
• 体检报告（不拦提交）：python3 scripts/docctl.py stale（covers/watches 比文档新 = STALE；staleness: manual 报 MANUAL）与 audit（覆盖缺口 / 悬空路径引用 / 未决泄漏 / 可变行号锚 / sessions 疑似决策候选）。frontmatter 可选 watches（只报陈旧不拦提交）/ mentions（仅检索与审计）/ aliases（概念别名）。
• 开工先组装上下文：python3 scripts/docctl.py context <任务相关路径或关键词>，按输出的清单读；process 记录是历史快照，不当现状读。
• 原始证据层（transcript 索引，全局引擎单份，仓库内统一经 python3 scripts/docctl.py engine <子命令> 使用，不写全局路径）：context 末尾附”相关历史会话”栏；文档找不到出处、前后矛盾、对历史决策困惑时先 python3 scripts/docctl.py recall <关键词> 查原始会话，再问用户；开放探查默认用安全 JSON DSL python3 scripts/docctl.py engine query <query.json>（search 必须显式 project_path，全项目必须 ack），可信本地 Python 才用 python3 scripts/docctl.py engine query-python --trusted <script.py>（带超时、输出上限和审计日志），全文钻取用 engine get-message <uuid>。schema 7 从当前 raw bytes 重构 canonical projection 后才发出内容；session 聚合另验完整 source set，同 ID 的全部 main-message projections 必须属于请求项目。主 SQLite 只读或锁定时，查询为请求项目的活动 session 建内存 overlay，overlay 优先并按 message UUID 与 immutable base 去重；结果标注来源和 freshness，overlay 不可用时明确 base-only。默认读面不返回 thinking，admin/private 敏感读取先写审计，审计失败就拒绝。schema 不匹配只允许显式 engine index clean rebuild。transcript 是历史证据，不是现状权威。
• committed attestation 与事务写入：decision --from-transcript 会先验证本机 raw user message，再用一个 fsynced journal operation 原子 roll-forward ledger、docs/evidence/seals/YYYY/*.jsonl seal 与 event v2；所有 event writer 共享 flock、连续 sequence 和 repo/operation UUID。硬退出后下次 writer 自动恢复，也可运行 python3 scripts/docctl.py recover；authority revision 冲突、坏 journal、坏 identity、坏 ledger/event/seal chain 和非终止 JSONL 都 fail closed。raw transcript 或 sqlite 不进 git。python3 scripts/docctl.py check --ci --base <ref> fail-closed：没有本机 fresh 原文且没有结构有效、repo-bound、已提交的 non-local_only attestation 时，active transcript 锚会报 ERROR，并检查 events/seals 历史 byte-prefix append-only。seal 是提交者声明；无 raw transcript 的 CI 不能独立认证消息曾经发生。协议不提供数字签名。
• 迁移与体检：新 clone 先 python3 scripts/docctl.py init；老仓库升级 0.9 跑 python3 scripts/docctl.py migrate 生成 .repo-state/identity.json、events 和 evidence 目录；python3 scripts/docctl.py doctor 检查 hook、seal chain、engine source inventory、slug 碰撞和隐私边界。
• session 收尾先对账再存档：python3 scripts/docctl.py session-audit 以只读方式列出疑似未入台账的决策、改了文件但没跟着动的 state 文档、缺失的 session 存档（报告级，不拦截）；只有显式 --record-event 才追加 session_audited event。对账后按 skill 存档格式写 docs/sessions/ 记录。
• 用户拍板（”就这么定 / 裁定 / 确认采用”）的当下：python3 scripts/docctl.py decision --title ... --scope ... --quote "原话逐字" --context "语境" --impact <落点> --from-transcript，同步更新落点 state 文档引用该编号，并把生成条目展示给用户过目。不许攒到 session 结尾。--from-transcript 把原话锚到会话消息（尾注 transcript:<uuid>，check 逐字验证，找不到原话会明确报错）；引擎不可用时去掉该开关退回（用户，日期）尾注。用户没拍板但一件事同时满足难以逆转、缺上下文会困惑、真实取舍三条，主动建议入账。
• 重写 state 文档：先跑 python3 scripts/docctl.py state-diff <文档>，diff 与锚点删除报告（含 frontmatter 的 covers/watches/mentions/scope）一起给用户确认；正文被改动的 state 文档 updated 须递增或为当天（hook 强制，不得回退）。证据锚用逐字引文或不可变对象（sessions、<rev>:<path>），不用可变行号。新建文档是例外，须先说明为什么现有文档装不下。
• 外发 web 模型（GPT-5.6 Sol Pro 等）：python3 scripts/docctl.py pack <文件/目录>... --topic <主题> 打包批次并打印统一提示词供复制；payload 里必须有 TASK.md 任务书。pack 先冻结输入到私有 staging，扫描冻结字节，按 included 文件 SHA-256 生成 MANIFEST，再核对 payload 与 ZIP 后一次性发布。输入内 symlink、realpath escape、raw transcript shape、hidden thinking、local_only seal 与 secret 是不可豁免的确凿违规；无法扫描类只可按规范化路径组件 --ack PREFIX:REASON 并记入 MANIFEST。默认排除 .git、.env*、SQLite/transcript/cache、exchange/、artifacts/。返回稿归档进过程层后蒸馏进 state/台账。复杂难题与方向性问题也该主动建议外发（GPT-5.6 Sol Pro 是最强模式，只是拿不到本地文件），不只批量任务。
• commit 被 commit-msg hook 拦下：按报错修复（更新 state 文档 / 修台账格式）。豁免必须带理由：[doc-ack: 理由] 管 state/doc 同步例外；[ledger-fix: 理由] 只管台账格式更正，不得删除 D 编号、block、标题或必填字段；[session-fix: 理由] 只管 process 记录等内容改名；[state-drop: 理由] 管 state 锚点删除，但 active 决策引用不可删；[decision-ack: 理由] 压疑似决策 WARN。不可豁免：既有决策消失、自我/循环 supersede、status 回改、session 内容删改、event/seal 非 byte-prefix EOF 追加、stale/tombstoned/parser-skipped transcript 作严格 proof。禁止 --no-verify。
• 新 clone 先跑一次 python3 scripts/docctl.py init（幂等）。