[refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1)

[loning]

SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1)

skill 自审 producer 发现 #1(requires_design)。完整 evidence/why/fix-boundary 见仓库 .refactor-loop/runs/self-audit-skill.md 第 1 条。solver 先读该条 + 相关 file:line。

走 Phase 9 多 solver 共识。📢 cc @loning

⟦AI:AUTO-LOOP⟧

[loning]

📊 状态卡片 — solver 派出

维度	值
阶段	派出 codex(role=solver)
codex log	phase9-issue12-r1.log
工作目录	/Users/auric/consensus-rnd
no-output stall window	5400s(~90 min 无输出窗口)
上下文	启动 Phase 9 r1:派 3 个独立 solver(minimal/structural/delete)评估 SKILL.md 拆分 controller 契约 vs REFERENCE。
下一步自动会做	1. 三 solver SOLVER_DONE:... 2. controller 派 meta-judge r 3. consensus → implement / converge → fresh round
是否需要人介入	❌ 否(自动推进)

🤖 controller status banner

⟦AI:AUTO-LOOP⟧

[loning]

🤖 minimal solver:建议只拆重型参考段落

TL;DR

• 这是什么: issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 的 minimal solver 输出,验证 SKILL.md 过重问题仍存在。
• 结论:建议只把长模板、示例、历史说明和 reference-manual 细节移到 REFERENCE.md,保留 SKILL.md 的 controller 硬约束。
• 下一步:等另外两个 solver 和 meta-judge 汇总,若达成共识再进入实现。

---

详细说明

SKILL.md 当前约 2537 行,REFERENCE.md 约 355 行;self-audit #1 指向的 concurrency floor、status/escalation banner 模板、Phase 9 共识卡片模板等重型内容仍在入口文件里。最小边界是不改 manifest、不改 frontmatter、不改 controller 语义,只把这些 reference 级内容搬到 REFERENCE.md,并在 SKILL.md 留 3-6 条强制规则摘要和普通相对 Markdown 链接。

测试建议是加一个 source-regression guard:检查 SKILL.md 行数预算、frontmatter 只含 name/description 且 ≤1024 字符、引用 REFERENCE.md 时不用 @REFERENCE.md。这满足 AGENTS.md 对 skill 修改的 TDD 纪律,但不引入 runtime 迁移。

---

📎 完整 codex 原始输出(存档备查)

---

solver: minimal
issue: 12
cluster: skill-md-controller-split
verdict: propose

Recommended framing

The violation is real: skills/codex-refactor-loop/SKILL.md is 2537 lines while REFERENCE.md is 355 lines, and the cited heavy areas are still present, though line numbers shifted slightly from the self-audit. The smallest viable fix is not a full rewrite; keep SKILL.md as the controller entrypoint and hard invariant index, then move only long templates, examples, historical lessons, and recovery/reference material into REFERENCE.md. SKILL.md should retain short normative bullets plus relative Markdown links such as See REFERENCE.md#concurrency-floor-reference; do not use @REFERENCE.md, because that can force eager loading in some host contexts.

Concrete plan (English)

