docs: keep shared agent instructions complete and task scoped

[songoow]

The root AGENTS.md was 40,363 bytes, exceeding Codex’s default 32 KiB instruction budget. On the reviewed baseline, startup injection stopped in the middle of a paragraph and omitted five complete later workflow sections. Keep a compact shared entry point with LoopX’s purpose and core capabilities, retain the mandatory constraints, and route task-specific reads to delivery, engineering and operations documents. CLAUDE.md imports the same entry point for Claude Code compatibility.

问题与分析依据

本次修复针对仓库规则向 Agent 上下文交付不完整：文件在仓库中完整存在，但宿主自动注入的内容只有前缀。后续显式读取全文可以补足上下文，因此只检查文件存在、或者人工补读后任务正常执行，都不能证明启动加载完整。

比较基线为 110893bca，根入口实现提交为 0c5da025f。

指标	基线	本 PR
根指令行数	687	195
根指令 UTF-8 字节数	40,363	10,246
与 Codex 默认 32,768 字节预算的关系	超出 7,595 字节	根文件占用约 31.3%
原有流程正文	14 个主题集中在根文件	14 个主题的原始义务段落保留并分类迁移
原有二/三级标题锚点	26	全部保留，继续支持现有链接

按默认预算对基线取前 32,768 字节，会在第 556 行的 scope-fit 检查段落中途停止。以下章节连标题都在范围之外；此前部分 scope-fit 条款也只交付了前半段：

完全未进入默认前缀的章节	基线起始行	丢失的约束主题
Automation And Monitor Todos	598	watch 进入 canonical continuous_monitor Todo，heartbeat 保持通用发现
Projection Sink Design	609	展示消费受限、受众安全的 projection，并保存行血缘
Smoke Retention Policy	635	保留持久公共行为检查，区分临时研究/实验材料
LoopX Self-Repair	660	重复或矛盾行为应修复其规则、状态投影或回归保护
Benchmark Smoke Classification	670	active toolkit 契约与历史 runner、评分及实验材料的归档边界

这些缺失由字节位置和实际请求组装共同证明。没有据此推断已经发生错误调度、越权或隐私事件。

两种宿主需要分别判断

• **Codex：**官方文档规定自动发现的指令受 project_doc_max_bytes 约束，默认 32 KiB。该根文件单独就超过预算；本次实际 CLI 请求也复现了前缀存在而全文/末尾章节缺失。OpenAI Docs
• **Claude Code：**当前版本原生支持 AGENTS.md，但默认会在项目存在 CLAUDE.md / CLAUDE.local.md 时优先使用 Claude 指令文件。官方支持用 CLAUDE.md 中的 @AGENTS.md 导入同一来源，也提供两种文件同时加载的设置。32 KiB 不是这里可以直接套用的通用限制。Claude Code 官方加载规则

因此，本 PR 用一行显式导入建立兼容入口，避免维护两份政策正文；根文件的瘦身解决已复现的 Codex 截断，同时降低两种宿主的常驻上下文成本。

拆分依据与保留的关键约束

常驻入口先说明 LoopX 是什么

旧入口直接从开发规约开始，项目目的和功能散落在 README、roadmap 与 capability catalog 中。新入口先建立任务判断所需的项目背景：

• 长期 Goal、Todo、依赖、验收与恢复；
• heartbeat、调度、quota，以及明确的继续/等待/停止条件；
• 对等 Agent 的 claim/lease、受限 handoff、依赖产物、接收方采纳与结果返回；
• Personal Workspace 的 App、Lark、CLI 会话、配置、任务、决策和结果回读；
• 工程、研究、知识、内容与办公 capability，以及明确的 extension/provider 边界。

这些描述取自现有 README、overall roadmap 与 capability/protocol 入口。根文件继续指向这些 owner，并明确区分已交付边界和仍待验收的能力；没有新增规模、运行时或安装成熟度声明。

根约束与详细流程各自承担什么