• Files: skills/codex-refactor-loop/SKILL.md — shrink selected heavy sections into controller-contract summaries and lazy relative links. Keep frontmatter unchanged; keep name and description only.
• Files: skills/codex-refactor-loop/REFERENCE.md — append moved reference sections under stable headings: Controller operations reference, Concurrency floor reference, Status banner templates, Escalation banner template, Phase 9 consensus card template, Historical migration notes.
• Files: skills/codex-refactor-loop/scripts/test_skill_entrypoint_contracts.py or existing test_ensure_project_rules_fixed_points.py — add source-regression checks that SKILL.md stays below a documented line budget, frontmatter has only name and description, frontmatter length is <=1024 chars, and SKILL.md references REFERENCE.md without @REFERENCE.md.
• Boundary to keep in SKILL.md: frontmatter; host config table; daemon startup command pattern; wake-source invariant; GitHub-state invariant; pure-orchestration rule; quick start; sentinel final-line rule; state source-of-truth summary; phase list and each phase's controller obligations; hard rules; language rule; file index.
• Boundary to move to REFERENCE.md: detailed concurrency-floor rationale, fill-priority table, shell snippet, duplicate anti-pattern list, and historical lesson currently around SKILL.md:1950-2018; full status banner Markdown template and full escalation banner template currently around SKILL.md:2066-2198; detailed Phase 9 consensus-card Markdown template currently around SKILL.md:1824-1866; recovery/playbook-style explanations and historical bilingual migration note currently around SKILL.md:2509-2515.
• Cross-file reference style: use normal relative links, for example [Concurrency floor reference](REFERENCE.md#concurrency-floor-reference). The contract sentence in SKILL.md should summarize the mandatory rule in 3-6 bullets, then link to the reference for examples/templates. Avoid @REFERENCE.md, absolute local paths, and host-specific .claude/skills/... links in new text.
• Host loading / skill discovery impact: no manifest or loader changes. Claude Code, Codex, Cursor, and Gemini still discover the same skills/codex-refactor-loop/SKILL.md; only optional reference material moves behind lazy Markdown links. Existing scripts and prompts keep their paths.
• Frontmatter <=1024 chars: no change needed. Current frontmatter body is about 274 chars and already has only name plus description; the split should not add workflow text to description.
• LOC delta: ~+650 / -900 net about -250 lines in SKILL.md plus moved content in REFERENCE.md; if content is copied nearly verbatim, total repo LOC net should be ~+40 / -40 excluding small heading/link edits. The important metric is SKILL.md dropping from ~2537 to roughly 1650-1800 lines, not repo-wide deletion.
• Tests to add/modify: 1 test file, 4-5 assertions. No behavior test of controller runtime is needed because this is documentation layout, but a source-regression guard is needed because AGENTS.md requires TDD discipline for skill edits.
• Philosophy/PROJECT_RULES/SPEC/Tier change: none. Existing AGENTS.md already says heavy references belong in REFERENCE.md; this plan implements that rule and does not change Tier boundaries or controller semantics.
• Migration path: one documentation-only PR; no runtime migration needed.

Concrete plan (中文)

• 文件: skills/codex-refactor-loop/SKILL.md — 把选中的重型段落压成 controller 契约摘要和惰性相对链接。frontmatter 不改,仍只保留 name 和 description。
• 文件: skills/codex-refactor-loop/REFERENCE.md — 追加被移出的参考段落,建议稳定标题为 Controller operations reference、Concurrency floor reference、Status banner templates、Escalation banner template、Phase 9 consensus card template、Historical migration notes。
• 文件: skills/codex-refactor-loop/scripts/test_skill_entrypoint_contracts.py 或现有 test_ensure_project_rules_fixed_points.py — 加 source-regression 检查: SKILL.md 不超过明确行数预算;frontmatter 只含 name 和 description;frontmatter 长度 <=1024 字符;SKILL.md 引用 REFERENCE.md 时不使用 @REFERENCE.md。
• 留在 SKILL.md 的边界: frontmatter;host 配置表;daemon 启动命令 pattern;wakeup 来源不变量;GitHub 状态面不变量;pure-orchestration 规则;quick start;sentinel final-line 规则;状态源摘要;phase 列表和每个 phase 的 controller 职责;hard rules;语言规则;文件索引。
• 移到 REFERENCE.md 的边界: 当前约 SKILL.md:1950-2018 的 concurrency floor 详细动机、填充优先级表、shell snippet、重复反面清单、历史教训;当前约 SKILL.md:2066-2198 的完整 status banner / escalation banner Markdown 模板;当前约 SKILL.md:1824-1866 的 Phase 9 consensus-card 完整 Markdown 模板;恢复手册式说明和当前约 SKILL.md:2509-2515 的历史 bilingual 迁移说明。
• 跨文件引用方式: 用普通相对 Markdown 链接,例如 [Concurrency floor reference](REFERENCE.md#concurrency-floor-reference)。SKILL.md 中每处只保留 3-6 条强制规则摘要,例子和模板放链接后面。不要用 @REFERENCE.md,不要新增绝对本机路径,也不要新增 host-specific .claude/skills/... 链接。
• 对 host 装载 / skill discovery 的影响: 不改 manifest 和 loader。Claude Code / Codex / Cursor / Gemini 仍从同一个 skills/codex-refactor-loop/SKILL.md 发现 skill;只有详细参考内容改为按需点开。现有 scripts/prompts 路径不变。
• frontmatter <=1024 字符: 不需要改。当前 frontmatter 约 274 字符,且已经只有 name 和 description;拆分时不要把流程摘要塞进 description。
• LOC 估算: SKILL.md 约 +650 / -900,净减少约 250 行;若多数内容原样搬到 REFERENCE.md,仓库总 LOC 净变化约 +40 / -40,主要是新增标题、锚点和链接。关键指标是 SKILL.md 从约 2537 行降到约 1650-1800 行,不是追求仓库总删除量。
• 测试: 1 个测试文件,4-5 个断言。因为这是文档布局调整,不需要 controller runtime 行为测试;但修改 skill 按 AGENTS.md 的 TDD 纪律需要 source-regression guard。
• Philosophy / PROJECT_RULES / SPEC / Tier 改动: 无。AGENTS.md 已经规定重型参考拆 REFERENCE.md;本方案只是执行该规则,不改变 Tier 边界或 controller 语义。
• 迁移路径: 单个文档 PR;无需运行时迁移。

Risks

• Moving text can break informal line-number references in old comments; mitigate by using stable headings in REFERENCE.md.
• If the implementer moves too much, SKILL.md may stop being operational during controller wakeups; mitigate by keeping all mandatory controller actions summarized in SKILL.md.
• A line-budget test can become brittle; set it as a generous regression ceiling, not an aggressive shrink target.
• This does not solve every inconsistency listed in self-audit findings 2-16; it only fixes issue 12's entrypoint/reference split.

Escalation triggers (if any)

• None.

Reasoning trace (internal — short, for meta-judge)

• Why this is the minimum: the existing rule already requires heavy references in REFERENCE.md; the smallest fix is moving the few obvious reference-manual blocks while preserving controller semantics and discovery metadata.
• What I considered but rejected: a full SKILL.md rewrite into a tiny phase index; that would be cleaner but high risk because many controller invariants are currently embedded in phase prose. I also rejected changing AGENTS.md because the current rule is already sufficient.
• What I cannot decide alone: the exact final line budget for SKILL.md; I propose a generous ceiling around 1800 lines and leave the final number to implementation after moving the named blocks.

SOLVER_DONE:minimal:propose:split only heavy templates/examples/history into REFERENCE.md while keeping controller invariants and frontmatter in SKILL.md

⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

🤖 structural solver: 建议拆成 controller 契约索引 + REFERENCE runbook

TL;DR

• 这是什么:issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 的 structural solver 方案,聚焦 SKILL.md 过重的结构拆分边界。
• 结论:建议把 SKILL.md 缩成约 650-750 行 controller 契约索引,把模板/runbook/schema/历史教训移到 REFERENCE.md。
• 下一步:等另外两个 solver 完成后,controller 派 meta-judge 做 Phase 9 共识裁决。

---

详细说明

我核对了 CLAUDE.md 的约束、self-audit #1、audit-iter-3.md、issue #12 以及当前文件结构。当前 SKILL.md 为 2537 行,REFERENCE.md 为 355 行；最大块集中在 Phase 7/8/9、Phase 1/4/6、loop control 和 status/escalation 模板。违反点对应的是 CLAUDE.md 的“重型参考拆 REFERENCE.md;脚本放 scripts/;prompt 模板放 prompts/。”

方案不新增运行时 actor、Channel 或 event envelope；这是 packaging / loader-scope 问题,不是控制流语义问题。新增的只是文档层面的 Controller Contract Index:每个 phase 在 SKILL.md 保留不变量、controller action、prompt/script surface 和 REFERENCE.md#anchor 链接。跨文件引用只用普通相对 Markdown link,避免 @REFERENCE.md 这种强制整文件加载写法。

决策点	建议	成本
SKILL.md 边界	保留触发条件、host 配置、硬不变量、per-wakeup skeleton、phase index、hard rules	约 -1800 到 -1900 行
REFERENCE.md 边界	承接 daemon runbook、完整模板、schema、Phase 7/8/9 细节、恢复手册	约 +1750 到 +1950 行
测试	加 source guard 验 frontmatter、anchor、lazy reference、边界	约 +180 到 +260 行
manifest/discovery	不改 manifest；现有平台都以 skills/ / SKILL.md 为入口	运行时 0 成本

---

📎 完整 codex 原始输出(存档备查)

---

solver: structural
issue: 12
cluster: skill-md-controller-split
verdict: propose

PROJECT_RULES clause violated (quoted verbatim)

• 重型参考拆 REFERENCE.md;脚本放 scripts/;prompt 模板放 prompts/。

Supporting constraints that frame the fix:

• 每个 skill 一个目录:skills/<kebab-name>/SKILL.md。
• frontmatter 仅需 name + description(全文 ≤1024 字符)。description 以 "Use when..." 描述触发条件,不要复述工作流。
• skills/codex-refactor-loop/ 为 host 项目移植,verbatim,仍带"重构"外壳与少量 host 主张。泛化路线见 README.md 的「泛化路线」。脱壳 / 重命名前不要改它的正文逻辑；例外：经 Phase 9 deep consensus 明确授权的 host-agnostic bootstrap / policy 注入修正可先落地，但不得引入具体 host 事实，且必须配套行为测试。

Verified evidence: skills/codex-refactor-loop/SKILL.md is 2537 lines while REFERENCE.md is 355 lines. The largest SKILL sections are Phase 7 246 lines, Phase 9 223 lines, Phase 8 189 lines, Phase 4 136 lines, Phase 6 123 lines, Phase 1 123 lines, plus detailed Loop control/status/escalation material. Self-audit evidence is confirmed: concurrency floor detail begins at SKILL.md:1950, escalation banner template begins at SKILL.md:2109, and the Files section lists REFERENCE.md only as state schema / batching / recovery at SKILL.md:2537.

Recommended framing (English)

Split SKILL.md into a small mandatory controller contract and a phase-index, then move long runbooks, templates, examples, historical lessons, and schemas into REFERENCE.md under stable relative anchors. The new structure eliminates the violation by construction: host skill discovery and first-load guidance only see the contract needed to decide and route, while execution detail is loaded by explicit phase-local links such as [REFERENCE.md#phase-9-design-consensus-runbook](REFERENCE.md#phase-9-design-consensus-runbook). No runtime actor, Channel, event envelope, or projection abstraction is needed; the relevant repo primitives are the existing skill entrypoint, relative reference file, prompt templates, scripts, GitHub-visible state surface, and WorkUnitV1 contract.

Recommended framing (中文)

把 SKILL.md 拆成精简的 controller 契约 + phase 索引，把长 runbook、模板、示例、历史教训、schema 移到 REFERENCE.md 的稳定相对 anchor 下。这样从结构上消除违反点:host 的 skill discovery 和首次加载只读“何时触发、必须遵守哪些不变量、每个 phase 如何路由”，执行某个 phase 时再按需打开 [REFERENCE.md#phase-9-design-consensus-runbook](REFERENCE.md#phase-9-design-consensus-runbook) 这类链接。这里不需要新增运行时 actor、Channel、event envelope 或 projection 抽象；适用的现有原语是 skill 入口、相对 reference 文件、prompt 模板、scripts、GitHub 状态面、WorkUnitV1 契约。

Concrete plan

• New abstractions (if any): Controller Contract Index, a documentation-only contract in skills/codex-refactor-loop/SKILL.md. Interface: each entry has Invariant, Controller action, Reference anchor, and Prompt/script surface. Layer: skill packaging / controller documentation. Project: consensus-rnd. Filename: skills/codex-refactor-loop/SKILL.md. This is justified by the explicit cross-platform skill-entrypoint extension point and two concrete callers: host agents loading SKILL.md for discovery/execution, and prompt/script maintainers validating controller contracts.
• Files:
  • skills/codex-refactor-loop/SKILL.md: shrink to ~650-750 lines. Keep frontmatter, host config variable table, controller invariants, first-wakeup checklist, per-wakeup sweep skeleton, phase index, hard rules, language policy, and Files index. Replace long sections with short contract rows plus relative links.
  • skills/codex-refactor-loop/REFERENCE.md: expand to ~2100-2300 lines. Move detailed daemon startup runbook, exact bash snippets, Phase 0 state bootstrap JSON, Phase 1 audit validation checklist, Phase 4 stacked/single PR procedures, Phase 6 daemon procedure, Phase 7/8/9 detailed algorithms, concurrency floor examples, status/escalation banner templates, label bootstrap commands, recovery playbook, state schema, batching heuristics, and historical lessons.
  • skills/codex-refactor-loop/scripts/test_skill_entrypoint_contract.py (new): behavior/source guard for frontmatter shape, description prefix, <=1024 chars, valid relative links, no forced @REFERENCE load syntax, and required controller contract headings.
  • skills/codex-refactor-loop/scripts/test_skill_reference_anchors.py (new or folded into the prior test): validates every SKILL reference anchor exists in REFERENCE and each phase index entry has a runnable-detail anchor.
  • skills/codex-refactor-loop/scripts/test_ensure_project_rules_fixed_points.py: optional small extension only if existing fixed-point tests are the preferred home; otherwise leave untouched.
• Split boundary:
  • Keep in SKILL: Host 配置 as a compact variable contract; GitHub 是系统状态唯一显示面; sentinel final-line rule; Controller = pure orchestration; Quick start; 状态源 as a sweep checklist; Phase 0-9 one-screen controller contract rows; loop stop/floor invariants in summary form; label groups as canonical names only; codex spawn contract in summary form; hard rules; language policy; file index.
  • Move to REFERENCE: exact daemon nohup bash -c examples and singleton repair commands; detailed anti-pattern narratives; full initial state.json; audit validation substeps; batching heuristics; PR stack/single detailed procedures; CI watch commands; Phase 7 monitor script bodies; Phase 8/9 dispatch templates and consensus card body; full status/escalation banner markdown templates; concurrency floor rationale/examples/scripts; label creation shell loops; recovery playbook; WorkUnitV1/state schema; historical postmortems.
  • Cross-file references: use normal relative Markdown links only, for example [REFERENCE.md#status-banner-templates](REFERENCE.md#status-banner-templates). Do not use @REFERENCE.md, absolute local paths, or wording that forces all hosts to preload the full reference. SKILL should say: "Load only the referenced REFERENCE anchor for the phase being executed or debugged."
  • Host loading / discovery impact: no manifest change. .codex-plugin/plugin.json and .cursor-plugin/plugin.json already point to "skills": "./skills/"; Gemini already says read SKILL.md on demand; Claude plugin remains package metadata. Shorter SKILL improves discovery token cost and keeps installed skill identity stable. REFERENCE.md remains packaged because repo rules already define skills/<name>/ paired files as the product surface.
  • Frontmatter: keep current name + description only. Current frontmatter body is 275 chars and starts with Use when; do not add workflow detail there. Add a test so future edits fail if the frontmatter exceeds 1024 chars or adds extra keys.
• LOC delta: SKILL.md ~-1800 to -1900 lines; REFERENCE.md ~+1750 to +1950 lines; tests ~+180 to +260 lines; net repository delta ~+130 to +310 lines because moved content is mostly conserved and anchor/index text is added.
• Tests to add:
  • 1 source behavior test for skill entrypoint contract: frontmatter shape, <=1024 chars, Use when, no extra frontmatter keys, required top-level contract headings.
  • 1 source behavior test for lazy reference loading: all SKILL links to REFERENCE.md#... resolve, no @REFERENCE forced-load syntax, no absolute /Users/... reference.
  • 1 source behavior test for split boundary: bulky templates and schemas live in REFERENCE, while SKILL retains canonical labels, sentinel, GitHub state, and controller pure-orchestration invariants.
• proto changes (if any): none.
• Philosophy/PROJECT_RULES/SPEC/Tier changes (if any): none. This is directly aligned with the existing 重型参考拆 REFERENCE.md clause. The verbatim-freeze clause allows Phase 9 deep consensus to authorize host-agnostic policy/bootstrap fixes with behavior tests; this split is packaging hygiene and does not introduce host facts, rename the skill, or change the runtime protocol.
• Runtime cost: 0 latency hops and 0 runtime allocations. Agent-time cost changes: first-load token cost drops by roughly 70% (SKILL.md 2537 lines to ~700 lines); executing a detailed phase adds one explicit reference file read for that phase, usually ~100-300 lines, not the whole 2300-line reference.

Risks

• The main tradeoff versus a minimal change is test and anchor maintenance: every moved section needs a stable anchor, and future edits must keep SKILL links valid.
• Over-engineering risk is turning the split into a new documentation framework. Keep it bounded to one documentation-only Controller Contract Index, one REFERENCE.md, and source guards; do not add registries, generated docs, state migrations, or new prompt loaders.
• If too much operational detail is removed from SKILL, a first-wakeup controller may under-bootstrap. Mitigation: SKILL keeps the exact first-wakeup checklist and links to phase-local runbooks for command details.

Escalation triggers (if any)

• none

Reasoning trace (internal — for meta-judge)

• Why this structure beats a documented exception: the rule already says heavy reference belongs in REFERENCE.md; keeping a 2537-line SKILL as an exception would normalize future drift and increase loader cost. A contract/index split makes the intended boundary mechanically testable.
• Why I picked this abstraction over alternatives: a runtime abstraction like actor inbox, Channel, or event envelope would not address the violation because the problem is packaging and loader scope, not control-flow semantics. A documentation-only contract index is the smallest structural abstraction that has real callers and a testable interface.
• What I cannot decide alone: exact final line budget for SKILL should be set by consensus, but the structural target should be under ~750 lines and enforced through semantic guards rather than a bare line-count test.

SOLVER_DONE:structural:propose:split SKILL into ~700-line controller contract index plus lazily linked REFERENCE anchors; no runtime abstraction or manifest change

⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

🤖 delete solver:不建议删除,保留拆分需求

TL;DR

• 这是什么: issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 的 delete solver 输出,专门质疑“是否需要做”。
• 结论:不建议删除该需求;SKILL.md 入口和 REFERENCE.md 都是承载面,问题是边界过重而非可删。
• 下一步:让 minimal/structural 的拆分方案进入 meta-judge,delete 侧 abstain。

---

详细说明

我检查了 issue #12、self-audit #1、audit-iter-3.md、CLAUDE.md 的 重型参考拆 REFERENCE.md 规则、SKILL.md 标题/行数分布、REFERENCE.md 结构、manifest discovery 入口和相关 git history。当前 SKILL.md 为 2537 行,REFERENCE.md 为 355 行;各平台仍通过 skills/<name>/SKILL.md 发现 skill,所以不能删除入口契约。

delete 侧的结论是 abstain:不要删 issue,不要删 REFERENCE.md,也不要把 controller 契约整体移走。合理边界是 SKILL.md 保留 frontmatter、host 配置、controller 硬不变量、phase 职责和短索引;长模板、恢复手册、历史教训、rationale-heavy 示例和 schema 细节放到 REFERENCE.md。跨文件引用应使用普通相对 Markdown 链接,避免 @REFERENCE.md 强制加载。

---

📎 完整 codex 原始输出(存档备查)

---

solver: delete
issue: 12
cluster: skill-md-controller-split
verdict: abstain

Classification

e) Genuinely needed and right-sized for the deletion decision: the requested controller-vs-reference split is a real repository maintenance need, not dead code, not an orphan feature, and not replaceable by deleting the skill entrypoint or REFERENCE.md. The current SKILL.md is not right-sized as a document, but the correction is a boundary split that should be designed by minimal/structural solvers rather than a deletion-first removal of the capability.

Recommended action (English)

Do not delete issue 12, do not delete REFERENCE.md, and do not delete the controller contract from SKILL.md. Keep the split requirement: SKILL.md should remain the discoverable controller contract and phase index, while long templates, recovery playbooks, historical postmortems, rationale-heavy examples, and schema/reference details belong in the existing REFERENCE.md. As delete solver, I abstain from proposing implementation because the value chain is load-bearing: all host discovery still enters through skills/codex-refactor-loop/SKILL.md, and the repository rules already require heavy references to be split into REFERENCE.md.

Recommended action (中文)

不要删除 issue 12,不要删除 REFERENCE.md,也不要把 controller 契约从 SKILL.md 中删掉。应保留拆分需求:SKILL.md 继续作为各平台能发现的 controller 契约和 phase 索引;长模板、恢复手册、历史复盘、动机/示例密集段落、schema/reference 细节放进现有 REFERENCE.md。作为 delete solver,我不提出落地实现方案,因为这条价值链是承载运行能力的:所有 host discovery 仍从 skills/codex-refactor-loop/SKILL.md 进入,而仓库规则已经要求重型参考拆到 REFERENCE.md。

Concrete plan (if propose)

• Files to delete: none.
• Caller migrations: none. Platform manifests keep pointing to skills/; discovery still resolves skills/codex-refactor-loop/SKILL.md.
• Tests to delete: none.
• LOC delta: -0 for deletion. A non-delete split may reduce SKILL.md by roughly 400-800 lines while moving selected text into REFERENCE.md; that is not a deletion-first plan.
• Philosophy/CLAUDE.md/SPEC/Tier changes (if any): none. CLAUDE.md already states 重型参考拆 REFERENCE.md;脚本放 scripts/;prompt 模板放 prompts/; no philosophy change is needed.
• Tracking issue (if defer): none. This is not deferrable under the prompt rules; the issue should remain active and be handled by a split plan.

Boundary Notes For Meta-Judge

• Keep in SKILL.md: frontmatter; host configuration variables; daemon startup invariant; wake-source invariant; GitHub-as-state invariant; controller pure orchestration rule; quick start; sentinel final-line rule; state source-of-truth summary; each phase's controller obligations; hard rules; working language policy summary; file index.
• Move or summarize into REFERENCE.md: full status banner Markdown template; full escalation banner template; Phase 9 consensus-card template; concurrency floor rationale, priority table, shell examples, and historical lessons; recovery/playbook-style material; state schema and batching heuristics already in REFERENCE.md; historical bilingual migration notes.
• Cross-file links: use ordinary relative Markdown links such as [Concurrency floor reference](REFERENCE.md#concurrency-floor-reference). Avoid @REFERENCE.md, absolute local paths, and new host-specific .claude/skills/... references so host loaders do not eagerly inject the reference file.
• Host loading / skill discovery impact: no manifest changes. .codex-plugin/plugin.json and .cursor-plugin/plugin.json expose "skills": "./skills/"; Gemini says skills are read on demand; Claude/Codex/Cursor still discover the same SKILL.md.
• Frontmatter: keep only name and description. Current frontmatter is 275 characters and already below the <=1024 character rule; do not move workflow summary text into description.

Reverse-evidence (why this is safe to delete)

• No public API breaks: no deletion is proposed. rg shows platform discovery points at skills/ and GEMINI.md tells agents to read skills/<name>/SKILL.md on demand.
• No external repo dependency on the code: untouched. The proposed delete verdict does not remove scripts, prompts, manifests, or skill entrypoints.
• Tests covering the path are themselves not load-bearing: no tests are deleted. Existing tests already read both SKILL.md and REFERENCE.md, which confirms REFERENCE.md is part of the supported asset surface.
• SKILL.md is actively load-bearing: wc -l reports 2537 lines and rg '^#' shows controller phases, loop control, status banners, labels, and hard rules all live there.
• REFERENCE.md is actively load-bearing: it already contains WorkUnitV1, state schema, batching heuristics, and recovery playbook sections; deleting it would contradict existing SKILL.md links at lines 632, 663, 697, and 2537.
• Git history shows intent: initial import created SKILL.md and REFERENCE.md together; later commits added controller-critical floor and work-unit details, so the problem is accumulation in the entrypoint, not unused material.

Risks

• If the split implementation moves mandatory controller obligations out of SKILL.md without a short normative summary, first-load agents may miss hard invariants.
• If REFERENCE.md links use @REFERENCE.md or absolute paths, some hosts may eagerly load the heavy file or fail after installation into a different directory.
• If a line-budget test is too aggressive, future legitimate controller-contract additions may fail for the wrong reason.
• If historical line-number references in GitHub comments are treated as stable, moving text will make old comments less direct; stable headings mitigate this.

Escalation triggers (if any)

• none

Reasoning trace (internal — for meta-judge)

• Why I claim this can be deleted: I do not claim the issue can be deleted. The deletion-first check found the opposite: the split requirement protects a real entrypoint/reference boundary required by repository rules.
• What I checked to verify safety: gh issue view 12 --comments; .refactor-loop/runs/self-audit-skill.md finding 1; .refactor-loop/runs/audit-iter-3.md; CLAUDE.md; wc -l and heading distribution for SKILL.md; REFERENCE.md headings; manifest/discovery references; git log and blame for relevant sections; existing REFERENCE.md call sites.
• What I cannot decide alone: the exact final split size and whether to move borderline phase prose versus only templates/rationale. That is implementation design, not a safe deletion decision.

SOLVER_DONE:delete:abstain:split requirement is load-bearing; delete solver rejects deleting issue, SKILL entrypoint, or REFERENCE and leaves boundary implementation to minimal/structural

⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

📊 状态卡片 — judge 派出

维度	值
阶段	派出 codex(role=judge)
codex log	phase9-issue12-r1-judge.log
工作目录	/Users/auric/consensus-rnd
no-output stall window	5400s(~90 min 无输出窗口)
上下文	r1 三 solver 已 3/3(全 propose)→ 派 r1 meta-judge 裁决 SKILL.md 拆分共识/再收敛。
下一步自动会做	1. judge META_JUDGE_DONE:... 2. consensus → implement / converge → fresh round / escalate → reflector or 人介入
是否需要人介入	❌ 否(自动推进)

🤖 controller status banner

⟦AI:AUTO-LOOP⟧

[loning]

🤖 meta-judge:issue #12 进入第 2 轮收敛

TL;DR

• 这是什么:Phase 9 issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 r1 meta-judge 裁决。
• 结论:未达 3/3 深共识;minimal 与 structural 的拆分深度差异过大,delete solver 为 abstain。
• 下一步:controller 应派 round-2,要求三方在“约 1650-1800 行 minimal split”与“约 650-750 行 controller contract index”之间给出明确边界。

---

详细说明

当前三方共识只覆盖方向:不删除 issue / SKILL.md / REFERENCE.md,不改 manifest/frontmatter/philosophy/CLAUDE.md/SPEC/Tier,SKILL.md 保留 controller 契约入口,重型参考内容移入 REFERENCE.md,并使用普通相对 Markdown 链接。分歧在落地深度:一个方案只移动明显重型模板/示例/历史段落,另一个方案把入口压成 controller contract index 并移动大部分 phase runbook/schema/template。

方案	SKILL.md 目标	trade-off
minimal	约 1650-1800 行	first-wakeup 风险低,但入口仍偏重
structural	约 650-750 行	loader 成本下降约 70%,但 anchor/test 维护成本更高
delete	abstain	认可不能删,但未给可执行 split 深度

因此 round-2 的具体问题是:issue #12 应落地为 minimal extract-only split 还是 structural controller-contract-index split;每个 solver 必须给出 exact keep/move boundary、line budget、test strategy,并确认不改 manifest/frontmatter/philosophy/CLAUDE.md/SPEC/Tier。

---

📎 完整 codex 原始输出(存档备查)

---

issue: 12
cluster: skill-md-controller-split
convergence_round: 1
solver_verdicts:
minimal: propose
structural: propose
delete: abstain
decision: converge

Decision (English)

Convergence is required. The solvers agree that issue 12 is real, deletion is wrong, manifests/frontmatter should not change, SKILL.md must remain the discoverable controller contract, heavy reference material should move to REFERENCE.md, links should be ordinary relative Markdown links, and no philosophy/CLAUDE.md/SPEC/Tier change is needed. That is not enough for Phase 9 consensus because the gate requires 3/3 unanimity, and the concrete split depth is materially different: minimal targets SKILL.md at roughly 1650-1800 lines with only obvious heavy blocks moved, while structural targets roughly 650-750 lines with most phase runbooks/templates/schemas moved behind a controller contract index. The delete solver abstains and gives boundary notes, but does not convert those notes into a concrete implementation plan. Round 1 is below the stall threshold, so this must go to convergence rather than escalation.

Decision (中文)

需要进入收敛轮。三个 solver 都认可 issue 12 是真实问题,也都反对删除:SKILL.md 仍应作为可发现的 controller 契约入口,重型参考材料应移到 REFERENCE.md,引用方式应使用普通相对 Markdown 链接,且不需要修改 philosophy / CLAUDE.md / SPEC / Tier 边界。但这还不是 Phase 9 深共识,因为授权门槛要求 3/3 一致,而两个具体方案的拆分深度差异很大:minimal 方案把 SKILL.md 控制在约 1650-1800 行,只搬明显重型段落;structural 方案把 SKILL.md 压到约 650-750 行,用 controller contract index 承接入口,把多数 phase runbook / 模板 / schema 移到 REFERENCE.md。delete solver 是 abstain,只给边界备注,没有转成可执行实现方案。当前是第 1 轮,未达到 stall 条件,因此应收敛而不是升级。

If consensus

• Chosen framing: n/a
• Implement plan (verbatim copy from the winning solver's "Concrete plan" section): n/a
• Philosophy/CLAUDE.md/SPEC/Tier changes included: none agreed for implementation in this round
• Implementation owner: n/a
• Add auto-loop-resume label to issue 12: n/a

If converge

• Convergence question (specific): Should issue 12 land as a minimal extract-only split that leaves SKILL.md around 1650-1800 lines, or as a structural controller-contract-index split that leaves SKILL.md around 650-750 lines; give the exact keep/move boundary, target line budget, test files, and why that depth is worth the maintenance cost.
• What each solver should address explicitly:
  • Minimal solver: either defend the 1650-1800 line target against the structural contract-index proposal, or adopt the structural target with exact sections moved and tests.
  • Structural solver: either defend the 650-750 line target against first-wakeup/bootstrap risk, or narrow the move set to the minimal proposal with exact sections and tests.
  • Delete solver: abstain is allowed only if it states which concrete split depth is acceptable; otherwise propose the smallest non-delete implementation plan with exact keep/move boundaries.
  • All solvers: state whether Phase 0-9 detailed runbooks, daemon command snippets, status/escalation/consensus templates, WorkUnit/state schemas, batching heuristics, recovery playbooks, and historical notes stay in SKILL.md or move to REFERENCE.md.
  • All solvers: include one explicit line budget for SKILL.md, one test strategy, and confirmation that there are no manifest/frontmatter/philosophy/CLAUDE.md/SPEC/Tier changes.
• Round number this fires: 2

If escalate

• Trigger category: n/a
• Why consensus failed to progress: n/a
• Suggested next step: n/a

Round audit trail (links to local artifacts)

• solver-minimal: /Users/auric/consensus-rnd/.refactor-loop/runs/phase9-issue12-r1-minimal.md
• solver-structural: /Users/auric/consensus-rnd/.refactor-loop/runs/phase9-issue12-r1-structural.md
• solver-delete: /Users/auric/consensus-rnd/.refactor-loop/runs/phase9-issue12-r1-delete.md

META_JUDGE_DONE:converge:round-2:Choose minimal extract-only split (~1650-1800 line SKILL) vs structural controller-contract-index split (~650-750 line SKILL), with exact keep/move boundaries and tests.

⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

📊 状态卡片 — solver 派出

维度	值
阶段	派出 codex(role=solver)
codex log	phase9-issue12-r2.log
工作目录	/Users/auric/consensus-rnd
no-output stall window	5400s(~90 min 无输出窗口)
上下文	r1 judge=converge:round-2(minimal extract-only vs structural contract-index split 二选一)。派 r2 三 solver 带收敛问题正面作答 + 确切 keep/move 边界。
下一步自动会做	1. 三 solver SOLVER_DONE:... 2. controller 派 meta-judge r 3. consensus → implement / converge → fresh round
是否需要人介入	❌ 否(自动推进)

🤖 controller status banner

⟦AI:AUTO-LOOP⟧

[loning]

🤖 delete solver r2:选择 structural contract-index split

TL;DR

• 这是什么: issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 convergence round 2 的 delete-framing 输出。
• 结论:不删能力,但建议删除 SKILL.md 的过度承载形态,选择 structural:入口压到 <=750 行 controller 契约索引。
• 下一步:controller 等 r2 另外两个 solver 后派 meta-judge,若 3/3 同意则进入实现。

---

详细说明

我正面选择 structural controller-contract-index split。minimal extract-only split 的 1650-1800 行目标仍让 host 首次加载的 SKILL.md 承载大量 runbook、模板和历史说明,不够符合 CLAUDE.md 的“重型参考拆 REFERENCE.md”规则。delete framing 下可删的不是 skill 能力,而是 2537 行入口文件同时当入口、runbook、schema、模板库和复盘档案的形态。

决策点	选择	边界
SKILL.md 预算	<=750 行	只留 frontmatter、host 配置摘要、controller 硬不变量、per-wakeup skeleton、Phase 0-9 contract rows、hard rules、文件索引
REFERENCE.md 承载	runbook/reference	移入 phase 细节、daemon 命令、status/escalation/consensus 模板、WorkUnit/state schema、batching、recovery、历史说明
测试	source contract guards	frontmatter、行数预算、anchor resolve、禁止 @REFERENCE.md/绝对路径、边界内容在正确文件
manifest / 规则	不改	不改 manifest、frontmatter、philosophy、CLAUDE.md、SPEC、Tier

配套测试建议是先写失败测试再改正文:新增 test_skill_entrypoint_contract.py,检查 SKILL.md <=750、frontmatter 只有 name/description 且 description 以 Use when 开头、所有 REFERENCE.md#anchor 可解析、入口保留 sentinel / GitHub state / pure orchestration / Phase 0-9 / label / marker 等硬不变量,同时确认完整 banner 模板、state schema JSON、concurrency shell snippet、label bootstrap loop、recovery playbook 已移入 REFERENCE.md。

---

📎 完整 codex 原始输出(存档备查)

---

solver: delete
issue: 12
cluster: skill-md-controller-split
verdict: propose

Classification

d) Genuinely needed but over-built. The load-bearing feature is the codex-refactor-loop skill entrypoint, not the 2537-line body currently acting as entrypoint, runbook, schema index, template library, and postmortem archive at once. Deleting issue 12, SKILL.md, or REFERENCE.md is unsafe; deleting the over-built shape inside SKILL.md is safe if the controller contract remains in the entrypoint and the detailed material moves to the existing REFERENCE.md.

Recommended action (English)

Choose the structural controller-contract-index split, not the minimal extract-only split. The minimal target of 1650-1800 lines leaves too much runbook and template material in the host-discovered entrypoint and does not really satisfy the repository rule that heavy reference belongs in REFERENCE.md. The right deletion-framed move is to collapse SKILL.md to the existing essential abstraction: a discoverable controller contract plus phase index, with a hard acceptance budget of <=750 lines. Move phase runbooks, command snippets, schemas, templates, detailed examples, recovery playbooks, and historical notes to REFERENCE.md under stable relative anchors. No manifest, frontmatter, philosophy, CLAUDE.md, SPEC, or Tier changes are needed.

Recommended action (中文)

选择 structural controller-contract-index split,不要选 minimal extract-only split。minimal 的 1650-1800 行目标仍把大量 runbook 和模板留在 host 首次发现的入口文件里,没有真正落实“重型参考拆 REFERENCE.md”这条仓库规则。delete framing 下的正确做法是删除 SKILL.md 的过度承载形态,保留它已有且必要的抽象:可发现的 controller 契约 + phase 索引,验收预算为 <=750 行。Phase runbook、命令片段、schema、模板、详细示例、恢复手册、历史说明全部移到 REFERENCE.md 的稳定相对 anchor。无需修改 manifest、frontmatter、philosophy、CLAUDE.md、SPEC 或 Tier 边界。

Concrete plan (if propose)

• Files to delete: none.
• Caller migrations: none. .codex-plugin/plugin.json, .cursor-plugin/plugin.json, Gemini, Claude plugin metadata, and README discovery all continue to point at skills/ and the same skills/codex-refactor-loop/SKILL.md.
• Tests to delete: none.
• LOC delta: SKILL.md about -1780 to -1880 lines; REFERENCE.md about +1650 to +1800 lines; source tests about +120 to +220 lines; net repo delta about -110 to +140 depending on how much duplicated prose is collapsed rather than moved verbatim.
• Philosophy/CLAUDE.md/SPEC/Tier changes (if any): none. Existing CLAUDE.md already says 重型参考拆 REFERENCE.md;脚本放 scripts/;prompt 模板放 prompts/; this plan enforces that rule without changing runtime protocol or Tier boundaries.
• Tracking issue (if defer): none. The prompt forbids defer, and deletion analysis shows the split should happen now.

Exact keep/move boundary

Keep in SKILL.md (controller contract/index, <=750 lines)

• Frontmatter: keep only name and description; description remains a trigger sentence starting with Use when and stays <=1024 chars.
• Host 配置: keep the compact variable contract table and required host.env injection invariant; move detailed startup examples.
• Host 运行编排: keep daemon inventory, singleton requirement, wake-source invariant, ScheduleWakeup registration invariant, EXIT=0 completion rule, GH_REPO_SLUG warning, and test cadence as short bullets.
• GitHub 是系统状态唯一显示面: keep the canonical state-surface rule, mandatory reflect events, bot/sentinel exclusion rule, no-gap policy, no controller self-escalation rule, and peek-after-spawn/merge/banner rule.
• Controller = pure orchestration: keep the non-negotiable controller/worker boundary and default worker = codex CLI invariant.
• Quick start: keep a first-wakeup skeleton only, with links to reference anchors for long command bodies.
• AI 内容标识符: keep sentinel literal, final-independent-line rule, and pre-post self-check; move examples and explanatory rationale.
• 状态源: keep per-wakeup sweep checklist and source-of-truth priority summary; move state schema/debug details.
• Phase 0-9: keep one compact contract entry per phase with trigger, controller action, must not, outputs/markers, and REFERENCE.md#anchor.
• Loop control: keep infinite-loop rule, floor responsibility summary, stop conditions, wakeup cadence, and remote-sync obligation.
• Status banner: keep trigger list and required final markers; move full banner bodies.
• Meta-layer escalation, CI 监控即时推进, Codex 进展实时上报, Label 系统, Codex 调用方式: keep only mandatory routing rules, canonical label names, command surfaces, and anti-footgun summaries.
• Hard rules, 工作语言规则, Files: keep concise policy and file index; REFERENCE.md entry becomes a detailed anchor list.

Move to REFERENCE.md (runbook/reference material)

• Full daemon startup nohup bash -c examples, singleton repair commands, and detailed monitor operations.
• Detailed anti-pattern narratives and rationale-heavy examples, including the same-machine multi-loop overcount story.
• Full Phase 0 bootstrap JSON/state examples and idempotent setup shell snippets.
• Phase 1 audit validation details, stale-worktree cleanup script bodies, design-issue body examples.
• Phase 2/3 implement/verify dispatch details that are better represented as runbook rows and prompt references.
• Phase 4 single/stacked PR procedures, stack-depth examples, merge command recipes, and post-merge local CI detail.
• Phase 5 remote CI polling commands and failure triage runbook.
• Phase 6 dev-sync daemon procedure, divergence computation commands, cadence rationale, and state tracking detail.
• Phase 7 external issue intake details, triage monitor script body, auto-discovery monitor algorithm, and manual override examples.
• Phase 8 reviewer role dispatch template, consensus/fix-retry algorithm details, full GitHub traceability table, state tracking, idempotency, and "why three angles" rationale.
• Phase 9 solver dispatch template, reflector/wakeup/stuck-label detailed procedures, maintainer-reset runbook, full consensus card body, traceability table, anti-spiral rationale, and operator policy detail.
• Concurrency floor rationale, fill-priority table, shell snippets, duplicate anti-pattern list, and historical lessons currently around SKILL.md:1950-2018.
• Full status banner and escalation banner Markdown templates currently around SKILL.md:2066-2198.
• Label bootstrap shell loops and label transition helper code.
• Full WorkUnitV1/state schema, batching heuristics, and recovery playbook, preserving and expanding the existing REFERENCE.md sections.
• Historical bilingual migration notes and removed/deprecated writer-codex tombstone notes.

Tests to add

• Add skills/codex-refactor-loop/scripts/test_skill_entrypoint_contract.py.
• Test 1: frontmatter has exactly name and description; description starts with Use when; frontmatter text <=1024 chars.
• Test 2: SKILL.md line count <=750, contains required contract headings, and still contains canonical invariants: GitHub state surface, pure orchestration, sentinel, codex CLI worker, Phase 0-9, label names, SOLVER_DONE, META_JUDGE_DONE.
• Test 3: every REFERENCE.md#... link in SKILL.md resolves to a heading anchor in REFERENCE.md; no @REFERENCE.md, /Users/, or host-specific .claude/skills/... link is introduced in new split text.
• Test 4: bulky boundary markers are absent from SKILL.md and present in REFERENCE.md: full status banner body, escalation ASCII problem graph, Phase 9 consensus card template, state schema JSON, concurrency floor shell snippet, label creation shell loops, and recovery playbook.
• Test 5: existing WorkUnitV1 and concurrency fixed-point tests continue to pass after moved text is read from combined SKILL.md + REFERENCE.md where appropriate.
• TDD order for implementation: first add the split-boundary tests and run them against the current repo to show failure; then edit SKILL.md/REFERENCE.md; then rerun the full skill script test suite.

Reverse-evidence (why this is safe to delete/collapse)

• No public API breaks: discovery remains the same installed skill name and same skills/codex-refactor-loop/SKILL.md path.
• No external repo dependency on removed code: no file deletion or manifest path change is proposed.
• Tests covering the path are load-bearing and should be preserved, not deleted; existing tests already read both SKILL.md and REFERENCE.md.
• Current line distribution proves over-build in the entrypoint: SKILL.md is 2537 lines while REFERENCE.md is 355 lines; the largest blocks are Phase 7/8/9, Phase 4/6, loop control, and banner/template sections.
• Issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 and self-audit [refactor-design] cluster-002: 共识引擎仍被重构外壳锁住(通用化脊柱) #1 identify the same problem: the entrypoint carries reference-manual weight and should be split into short controller contract plus phase index.
• The existing repository rule already establishes the destination abstraction: heavy reference belongs in REFERENCE.md; no new runtime abstraction is needed.

Risks

• If implementers move mandatory obligations without preserving short normative summaries in SKILL.md, first-wakeup controllers may under-bootstrap.
• If anchors are unstable, old comments and future solver prompts may lose clear pointers; anchor-resolution tests mitigate this.
• If the <=750-line budget is met by deleting semantics instead of moving them, controller behavior could regress; boundary tests must check required invariants remain in SKILL.md and detailed material exists in REFERENCE.md.
• If future maintainers treat REFERENCE.md as eagerly loaded, the token benefit shrinks; SKILL should explicitly say to load only phase-local anchors.

Escalation triggers (if any)

• none

Reasoning trace (internal — for meta-judge)

• Why I claim this can be deleted/collapsed: the code path is not dead, but the over-built entrypoint shape is deletable. The simpler existing abstraction is SKILL.md as controller contract/index plus REFERENCE.md as runbook/reference.
• What I checked to verify safety: r1 minimal/structural/delete outputs; issue [refactor-design] SKILL.md 过重:拆分 controller 契约 vs REFERENCE(self-audit #1) #12 body/comments; audit-iter-3.md; CLAUDE.md; self-audit [refactor-design] cluster-002: 共识引擎仍被重构外壳锁住(通用化脊柱) #1; current SKILL.md/REFERENCE.md line counts and headings; manifest/discovery references; existing fixed-point tests; git history showing the skill and reference were imported together and then accumulated controller-critical detail.
• What I cannot decide alone: exact final wording of each retained controller row. The split depth is decided here: structural <=750-line SKILL.md, with phase details moved behind tested REFERENCE.md anchors.

SOLVER_DONE:delete:propose:collapse over-built SKILL entrypoint into structural <=750-line controller contract index and move runbooks/templates/schemas/history to REFERENCE.md

⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