根文件保留会影响任务选择和授权判断的约束：完整用户结果、独立干净 worktree、分支/PR/DCO、显式合并授权、公私边界、真实入口与后端验证、产品 companion journey、TypeScript 单一决策 owner、default-off/领域中立要求。对应动作发生前，必须读取并遵循根文件链接的具体流程。

详细流程 owner	承接内容	根文件如何触发
agent-delivery.md	目标与验收、worktree/PR、暂存和发布、自合并边界、release、首屏证据、产品完整性、UI、公私边界、评审发布；补充宿主加载维护说明	选任务、提交/评审/合并、发布或变更用户入口前，读取相应 section 与既有 skill
agent-engineering.md	TS/Python 归属、源码环境、预算决策、真实路径重构验证、bounded refactor、capability/extension placement、smoke 留存	修改工程契约、能力归属、预算或重构前，读取相应 checklist
agent-operations.md	monitor Todo、projection sink、自修复、benchmark 分类	监控、展示投影、自修复或 benchmark 清理/评审时读取

迁移逐段核对了原始义务、例外、证据要求、顺序、继续和停止条件：所有 14 个原始主题的正文措辞保留，变化为位置、Markdown 相对链接与分组标题。现有 26 个根标题锚点继续可达，已有 skill 链接无须改名。placement smoke 改为校验新的详细 owner，同时确认根入口仍指向该 owner。

取舍与保护

• **12 KiB / 200 行是仓库的维护预算。**12 KiB 约占默认 32 KiB 的 37.5%，为其他发现的指令留出空间；当前实际大小为 10,246 字节。它不是对 Claude Code 加载上限的声明，也不要求用户修改个人全局配置。额外的全局/目录指令或主动禁用配置仍需按实际宿主诊断。
• 详细文档使用普通 Markdown 链接。CLAUDE.md 只导入根入口；详细流程没有批量 @ 导入。Claude 官方说明导入内容仍会在启动时进入上下文，因此仅把全文拆成自动导入的文件不能减少常驻成本。官方导入说明
• **保留强制性，改变读取时机。**根文件明确要求在对应动作前读详细 section。链接可达检查提供静态保护，不能证明模型一定会正确选择、读取或遵守流程；权限与验收仍由原有 owner、hook/validator 和 review gate 承担。
• **相关重构已完成。**两种宿主共享单一政策正文，详细流程有明确归属；没有新增产品 capability、平行决策源或另一套全局设置。

验证证据

真实宿主请求组装对比

使用真实安装的 Codex 0.163.0、Claude Code 2.1.302，将请求指向隔离的本地 HTTP 模拟端点，在首个模型请求组装时检查指令正文。模拟端点不执行模型；报告只保留脱敏的存在性与副本数。

实测组合	根指令开头存在	根指令全文存在	末尾 Benchmark 分类章节存在	新根入口副本数
基线 + Codex 0.163.0	是	否	否	不适用
本 PR + Codex 0.163.0	是	是	是	1
本 PR + Claude Code 2.1.302	是	是	是	1

这证明已复现旧 Codex 加载缺口，且两个实测宿主均完整组装新版入口。未对旧版 Claude 文件做截断对比，也未把这项检查当作模型遵守、后续 workflow 选择或安装态产品验收的证明。主机请求捕获属于本次定向验证；仓库 smoke 的覆盖范围是下面的静态回归保护。

可重复运行的仓库检查

uv sync --extra test
npm ci --ignore-scripts --no-audit --no-fund
uv run --no-sync --extra test python examples/agent-instructions-smoke.py
uv run --no-sync --extra test python examples/capability-extension-placement-doc-smoke.py
uv run --no-sync --extra test python examples/docs-governance-smoke.py
uv run --no-sync --extra test loopx canary premerge --from-git-diff --git-diff-base upstream/main

--git-diff-base 应指向实际 PR 目标仓库的 main；非 fork checkout 可使用其对应的 origin/main。

新 agent-instructions-smoke.py 已接入现有 docs-governance 路径，覆盖：

• 根入口大小与行数预算；
• Claude 入口为唯一 @AGENTS.md 导入；
• 根入口直接自动导入详细文件的回归保护；
• 根入口及其 agent-detail 文档中的本地链接/锚点；
• 合法 fixture，以及超限、丢失文件、丢失锚点和“只有口头要求读取、没有显式导入”的负例。

对 0c5da025f 的标准 premerge：5 项 direct checks、11 项 selected checks 全部通过，零失败。另行执行的共享入口 smoke、placement smoke、docs-governance、Ruff 和 staged bilingual RFC check 均通过。首次环境资格检查发现新 worktree 缺少 TypeScript dev dependency；补齐锁定依赖并修正迁移文档 EOF 空行后，最终提交重新运行完整 premerge 通过。

不调用模型，复核基线的大小与默认截断位置

python3 - <<'PY'
import subprocess
base = '110893bcafeb23c166251f9aeec6fe3d829294d1'
raw = subprocess.check_output(['git', 'show', base + ':AGENTS.md'])
limit = 32 * 1024
prefix = raw[:limit]
print('bytes:', len(raw), 'omitted bytes:', len(raw) - limit)
print('cutoff line:', prefix.count(b'\n') + 1)
print('final section delivered:', b'## Benchmark Smoke Classification' in prefix)
PY

预期：bytes: 40363，omitted bytes: 7595，cutoff line: 556，末尾章节为 False。字节计算用于解释原因，真实 CLI 请求组装表用于证明宿主实际表现。

主流写法对标及 Skill / Prompt 的下一步

补充研究材料：AGENTS、Skill 与运行时 Prompt：对标及 LoopX 优化边界。材料区分官方规范、公开项目实例、当前源码观察与待验证方案，并给出复现方法。

参考范围包括 AGENTS.md 开放格式、OpenAI Docs 的指令维护建议、Claude Code/Anthropic skill 编写指导、Agent Skills 规范，以及固定版本的 Apache Airflow 和 Temporal Java SDK 实例。公开项目展示的是不同取舍，不作为“流行所以有效”的证明。

层级	当前结论	后续有界方向
AGENTS	本 PR 已实现短共享入口、项目核心功能、关键约束及按任务读取细则，并验证完整加载	对开发、UI、评审、发布、监控和无关任务观察是否读对细则，不能从加载完整推断遵守率
Skill	loopx-project/SKILL.md 有 1133 行 / 56,400 字节，是优先审查分流的入口；已有 self-repair 按症状检索、PR review 的 capability owner 可复用	保留首个权威 packet、身份/准入/停止条件；将条件流程改为有明确触发条件的直接 reference，并评测正触发、负触发、邻近歧义、授权停止和回读
运行时 Prompt	已有 typed required-reads、同次保存的 full-decision 引用、字符预算和独立行为 oracle	先量测完整模型请求并定位预算差额，再对一个 owner 做同输入 base/head 与行为对照，不建立平行 Python 决策源

新观察：同一合成 heartbeat 输入下，thin/brief/compact 均满足接口字符预算；full 的归一化字符数为 13,277 / 12,640，关闭 Reward Memory 后为 12,857 / 12,000，均不满足该 fixture 的自身预算。这是新记录的源码现象，尚未证明线上故障或模型 token 超限；本 PR 未改动 loopx/ 或 skills/。不据此直接增加预算或删减授权、恢复和结算义务。

现有无 provider 的 test_host_prompt_behavior.py 8 passed，使用 scripted client，证明 oracle/负例而非真实模型成绩。研究材料明确保留 skill 触发矩阵、真实行为 eval、输入 token/缓存/延迟/费用和 effect/readback 的证据缺口；没有把这些建议描述为已完成的 Skill 或运行时 Prompt 优化。

研究补充提交 bce6ff737 亦重新运行标准 premerge：5 项 direct checks、11 项 selected checks 通过，零失败。该结果与上面的 full 合成字符预算失败分别记录。

交付边界

本 PR 交付仓库指令及其回归保护。托管 CI、精确 head 的 review 和合并授权仍为独立 gate，以 PR Checks 和 review 状态为准。现有会话可能保留旧指令；采用合并后的 checkout 时，需要新会话或显式重读才能依赖更新。

[loopx-agent]

Reviewer: model_agent; gpt-6.1-sol; OpenAI; runtime_reported; reasoning_effort=max

Exact head: bce6ff737351667c450f6baff0b4c2deed1be8e8；不可变基线：110893bcafeb23c166251f9aeec6fe3d829294d1。完整当前提交的独立审查；未读取、轮询或等待 GitHub CI。

非阻塞复现修正（P3）

未发现本次提交的阻塞问题。字符预算表有一项精确复现偏差：按公开片段、在当前源码和不可变 110893bca，full 的归一化结果均为 13,265/12,640、12,845/12,000，即超 625/845；表格写为超 637/857。thin/brief 差 6 字符，compact/full 差 12 字符。两个 revision 的完整预算对象相等，full 超预算的定性结论一致，所以不阻塞根加载修复。建议固定表格实际完整输入与 revision，修正数值或说明差异来源；当前没有推断其原因，也没有放松任何预算。

动机

在仓库启动 Codex 或 Claude Code 的贡献者，需要可靠加载同一套项目规则。 原根指令超过默认加载预算，Codex 实际请求中后段规则被截断；现在根入口完整加载，再按正在进行的开发、审查或发布动作读取强制流程，避免无关任务常驻全部细节。 本次实际 Codex 请求组装证明旧入口只有 32,768 字节，新入口 10,246 字节完整出现一次；原 78 段义务和 27 个根标题锚点均保留。 本次不证明模型必然遵守指令，也不代表 Claude 已在本机独立运行或旧会话已自动更新。 不同全局指令组合、独立 Claude 执行和长期宿主采用仍需各自真实会话验证，不能由静态检查代替。 研究表格的精确字符数在当前公开片段下存在小幅复现差异，作为非阻塞修正项记录。

改动思路

这里改变的是 Agent 实际接收规则的方式，不能因为后缀为 Markdown 就当作无行为影响的整理。根入口保留通用边界、产品定位与动作触发，三份既有 owner 流程按交付、工程、运营归并；每个入口明确“在动作之前读取并遵守”，详细文档再声明例外和权限边界仍然强制。Claude 启动导入同一根文件，避免维护第二份规则。相比让每个人增大全局限制，这个边界能在默认宿主上工作；相比删短全部规则，原义务完整保留；相比 eager import 全部细节，不会把原来的上下文成本搬到另一个文件。该修复是完整、可回滚的指令交付切片，不要求另造 loader 或产品设置。下表是源代码与宿主观测的说明，不是模型遵从证明。

场景	原入口	当前入口
默认 Codex 启动	40,363 字节根文件进入预算后只剩前 32,768 字节	10,246 字节根入口完整出现一次
开发／UI／审查／发布	所有流程试图常驻，后段可能缺失	动作前强制读取对应完整流程
无关解释任务	常驻无关发布和 benchmark 细节	通用权限／隐私仍适用，任务细节不 eager import
Claude 启动	需保持宿主入口一致	CLAUDE.md 仅 @AGENTS.md，共用同一规则

具体改动

关键内容讲解

1. AGENTS.md 从 687 行缩为 195 行／10,246 字节，保留全部 27 个既有根标题锚点，新增产品定位与使用方式。根中仍可直接看见 clean worktree、PR、DCO、双语、隐私和明确合并授权等边界，不把详细读取写成可选背景。
2. agent-delivery.md、agent-engineering.md、agent-operations.md 以原章节为单位移动。独立规范化只处理空白、标题和解析后的等价相对链接，原 78 段义务全部保留；逐节检查了 modality、适用范围、证据来源、授权、继续与停止条件，不能仅凭段落哈希通过。提交卫生增加的两个子标题和 release 小节提升层级没有删掉义务。
3. CLAUDE.md 只有原生 @AGENTS.md 导入。详细流程是普通 Markdown 链接，既不 eager import，也不另建宿主政策副本。新的加载说明明确旧会话可能保留旧内容、全局上下文仍可能耗尽预算、加载不等于遵从。
4. agent-instructions-smoke.py 检查根预算、精确共享导入与本地目标／锚点，负例覆盖文档缺失、锚点错误、字节／行超限及 prose-only alias；现有 placement 和 docs-governance 读者迁移到新 owner，没有为搬移的规则再造平行检查体系。

规范映射基于 修改前完整 AGENTS.md：义务保真：implemented，原段落、顺序、例外与停止条件保留；完整根加载：implemented，当前宿主实际请求有同条件 base/head 对照；任务适用范围：implemented，开发、暂存、UI、review/merge、release、monitor 和无关任务七条路线逐项追到目标；可维护边界：implemented，原锚点保留且负例拒绝错误目标；模型遵从／独立 Claude 运行：未验证，不伪装成通过。基线已有的 first-screen evidence 政策原样迁移，不能把本次拆分误说成对那项政策的新授权或新限制。

对主干的风险

最强风险是文件仍存在、链接也有效，但根把“必须读取”改成“可以阅读”，或者迁移让某类动作失去原 stop gate。本次除全量段落与锚点对照，还检查根 read-before-action 和每个动作触发：暂存前完整卫生与隐私扫描、UI 前设计与 packaged journey、审查前 capability lenses、合并前精确 head/readiness/明确授权、发布前个人指南及双语操作说明、monitor 保留原生 Todo／泛化调度边界；无关解释任务不被发布／benchmark 前提绑架。这是源规则反事实分析，不宣称模型真的执行过七个任务。

独立实际宿主是 codex-cli 0.162.0-alpha.17.2，与作者报告的版本分开记账。用 fresh/read-only/ephemeral、忽略用户配置与 rules 的同条件请求组装，向自有 loopback 拒绝服务发送请求；服务故意 HTTP 400，零模型推理、零模型工具执行、无全局配置修改。观测旧根只加载前 32,768 字节且缺最后章节；当前根 10,246 字节完整出现一次，最后的 Benchmark Smoke Classification 和强制读取入口存在。没有保存请求 header／凭据或周围私有 prompt。官方 OpenAI AGENTS 文档 支持默认合计 32 KiB 约束；此探针证明 request assembly，不证明遵从，也不覆盖任意个人全局组合。

本机没有 Claude 可执行文件，因此未安装或伪造执行结果。已核对 Claude 官方 memory 文档 的启动相对导入及原生 AGENTS discovery 条件；精确共享 import 也支持未原生发现 AGENTS 的版本。独立 Claude 会话 readback 保持未验证。entry/placement/docs-governance、Ruff、双语检查通过；native premerge 5 个直接检查＋11 个选中命令全部通过，无 manual holds。负例能检出坏链接和导入，但不证明文字语义，因此与独立 clause/route 分析分开记录。

当前 head 在原实现之后只增加 175 行研究说明，总计 9 个路径、+1139/-611。发布前完整重审新增文档，并对 AGENTS.md、CLAUDE.md、三份流程、三项原检查、整个 loopx/ 与 skills/ tree 逐一比较 Git object：与实际 host 探针所用的 0c5da025f6097d5026885e44356bdad22d86b3f7 完全相同。因此复用的32KiB加载证据仍明确标记原执行 revision，并附当前输入未变的证明；新 head 的 premerge 和研究相关检查重新执行。旧 head 没有发布过审查。

新增研究区分官方原则、公开仓库实例、当前源代码与未来建议，未修改 skills 或运行时 prompt。独立核对固定 revision 的 Airflow/Temporal 原文、技能和 builder 源码归属及文件计量；OpenAI 的按任务读取建议、Agent Skills 分层资源规范、Anthropic eval-first 建议支持这些写作取舍，不能充当 LoopX 效果证明。当前源码实际运行同一纯 builder 的 base/head 对照均为 thin/brief/compact 在预算内、full 超625/845；8项 host_prompt_behavior 测试通过，明确使用 scripted client。没有执行生成的任务正文、读取或改写活动 Goal、调用模型或 provider，也没有把字符数当 token 或线上故障。小幅精确计量复现差异见开头P3，原因未臆测。

语义与 CI 对齐

共享根属于自动加载的行为表面，已经明确披露加载与范围变化；没有新增状态枚举、权限来源、scheduler 或 quota 规则。12 KiB／200 行是机器检查的仓库维护限制，任务流程是强制 Agent 指令，均没有被包装成可忽略 guidance；模型遵从另需观测。原任务规则的 owner、权限、continuation 和 stop gate 没有因短根或绿色 smoke 获得豁免。

我的整体评价

APPROVE（一个非阻塞 P3），交付判断为 justified_increment。 long_horizon=improved：实际截断得到修复，尾部持续工作与停止条件重新可发现，原义务完整保留；user_experience=improved：贡献者用现有目录和默认宿主启动即可，无需人的全局设置调整或额外批准轮次。未来重构检查已落实为一个共享根和三个按变化原因聚合的 owner；继续抽象自动 loader 会增加成本，当前没有必要。完整加载切片可以单独验收和回滚；模型遵从、Claude 独立执行、旧会话更新和更广安装采用仍分别保留。审查认可不提供 merge/bypass 授权，未执行合并。

English verdict: APPROVE with one non-blocking reproducibility nit — bce6ff737351667c450f6baff0b4c2deed1be8e8. Independent actual Codex request assembly reproduces the old 32 KiB truncation and loads the complete new root once. All 78 original obligation paragraphs and 27 root anchors remain, required task routes were assessed, and focused checks plus 5+11 native premerge commands pass. Model compliance and independent local Claude execution are explicitly unverified; merge authority remains separate.

[loopx-agent]

[P3] 补齐字符预算表的精确复现输入

当前源码环境在两个 revision 得到相同 full 归一化字符数13265/12640、12845/12000，即超625/845；表格为13277/12640、12857/12000，即超637/857。thin/brief也相差6，compact/full相差12。总体full超预算结论一致，但固定表值无法按公开片段逐字重现，后续同workload基线比较可能误用。未据此推断原因、线上故障或本PR回归。

最小修复：把实际完整合成参数、对应源码 revision 和可执行测量片段固定到同一来源；修正表值或明确其不同输入/环境，并保留字符预算与token/模型效果的区别。

[songoow]

Superseded by #6725 after comparing the complete proposal at bce6ff737351667c450f6baff0b4c2deed1be8e8 with the consolidated implementation at 971791dd09d73e92d83ae878dde46df68ffba6bc.

项目定位与核心能力说明、单一 CLAUDE.md -> @AGENTS.md 入口、外部规范与公开实现的研究依据已纳入 #6725。默认加载截断、根文件/链接保护也由后继 PR 覆盖；项目 skill 的六份打包 reference、当前授权/准入/恢复/结算和内部 prompt 修复则在同一后继 PR 内交付。

未引入三份额外的 agent 流程文档：对应细则归入既有 development、release、state-machine、extension 和 smoke owner，避免维护平行政策。12 KiB / 200 行是本提案的维护选择，不是宿主硬限制；后继保留必要义务，根为 27,976 字节，并重新实测 Codex 0.163.0 与 Claude Code 2.1.302 的首次请求均包含完整正文一次。实际模型遵守与 live long-horizon 效果仍未证明。

关闭只表示重复提案被整合替代，不表示已合并；保留该分支、研究与审查历史。此 PR 旧 head 的批准、CI 和加载证据不转移到 #6725，后继使用自己的 exact-head 验证与评审。详细问题、取舍、参考来源和验收结果见 #6725 的说明。