design: 哲学/SKILL 文档去版本后缀(V1/V2/schema_version)

[loning]

背景

CLAUDE.md 已加新不动点:`哲学文档不写版本后缀`(V1/V2/`schema_version: 1` 等)。SKILL.md/REFERENCE.md 仍有 ~48 个 versioned identifier site:`WorkUnitV1`、`IntegrationSyncDaemonV1`、`IntegrationSyncRequestV1`、`ManualIssueTriageDecisionV1`、`SkillDegradationWatchV1`、`WorktreeLifecycleProjectionV1`、`schema_version: 1`、`work_unit_schema_version: 1` 等。

CLAUDE.md 哲学段已就地替换 2 处 `IntegrationSyncDaemonV1` 为功能描述 "integration-branch sync daemon"。

目标

把 SKILL.md / REFERENCE.md / scripts 注释 / 测试名称中的 V1/V2 后缀替换为职责导向的命名,保留 schema 内部演化坐标(`state.json` 字段 `schema_version` / `work_unit_schema_version` 在代码里继续用,只从哲学文本撤出)。

替换映射(候选,Phase 9 收敛)

• `WorkUnitV1` → `WorkUnit` 或 `work-unit container`
• `IntegrationSyncDaemonV1` → `integration-branch sync daemon`
• `IntegrationSyncRequestV1` → `integration-sync request artifact`
• `ManualIssueTriageDecisionV1` → `manual-issue triage decision artifact`
• `SkillDegradationWatchV1` → `skill-degradation watch`
• `WorktreeLifecycleProjectionV1` → `worktree-lifecycle projection`(若实现)
• `schema_version: 1` 在哲学/SKILL 文档段 → 删除该字面提及,改 "v1 stable" 等抽象描述;`state.json` 字段保留

不可动

• `state.json` 实际字段名 `schema_version`/`work_unit_schema_version`(代码内,不在哲学层)
• `.version-bump.json` 映射的 package/manifest release semver(发布坐标,不是 design identifier)
• marker 词表本身(`SOLVER_DONE`/`META_JUDGE_DONE` 等 — 已 language-agnostic)
• sentinel `⟦AI:AUTO-LOOP⟧`

验证标准

• `grep -E 'V1|V2|schema_version' skills/codex-refactor-loop/SKILL.md skills/codex-refactor-loop/REFERENCE.md` 在哲学/契约段返回零(实际字段定义保留)
• Source-regression test:禁止未来在 SKILL/REFERENCE 哲学段重新出现 `*V1`/`*V2` identifier(代码内 schema 字段可豁免)
• 共识引擎语义零变更
• behavior test 全绿

Phase 9 framing

• minimal: 仅替换 SKILL.md/REFERENCE.md 哲学段的字面,代码 identifier 暂保留(逐 PR 跟进)
• structural: 哲学段 + 代码 identifier 同步 rename,加 source-regression 锁哲学段
• delete: 删整段 versioned exception 文本,改抽象描述 + indirect 指向 `runs/.../judge.md` artifact

⟦AI:AUTO-LOOP⟧

[loning]

🤖 minimal solver: issue 107 建议文档/注释层去版本后缀

TL;DR

• 这是什么: minimal solver 独立核对 issue 107 后，确认 SKILL.md / REFERENCE.md 的版本后缀违规真实存在。
• 结论: 建议只改文档契约、脚本注释和 source-regression 断言；保留真实 JSON schema 字段、artifact schema 字符串和 Python 类型名。
• 下一步: controller 可让 meta-judge 汇总 3 个 solver 输出，若采纳本 framing 再派实现 worker。

---

详细说明

最小边界是把哲学/契约层的 WorkUnitV1、IntegrationSyncDaemonV1、IntegrationSyncRequestV1、ManualIssueTriageDecisionV1、SkillDegradationWatchV1 等改成职责名；schema_version / work_unit_schema_version 只保留在 .refactor-loop/state.json 实际字段说明和 JSON 示例里。这样不会触发 state migration、artifact 兼容迁移或 dataclass rename。

不建议把 IntegrationSyncRequestV1 / ManualIssueTriageDecisionV1 的 Python 类名和 artifact schema 值同步改掉；那会从文档清理变成 runtime protocol migration，成本和回滚风险都明显变大。

---

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

---
solver: minimal
issue: 107
cluster: issue-107
verdict: propose
---

## Recommended framing
违规真实存在：`skills/codex-refactor-loop/SKILL.md` 与 `REFERENCE.md` 仍有 48 处 `V1/V2/schema_version` 命中，其中多处位于 controller contract、named runtime exception、phase index、WorkUnit contract 等哲学/契约叙述层。最小可行边界是不做 runtime protocol rename，只把 SKILL/REFERENCE 的职责叙述、脚本注释、测试名称/断言从版本后缀改为职责名，并新增 source-regression 防止哲学/契约段重新出现版本化 identifier；真实 state 字段、JSON 示例、artifact `schema` 字符串和 Python dataclass 名保持不变。

## Concrete plan
- Files: `skills/codex-refactor-loop/SKILL.md`：把 contract/phase/named exception prose 中的 `WorkUnitV1` 改为 `WorkUnit` / `work-unit container`，`IntegrationSyncDaemonV1` 改为 `integration-branch sync daemon`，`IntegrationSyncRequestV1` 改为 `integration-sync request artifact`，`ManualIssueTriageDecisionV1` 改为 `manual-issue triage decision artifact`，`SkillDegradationWatchV1` 改为 `skill-degradation watch`；删除 `WorkUnitV2` 这类版本化反例字面，改成 “migrated work-unit replacement / public marker alias”等职责描述。
- Files: `skills/codex-refactor-loop/REFERENCE.md`：同样替换 prose；把 `## WorkUnitV1 contract` / `#workunitv1-contract` 改为 `## WorkUnit contract` / `#workunit-contract` 并更新内部链接；保留 State schema 段 JSON 示例里的 `schema_version` 与 `work_unit_schema_version`。
- Files: `skills/codex-refactor-loop/scripts/dev_sync_daemon.py`, `integration_sync_requests.py`, `triage_decisions.py`, `apply_integration_sync_request.py`, `apply_triage_decision.py`, `controller_lib.sh`, `check_skill_degradation.py`：只改 docstring/comment/log prose 中的版本化称呼；不改 class name、type annotation、artifact `schema` 值、validation message。
- Files: `skills/codex-refactor-loop/scripts/test_skill_entrypoint_contract.py`, `test_ensure_project_rules_fixed_points.py`, `test_dev_sync_daemon_state_machine.py`, `test_check_skill_degradation.py`：同步 source-regression 断言、测试类/测试名的职责命名；fixture 中真实 `schema` 值保持原样。
- LOC delta: ~+45 / -45；大多数是同 行文本替换，新增约 30-40 行 source-regression helper/allowlist，删除或替换约 30-40 行旧字面断言。
- Tests to add/modify: 修改 `test_ensure_project_rules_fixed_points.py`，新增一个 source-regression 检查：扫描 `SKILL.md` 全文和 `REFERENCE.md` 的哲学/契约 prose，禁止 `\b[A-Za-z][A-Za-z0-9]*V[12]\b`；对 `schema_version` / `work_unit_schema_version` 只允许在 State schema 字段定义、JSON 示例、runtime schema 兼容说明中出现。修改 `test_skill_entrypoint_contract.py` 的 heavy marker 期望；修改 `test_dev_sync_daemon_state_machine.py` 与 `test_check_skill_degradation.py` 的标题/marker 断言。行为测试不新增，跑现有 `python3 -m unittest discover -s skills/codex-refactor-loop/scripts -p 'test_*.py'` 即可。
- Philosophy/PROJECT_RULES/SPEC/Tier change (if any): none。`CLAUDE.md` 已有 “schema/identifier 版本号属于代码内部演化坐标，不进哲学文档” 与 release semver 例外；本计划只是把这个规则落到 codex-refactor-loop 文档和 source-regression。无需改 Tier 边界，也无需 GPG ratification。
- Migration path: no migration needed；runtime schema、state 文件、artifact JSON、public markers、labels、branch names、Python imports 全部保持兼容。

## Risks
- 文档名与 Python 类型名会暂时不同，例如文档写 “integration-sync request artifact”，代码类仍叫 `IntegrationSyncRequestV1`；这是刻意保留的 runtime compatibility trade-off。
- 若 source-regression 的 allowlist 写得过宽，未来可能把真正哲学段里的 `schema_version` 放过去；实现时应按 section/代码块范围窄豁免，而不是全文件豁免。
- 旧 anchor `#workunitv1-contract` 若有外部深链会失效；本仓库内链接可一次性更新。若担心外部深链，可保留一个无正文兼容 anchor，但 minimal framing 不建议新增兼容壳。

## Escalation triggers (if any)
- none

## Reasoning trace (internal — short, for meta-judge)
- Why this is the minimum: 证据命中集中在哲学/契约 prose、注释和 source-regression 断言；改这些即可满足新不动点，同时不碰 state/artifact runtime 协议。
- What I considered but rejected: 同步 rename Python class、artifact `schema` 值、state schema 字段；这会引入兼容迁移、双读/双写或 schema bump，超过 issue 的最小修复边界。
- What I cannot decide alone: 是否要为外部 deep link 保留旧 `#workunitv1-contract` anchor；我倾向不保留，因为仓库规则偏向删除历史兼容壳。

SOLVER_DONE:minimal:propose:文档/注释/测试文字去版本后缀，runtime schema 与类型名保持兼容

⟦AI:AUTO-LOOP⟧

[loning]

🤖 delete solver:建议删文档层 V1 词汇,不动 runtime schema

TL;DR

• 这是什么:issue 107 的 delete-bias 独立 solver 结论。
• 结论:不删除 integration sync / triage / state schema 功能;删除/折叠 SKILL/REFERENCE 里把 V1 当哲学词的写法。
• 下一步:meta-judge 可把它作为 deletion/collapse 方案输入,implementation 只应动文档词汇和 source-regression,不要改 wire schema。

---

详细说明

反向调用链显示这些能力是真实 load-bearing: IntegrationSyncRequestV1 和 ManualIssueTriageDecisionV1 是 JSON artifact 的 schema 值,apply helper 会严格校验;schema_version / work_unit_schema_version 是 state 文件实际字段。因此 delete 方案不是删功能,而是删错误抽象:不要让哲学/契约段继续把 V1/V2/schema_version 当产品词汇。

建议把 SKILL.md / REFERENCE.md / prompt / 注释 / source-regression 中的架构面命名折叠为职责名:work-unit container、integration-branch sync daemon、integration-sync request artifact、manual-issue triage decision artifact、skill-degradation watch。运行时 schema 字符串、state 字段、marker、label、branch 名保持兼容。另一个发现是 .refactor-loop/runs/audit-iter-.md 和 live issue 107 不一致:审计文件说 .claude/skills symlink,但 GitHub issue 107 实际是 versioned identifier 清理;我按 live issue 和 repo 证据判断。

---

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

---

solver: delete
issue: 107
cluster: issue-107
verdict: propose

Classification

d) Genuinely needed but over-built — 能力本身真实需要,但文档/测试把 wire/schema 演化坐标提升成了哲学词汇和契约标题。

Recommended action

建议保留现有 runtime schema / marker / state 字段不动,删除 SKILL.md / REFERENCE.md / prompt / 脚本注释 / source-regression test 里把 WorkUnitV1、IntegrationSyncDaemonV1、IntegrationSyncRequestV1、ManualIssueTriageDecisionV1、SkillDegradationWatchV1 当架构哲学词或 heading 的写法,统一折叠成职责导向名:work-unit container、integration-branch sync daemon、integration-sync request artifact、manual-issue triage decision artifact、skill-degradation watch。schema_version / work_unit_schema_version 只保留在 JSON 示例、runtime validation、legacy state 读取说明里,不再作为哲学段必须记忆的口号。

Concrete plan (if propose)

• Files to delete: none.
• Caller migrations:
  • skills/codex-refactor-loop/SKILL.md contract/index/Phase guardrails/named exception headings -> role names without V1; reference anchors renamed from #workunitv1-contract to #work-unit-contract.
  • skills/codex-refactor-loop/REFERENCE.md philosophy/runbook prose -> role names without V1; wire schema strings remain only in JSON examples, Python schema validators, and explicit "wire schema is unchanged" notes.
  • skills/codex-refactor-loop/prompts/triage-external-issue.md -> say "manual-issue triage decision JSON artifact"; keep schema: "ManualIssueTriageDecisionV1" only inside the emitted JSON block contract if compatibility requires it.
  • skills/codex-refactor-loop/scripts/dev_sync_daemon.py, check_skill_degradation.py, controller_lib.sh, apply_*, *_decisions.py comments/docstrings -> remove architecture-facing V1 phrasing; keep class names and schema string constants unless implementation solvers choose a full compatibility migration.
  • skills/codex-refactor-loop/scripts/test_ensure_project_rules_fixed_points.py, test_dev_sync_daemon_state_machine.py, test_check_skill_degradation.py, test_skill_entrypoint_contract.py -> delete assertions that require V1 tokens in SKILL/REFERENCE prose; replace with source-regression assertions that philosophy/contract prose does not contain \b[A-Za-z][A-Za-z0-9_]*V[12]\b outside allowlisted code/schema snippets.
• Tests to delete: no test file deletion; delete old positive source-regression assertions such as "SKILL contains ## Named runtime exception — IntegrationSyncDaemonV1(per #65)", "REFERENCE split on Daemon 工作流由 IntegrationSyncDaemonV1`...", "WorkUnitV1 contract markers are present", and "SkillDegradationWatchV1 named exception is present"; replace them with equivalent responsibility-name assertions.
• LOC delta: about -25 to -60 net, mostly from deleting duplicated versioned prose and old positive marker lists; may be near-zero if implementer chooses verbose compatibility notes.
• Philosophy/CLAUDE.md/SPEC/Tier changes (if any): none. CLAUDE.md already contains "哲学文档不写版本后缀"; this plan is enforcement, not a Tier/SPEC boundary change.

Reverse-evidence (why this is safe to delete)

• No public API breaks: runtime schema strings are preserved where validated (integration_sync_requests.py requires schema == "IntegrationSyncRequestV1"; triage_decisions.py requires schema == "ManualIssueTriageDecisionV1"), and state fields schema_version / work_unit_schema_version remain in code/examples where they are actual wire fields.
• No external repo dependency on the code is touched: the plan does not rename classes, JSON schema values, markers, labels, branches, or state containers.
• Tests covering the path are themselves not load-bearing when they only assert old vocabulary appears in prose; behavior tests for apply helpers, daemon request emission, triage decision validation, and degradation checking remain load-bearing.
• Git history shows these names came from recent safety refactors (design: codex max_output_tokens + cluster dedup + log rotation + maintainer-directive 扩用边界 #70, goal: skills 规范化 + 防退化(脚本检测 SKILL.md / scripts / prompts 漂移) #66, [refactor-design] codex 直接操作 git/gh 减少 controller 中转(维护者实证) #53/design: auto-refact-dev → develop 自动 rollup 流程(Phase 9 design-solving) #65) as compatibility/schema boundaries, not as product philosophy. The value chain is "worker/daemon emits artifact -> controller apply helper validates schema -> GitHub/git lifecycle stays controller-owned"; the V1 suffix is not what provides safety.
• .refactor-loop/runs/audit-iter-.md is stale/mismatched for issue 107: its cluster-004 discusses .claude/skills, while live gh issue view 107 discusses versioned identifiers. The deletion plan follows the live issue and verified repo evidence.

Risks

• If some downstream installed copy parses SKILL.md headings literally, renaming headings could break that downstream documentation scraper. I found no in-repo runtime consumer of these headings except source-regression tests.
• If implementer removes schema strings from JSON contracts instead of only prose, apply_integration_sync_request.py / apply_triage_decision.py compatibility will break.
• If the allowlist for schema_version is too broad, the new source-regression test may fail to catch future philosophy leakage; if too narrow, it may block legitimate JSON examples.
• The audit input mismatch means a controller may have attached the wrong audit cluster to issue 107; meta-judge should prefer live GitHub issue evidence.

Escalation triggers (if any)

• none

Reasoning trace (internal — for meta-judge)

• Why I claim this can be deleted: The repo already has the governing invariant in CLAUDE.md: philosophy docs do not carry V1/V2/schema_version design identifiers. rg found the violation concentrated in SKILL/REFERENCE prose, prompt wording, comments/docstrings, and source-regression tests that positively require old names. The runtime capability value chain does not depend on philosophical V1 wording.
• What I checked to verify safety: gh issue view 107 --comments; .refactor-loop/runs/audit-iter-.md; CLAUDE/AGENTS deletion-first clause; rg over SKILL/REFERENCE/prompts/scripts for WorkUnitV1|IntegrationSyncDaemonV1|IntegrationSyncRequestV1|ManualIssueTriageDecisionV1|SkillDegradationWatchV1|schema_version|work_unit_schema_version; source snippets for integration_sync_requests.py, triage_decisions.py, dev_sync_daemon.py; source-regression assertions in test_ensure_project_rules_fixed_points.py; git history for IntegrationSyncDaemonV1, IntegrationSyncRequestV1, ManualIssueTriageDecisionV1, and SkillDegradationWatchV1.
• What I cannot decide alone: Whether implementation should also rename Python class identifiers after adding backward-compatible aliases. Delete-side recommendation is no: preserve runtime identifiers and delete only the philosophical/documentation leak.

⟦AI:AUTO-LOOP⟧
SOLVER_DONE:delete:propose:删除/折叠哲学与契约文档中的 V1/V2/schema_version 词汇泄漏,保留 runtime schema 字符串和状态字段兼容

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Phase 9 structural solver: 去版本后缀采用职责名 + wire schema 隔离

TL;DR

• 这是什么: issue 107 的 structural solver 方案。
• 结论: propose,把文档/类名/测试名改职责名,仅保留 JSON wire schema literal 作为兼容坐标。
• 下一步: meta-judge 对 3 个 solver 输出收敛;无需 maintainer 额外动作。

---

详细说明

建议把 WorkUnitV1、IntegrationSyncDaemonV1 这类人读到的架构名替换成职责名,例如 work-unit contract、integration-branch sync daemon、integration-sync request artifact。"schema": "IntegrationSyncRequestV1" 这类已发布 artifact 的 wire schema 值继续保留,但只能出现在 validator 常量和 JSON fixture/schema 示例里。

成本估计:约 15 个文件,~+260 / -230 LOC,新增 1 个 source-regression 测试文件和 4 个兼容行为断言;运行时 0 新 actor/daemon hop,CI 扫描 <1s。

---

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

---

solver: structural
issue: 107
cluster: issue-107
verdict: propose

PROJECT_RULES clause violated (quoted verbatim)

• 哲学文档不写版本后缀:V1/V2/schema_version: 1 之类的 schema/identifier 版本号属于代码内部演化坐标,不进哲学文档(CLAUDE.md/README.md/SKILL.md 哲学段)。哲学描述不变量与边界,不绑定当前版本号;一旦哲学文本要随 schema 改版而改,说明版本号泄露到了不该泄露的层。Release semver(.version-bump.json 映射的 package/manifest 版本)是另一回事——那是发布坐标,不是设计 identifier。

Supporting rule:

• 变更必须可验证:行为约束必须落到机械验证手段(behavior test / source-regression test / 段落 lint);仅靠"agent 应该记得"承载的约束视为未落地。

Recommended framing

把“职责名”和“wire/schema 演化坐标”拆成两个边界:SKILL.md / REFERENCE.md 的 contract、runtime exception、phase guardrail、anchor、actor 名称只写职责名,例如 work-unit contract、integration-branch sync daemon、integration-sync request artifact、manual-issue triage decision artifact、skill-degradation watch;代码中的 Python 类名和测试名同步改成职责名。JSON wire schema literal 作为内部兼容坐标保留在 validator 常量和 fixture 里,例如 "IntegrationSyncRequestV1" 仍可作为已发布 artifact schema 值,但不得出现在哲学/契约文案、类名、heading 或注释叙事中。这样不是给 V1 开例外,而是把版本号关进唯一合理的 schema 层。

Concrete plan

• New abstractions (if any): none as runtime abstraction. Add one source-regression policy surface named VersionedIdentifierDocBoundary only as a test/check concept: it scans docs/comments/identifiers and has no actor, no daemon, no lifecycle authority.
• Existing repo primitives used:
  • SKILL.md local contract + REFERENCE.md lazy anchors for contract wording.
  • Existing JSON artifact validators in integration_sync_requests.py and triage_decisions.py for wire schema compatibility.
  • Existing behavior/source-regression test pattern under skills/codex-refactor-loop/scripts/test_*.py.
  • Existing check_skill_degradation.py --static CI surface can be extended to include the doc-boundary drift check, or the new test can stand alone under contract-tests. No IAsyncEnumerable, Channel, proto, actor inbox, or projection-pipeline primitive exists in this repo.
• Files:
  • CLAUDE.md: narrow wording change to include REFERENCE/SKILL contract/runbook sections and define the allowlist for wire/schema examples.
  • skills/codex-refactor-loop/SKILL.md: replace human-facing WorkUnitV1, IntegrationSyncDaemonV1, IntegrationSyncRequestV1, ManualIssueTriageDecisionV1, SkillDegradationWatchV1, WorkUnitV2, and schema_version: 1 mentions with responsibility names or “existing state schema fields”.
  • skills/codex-refactor-loop/REFERENCE.md: rename anchors/headings from workunitv1-contract to workunit-contract, rewrite contract prose to responsibility names, keep actual state JSON examples under ## State schema.
  • skills/codex-refactor-loop/scripts/dev_sync_daemon.py: rename IntegrationSyncDaemonV1 class to IntegrationSyncDaemon; rewrite docstrings/comments/log text to “integration-sync request artifact”; keep emitted JSON schema unchanged through request object.
  • skills/codex-refactor-loop/scripts/integration_sync_requests.py: rename dataclass IntegrationSyncRequestV1 to IntegrationSyncRequest; introduce INTEGRATION_SYNC_REQUEST_SCHEMA = "IntegrationSyncRequestV1" as the only wire literal; keep validation behavior identical.
  • skills/codex-refactor-loop/scripts/triage_decisions.py: rename dataclass ManualIssueTriageDecisionV1 to ManualIssueTriageDecision; introduce MANUAL_ISSUE_TRIAGE_DECISION_SCHEMA = "ManualIssueTriageDecisionV1" as the only wire literal; keep validation behavior identical.
  • skills/codex-refactor-loop/scripts/apply_integration_sync_request.py, apply_triage_decision.py, controller_lib.sh: update docstrings/comments/import type names only.
  • skills/codex-refactor-loop/scripts/check_skill_degradation.py: update required marker names and add/consume the versioned-identifier doc-boundary check.
  • Tests to update: test_dev_sync_daemon_state_machine.py, test_apply_artifact_helpers.py, test_check_skill_degradation.py, test_ensure_project_rules_fixed_points.py, test_skill_entrypoint_contract.py, test_phase9_router_daemon.py fixture wording where it forbids WorkUnitV2.
  • New test: skills/codex-refactor-loop/scripts/test_versioned_identifier_doc_boundary.py.
• LOC delta: ~+260 / -230 across ~15 touched files, including one new ~90 LOC source-regression test. Net change ~+30 LOC.
• Tests to add:
  • test_versioned_identifier_doc_boundary.py::test_skill_and_reference_contract_sections_do_not_use_versioned_identifiers: parses SKILL/REFERENCE by headings and fails on \b[A-Za-z][A-Za-z0-9]*V[0-9]+\b, schema_version: 1, and work_unit_schema_version: 1 outside allowlisted schema-example sections.
  • test_versioned_identifier_doc_boundary.py::test_source_identifiers_and_comments_use_responsibility_names: scans Python/shell comments, docstrings, class names, and test names; allows only explicit wire-schema constant assignments and JSON fixture "schema" values.
  • test_integration_sync_requests.py or existing test_apply_artifact_helpers.py: assert old artifact JSON with "schema": "IntegrationSyncRequestV1" still validates and emits identical controller-owned request semantics.
  • Existing triage artifact test: assert "schema": "ManualIssueTriageDecisionV1" still validates and lifecycle fields remain controller / false.
  • Existing static check test: assert check_skill_degradation.py --static fails when a human-facing SKILL/REFERENCE contract paragraph reintroduces FooV1.
• proto changes (if any): none.
• Philosophy/PROJECT_RULES/SPEC/Tier changes (if any):
  • File/clause: CLAUDE.md / 设计哲学(跨 skill 不动点) / 哲学文档不写版本后缀.
  • Current invariant: version suffixes do not enter CLAUDE.md/README.md/SKILL.md philosophy paragraphs, but REFERENCE.md contract/runbook surfaces and source comments are ambiguous.
  • Proposed invariant text:
    **哲学/契约文档不写版本后缀**:\V1`/`V2`/`schema_version: 1` 之类的 schema/identifier 版本号属于代码内部演化坐标,不进 `CLAUDE.md`/`README.md`/`SKILL.md`/`REFERENCE.md` 的哲学、contract、runtime exception、phase guardrail、runbook heading/anchor 文案,也不作为 actor/class/test 名称。文档描述职责名与边界;版本坐标只允许出现在明确的 wire/schema 字段定义、JSON schema 示例、validator 常量、兼容迁移说明中。Release semver(...) 是发布坐标,不是 design identifier。`
  • Why worth trusted-base cost: this closes the ambiguity that caused issue 107. Without it, agents can argue REFERENCE.md or source comments are not “philosophy paragraphs” and reintroduce versioned product vocabulary.
  • Why deep consensus should hold: no Tier I/II ratification, no GPG/signing, no lifecycle authority, no behavior change; it tightens naming policy while preserving existing wire schema compatibility.
• Runtime cost: 0 extra controller wakeup hops, 0 extra actor/daemon hops, 0 additional runtime allocations in loop execution. Validator constants replace duplicated string literals; memory delta <1 KB/module import. CI/source-regression scan cost: ~20-40 files, estimated <150 ms locally and <1 s in CI.

Risks

• Structural rename touches more files than a docs-only replacement; stale imports or test fixtures can break even though runtime behavior should not change.
• The checker can become overbroad if it bans wire schema literals everywhere. Keep the allowlist narrow: only constant assignments, JSON "schema" fixture values, and fenced state schema examples.
• Renaming workunitv1-contract anchors can break internal links if any are missed. Update all Markdown links in the same PR and avoid adding compatibility duplicate anchors, because shadow anchors would keep the old vocabulary alive.
• Keeping "IntegrationSyncRequestV1" and "ManualIssueTriageDecisionV1" as wire literals may look like partial cleanup. The plan must state repeatedly that those are schema payload values, not architecture names.

Escalation triggers (if any)

• none

Reasoning trace (internal — for meta-judge)

• Why this structure beats a documented exception: an exception would preserve two naming systems: philosophy says no versions, runtime docs keep versioned names. Splitting human-facing responsibility names from wire-schema literals makes the boundary mechanically testable.
• Why I picked this abstraction over alternatives: a new actor/envelope/pipeline would be unjustified. The only required new surface is a source-regression boundary check because the violation is vocabulary drift across docs/comments/tests, not runtime flow.
• What I cannot decide alone: whether meta-judge wants the wire schema string values renamed too. My recommendation is no: they are durable artifact compatibility coordinates and renaming them would create migration risk without reducing human-facing conceptual leakage.

SOLVER_DONE:structural:propose:职责命名替代文档版本后缀并隔离保留wire-schema坐标
⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Meta-judge: issue 107 进入 round 2 收敛

TL;DR

• 这是什么:Phase 9 meta-judge 对 issue 107 三个 solver 输出的仲裁。
• 结论:3/3 都 propose,但 framing 不一致;本轮不能 auto-dispatch implement。
• 下一步:controller 重新派 round 2,聚焦 Python 类型名是否 rename、CLAUDE.md 是否收窄这两个边界。

---

详细说明

三位 solver 已经在核心目标上接近:都确认 SKILL.md / REFERENCE.md 等人读契约层的 V1/V2/schema_version 泄漏真实存在,也都保留 runtime wire schema 值和 state 字段兼容。但还没有 3/3 同 framing: minimal/delete 选择文档、prompt、注释和 source-regression 清理,保留 Python class/type 名;structural 选择同步 rename Python class/test 名,并修改 CLAUDE.md invariant。

因此本轮是 convergence,不是 stalled。当前 round=1,未达到 >=3 轮无进展条件。round 2 的问题应窄化为:实现边界选 A) 文档契约清理并保留 Python 类型名,还是 B) 同步 rename 类型名并修改 CLAUDE.md;每个 solver 必须给出唯一边界、文件清单、allowlist 和测试集合。

方案	边界	trade-off
A	清理 SKILL/REFERENCE/prompt/注释/source-regression,保留 Python 类型名	迁移风险最低,但代码 identifier 仍带 V1
B	同步 rename Python class/test identifier,保留 wire schema literal	概念边界最干净,但触碰更多文件和 imports
C	改 wire schema/state 字段	3 个 solver 都未支持,不进入下一轮默认方案

---

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

---
issue: 107
cluster: issue-107
convergence_round: 1
solver_verdicts:
  minimal: propose
  structural: propose
  delete: propose
decision: converge
---

## Decision
本轮不达成 consensus,进入 convergence round 2。三位 solver 都确认 issue 107 是真实违规,也都同意保留 runtime wire schema 值和 state 字段兼容,并把 SKILL/REFERENCE 等人读契约层的 `V1/V2/schema_version` 泄漏改为职责名;但 framing 未 3/3 一致: minimal/delete 明确保留 Python class/type identifier 且不改 `CLAUDE.md`,structural 明确要求同步 rename Python class/test identifier 并收窄 `CLAUDE.md` 规则。因此分歧是命名边界和 trusted-base 文案边界,不是 stall;当前 convergence_round=1,不满足 >=3 轮无进展的 stall 条件。

## If converge
- Convergence question (specific): issue 107 的实现边界应选择 A) 只清理 SKILL/REFERENCE/prompt/注释/source-regression 的人读契约词汇并保留 Python class/type 名,还是 B) 同步 rename Python class/test identifier 并修改 `CLAUDE.md` invariant;请给出唯一推荐边界、确切文件清单、是否需要 `CLAUDE.md` 文案、以及兼容性测试。
- What each solver should address explicitly:
  - 是否把 `IntegrationSyncRequestV1` / `ManualIssueTriageDecisionV1` / `IntegrationSyncDaemonV1` 的 Python class/type/test 名改成无版本职责名;如果改,是否需要 alias 或迁移;如果不改,source-regression 如何避免文档继续把它当架构词。
  - 是否修改 `CLAUDE.md` 的 `哲学文档不写版本后缀` 条款;如果改,给出 exact replacement text;如果不改,说明现有条款如何覆盖 `REFERENCE.md` contract/runbook、prompt、source comments 和 tests。
  - `schema_version` / `work_unit_schema_version` / artifact `"schema": "*V1"` 的 allowlist 精确范围:哪些 section、JSON block、validator constant、fixture 可保留,哪些 prose/heading/comment 必须禁止。
  - 最终文件清单和 LOC 级别是否落在同一实现边界内;避免一边是 ~45 行文案改动,另一边是 ~260/~230 的 class rename。
  - 保留 runtime compatibility 的行为测试和防回归 source-regression 测试各列最小集合。
- Round number this fires: 2

## Round audit trail (links to local artifacts)
- solver-minimal: /Users/auric/consensus-rnd/.refactor-loop/runs/phase9-issue107-r1-minimal.md
- solver-structural: /Users/auric/consensus-rnd/.refactor-loop/runs/phase9-issue107-r1-structural.md
- solver-delete: /Users/auric/consensus-rnd/.refactor-loop/runs/phase9-issue107-r1-delete.md

META_JUDGE_DONE:converge:round-2:实现边界选 A 文档契约清理保留 Python 类型名,还是 B 同步 rename 类型名并修改 CLAUDE.md invariant?
⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

🤖 delete solver r2: 选择 A,不做 Python 类型 rename

TL;DR

• 这是什么: issue 107 round 2 delete solver 对 A/B 边界的收敛回答。
• 结论: 选择 A,删除文档/prompt/注释/测试断言里的版本后缀词汇;保留 Python class/type 名和 wire schema/state 字段。
• 下一步: meta-judge 可用此与 round 2 其他 solver 输出收敛实现边界。

---

详细说明

Delete framing 不支持 B:同步 rename IntegrationSyncRequestV1 / ManualIssueTriageDecisionV1 / IntegrationSyncDaemonV1 的 Python identifier,但仍保留 "schema": "*V1" wire literal,不会删除真实能力链,只会增加 import churn、alias/migration 决策和测试面。

推荐边界是把 SKILL.md / REFERENCE.md / prompt / 注释 / source-regression 中的人读架构词折叠成职责名:work-unit container、integration-branch sync daemon、integration-sync request artifact、manual-issue triage decision artifact、skill-degradation watch。schema_version / work_unit_schema_version 只在 state JSON 示例、validator literal、兼容说明中保留。CLAUDE.md 当前不动;已有条款足够覆盖本 issue 的 SKILL/哲学层泄漏。

---

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

---
solver: delete
issue: 107
cluster: issue-107
verdict: propose
---

## Classification
d) Genuinely needed but over-built — 需要保留 integration sync、triage decision、state schema 这些 runtime 能力,但不需要把 `V1/V2/schema_version` 当成人读架构词、prompt 词或 source-regression 正向断言继续传播。

## Recommended action
选择 A:只删除/折叠 SKILL.md、REFERENCE.md、prompts、脚本注释/docstring、source-regression 断言里的人读版本后缀词汇,保留 Python class/type 名、artifact `"schema": "*V1"` wire literal、`schema_version` / `work_unit_schema_version` state 字段不动。Delete framing 不支持 B,因为 B 只是把 `IntegrationSyncRequestV1` / `ManualIssueTriageDecisionV1` 等 runtime identifier 重命名后再保留同名 wire schema literal,没有删除一条真实能力链,却增加 import churn、alias/migration 决策和测试面。

## Concrete plan (if propose)
- Files to delete: none.
- Caller migrations:
  - `skills/codex-refactor-loop/SKILL.md`: contract table、Phase index、Phase 0/1/6/7/9 guardrail、named runtime exception heading/prose 改职责名;`WorkUnitV1` -> `work-unit container` / `WorkUnit contract`;`IntegrationSyncDaemonV1` -> `integration-branch sync daemon`;`IntegrationSyncRequestV1` -> `integration-sync request artifact`;`ManualIssueTriageDecisionV1` -> `manual-issue triage decision artifact`;`SkillDegradationWatchV1` -> `skill-degradation watch`;`WorkUnitV2` 反例改为 `migrated work-unit replacement`。
  - `skills/codex-refactor-loop/REFERENCE.md`: rename `## WorkUnitV1 contract` / `#workunitv1-contract` to `## WorkUnit contract` / `#work-unit-contract`;runbook/prose 同步职责名;State schema JSON block and explicit compatibility notes may keep `schema_version` and `work_unit_schema_version`.
  - `skills/codex-refactor-loop/prompts/triage-external-issue.md`: prose says `manual-issue triage decision artifact`; only the concrete JSON field line may retain `schema: "ManualIssueTriageDecisionV1"` because workers must emit the existing wire schema.
  - `skills/codex-refactor-loop/scripts/dev_sync_daemon.py`, `apply_integration_sync_request.py`, `apply_triage_decision.py`, `controller_lib.sh`, `check_skill_degradation.py`, `integration_sync_requests.py`, `triage_decisions.py`, `host.env.example`: comments/docstrings/log prose use responsibility names. Do not rename `IntegrationSyncDaemonV1`, `IntegrationSyncRequestV1`, or `ManualIssueTriageDecisionV1` classes/types in this issue.
  - `skills/codex-refactor-loop/scripts/test_ensure_project_rules_fixed_points.py`, `test_skill_entrypoint_contract.py`, `test_dev_sync_daemon_state_machine.py`, `test_check_skill_degradation.py`, `test_phase9_router_daemon.py`: delete positive assertions requiring old prose tokens, replace with responsibility-name assertions and a narrow doc-boundary source-regression check.
- Tests to delete: no test file deletion. Delete obsolete assertion strings such as `## Named runtime exception — IntegrationSyncDaemonV1(per #65)`, `Daemon 工作流由 IntegrationSyncDaemonV1`, `## WorkUnitV1 contract`, `SkillDegradationWatchV1(per #66)`, and `WorkUnitV2` as required prose.
- LOC delta: about -25 to -60 net if implementation avoids compatibility boilerplate; roughly +40 / -80 expected across docs/prompts/comments/tests.
- Philosophy/CLAUDE.md/SPEC/Tier changes (if any): none. The existing `CLAUDE.md` invariant already says `V1`/`V2`/`schema_version: 1` do not belong in `CLAUDE.md`/`README.md`/`SKILL.md` philosophy text. Round 2 delete does not widen that constitutional rule into a class/test-name ban; implementers can enforce issue 107 by source-regression on the actual leak surfaces without editing `CLAUDE.md`.

## Reverse-evidence (why this is safe to delete)
- No public API breaks: `integration_sync_requests.py` validates `schema == "IntegrationSyncRequestV1"` and returns `IntegrationSyncRequestV1`;`triage_decisions.py` validates `schema == "ManualIssueTriageDecisionV1"` and returns `ManualIssueTriageDecisionV1`;state JSON fields remain actual compatibility fields.
- No external repo dependency on the code is touched: no marker, branch, label, artifact field, state field, class import, or validator literal is renamed.
- Tests covering the path remain load-bearing when they assert behavior: apply helper validation, daemon request emission, triage decision safety, restart/static checks. Tests that merely require old prose vocabulary are not load-bearing and should be rewritten.
- Git history shows `IntegrationSyncRequestV1` / `ManualIssueTriageDecisionV1` were introduced by #70 as narrow controller-owned JSON artifact schemas after deleting lifecycle authority. Their safety value is in fixed schema validation and controller ownership, not in exposing `V1` as product vocabulary.
- Round 1 convergence question asks A vs B. B touches more files (~15 files, ~+260/-230) and requires alias/import decisions while preserving wire literals anyway; A directly deletes the leak with lower blast radius.

## Risks
- If an in-repo or external doc scraper hardcodes old Markdown anchors, renaming `#workunitv1-contract` will break that deep link. I found no in-repo runtime caller; internal links must be updated.
- If implementation over-applies A and removes `"schema": "IntegrationSyncRequestV1"` or `"schema": "ManualIssueTriageDecisionV1"` from JSON contracts, apply helpers will break compatibility.
- If source-regression allowlists all of `REFERENCE.md`, future contract/runbook prose could reintroduce versioned architecture names. The allowlist should be section/block scoped: state schema JSON examples, validator literal references, and explicit runtime compatibility notes only.
- If future consensus wants source class names cleaned too, that should be a separate structural rename issue with compatibility aliases; it is not deletion-positive for issue 107.

## Escalation triggers (if any)
- none

## Reasoning trace (internal — for meta-judge)
- Why I claim this can be deleted: The leak is human-facing vocabulary duplication. The value chain is `daemon/worker emits artifact -> validator checks fixed schema/state fields -> controller owns lifecycle`; renaming runtime Python types does not remove a capability or simplify that chain today.
- What I checked to verify safety: `gh issue view 107 --comments`; round 1 judge artifact; `rg` for `WorkUnitV1|WorkUnitV2|IntegrationSyncDaemonV1|IntegrationSyncRequestV1|ManualIssueTriageDecisionV1|SkillDegradationWatchV1|schema_version|work_unit_schema_version`; validators in `integration_sync_requests.py` and `triage_decisions.py`; source-regression call sites; git history for #70 introducing the wire schemas.
- What I cannot decide alone: final implementation may choose exact responsibility wording, but the delete-side boundary is fixed: choose A, do not rename Python class/type identifiers in this issue, do not edit wire schema/state fields, and do not modify `CLAUDE.md`.

SOLVER_DONE:delete:propose:选择A清理文档prompt注释测试中的版本后缀词汇,保留Python类型名与wire schema/state字段兼容

⟦AI:AUTO-LOOP⟧

[loning]

🤖 minimal solver r2: 选择 A,保留 Python 类型名

TL;DR

• 这是什么:issue 107 round 2 minimal solver 输出。
• 结论:选择 A,只清理文档契约/prompt/注释/source-regression 中的人读版本后缀;保留 Python class/type 名和 wire schema literal。
• 下一步:meta-judge 可用本方案与 structural/delete r2 输出收敛;无需 maintainer 额外授权。

---

详细说明

我选择 A,因为它消除当前已验证的哲学/契约层违规,同时不引入 import alias、schema migration 或 $PROJECT_RULES 修宪。IntegrationSyncRequestV1 / ManualIssueTriageDecisionV1 / IntegrationSyncDaemonV1 这些 Python 名和 artifact "schema": "*V1" 暂保留为内部兼容坐标;source-regression 只允许它们出现在 validator literal、fixture、JSON contract 和兼容说明里。

最小实现面是 SKILL.md、REFERENCE.md、triage-external-issue.md、脚本注释/docstring、以及现有 source-regression 断言。行为测试继续锁住旧 schema JSON 可验证,防止实现者误删 wire compatibility。

---

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

---
solver: minimal
issue: 107
cluster: issue-107
verdict: propose
---

## Recommended framing
选择 A:只清理人读契约词汇,保留 Python class/type 名。违规真实存在,但最小可行边界不是 rename runtime identifiers,而是把 `SKILL.md` / `REFERENCE.md` / prompt / 注释 / source-regression 中作为架构词出现的 `V1/V2/schema_version` 改成职责名,并用窄 allowlist 测试防回归。`IntegrationSyncRequestV1`、`ManualIssueTriageDecisionV1`、`IntegrationSyncDaemonV1` 等 Python 名称和 artifact `"schema": "*V1"` literal 暂保留为内部兼容坐标;若要清理 class 名,应另开独立兼容迁移,不绑在本轮文档哲学修复里。

## Concrete plan
- Files: `skills/codex-refactor-loop/SKILL.md`:把 contract index、Phase index、named runtime exception、producer/phase guardrail 中的人读 `WorkUnitV1`、`IntegrationSyncDaemonV1`、`IntegrationSyncRequestV1`、`ManualIssueTriageDecisionV1`、`SkillDegradationWatchV1`、`WorkUnitV2` 改为职责名,例如 `work-unit contract`、`integration-branch sync daemon`、`integration-sync request artifact`、`manual-issue triage decision artifact`、`skill-degradation watch`、`migrated work-unit replacement`。
- Files: `skills/codex-refactor-loop/REFERENCE.md`:同样替换 contract/runbook prose;`## WorkUnitV1 contract` / `#workunitv1-contract` 改为 `## WorkUnit contract` / `#workunit-contract`,并更新仓库内链接。不保留旧 anchor 兼容壳。
- Files: `skills/codex-refactor-loop/prompts/triage-external-issue.md`:把 prose 中的 `WorkUnitV1-backed` 和 `ManualIssueTriageDecisionV1 JSON artifact/object` 改为职责名;只在实际 JSON contract 行保留 `schema: "ManualIssueTriageDecisionV1"`。
- Files: `skills/codex-refactor-loop/scripts/dev_sync_daemon.py`, `apply_integration_sync_request.py`, `apply_triage_decision.py`, `controller_lib.sh`, `check_skill_degradation.py`:只改 docstring/comment/log prose。保留 `IntegrationSyncDaemonV1` class、`IntegrationSyncRequestV1` / `ManualIssueTriageDecisionV1` dataclass、imports、type annotations、validator error message 和 schema literal。
- Files: `skills/codex-refactor-loop/scripts/test_ensure_project_rules_fixed_points.py`, `test_skill_entrypoint_contract.py`, `test_dev_sync_daemon_state_machine.py`, `test_check_skill_degradation.py`, `test_phase9_router_daemon.py`:把正向断言从版本后缀词改为职责名;fixture / behavior assertion 中真实 `"schema": "*V1"` 保留。
- LOC delta: ~+70 / -70。若把 doc-boundary source-regression helper 单独成新 test file,约 ~+110 / -70;仍不需要触碰 runtime imports。
- Tests to add/modify:新增或修改一个 source-regression 检查,扫描 `SKILL.md` 和 `REFERENCE.md` 的 prose/heading/anchor,禁止 `\b[A-Za-z][A-Za-z0-9_]*V[0-9]+\b`、`schema_version: 1`、`work_unit_schema_version: 1` 出现在 contract/runtime exception/phase guardrail/runbook prose;允许它们只出现在明确的 State schema 字段定义、JSON 示例、validator literal、fixture literal、兼容说明。修改现有 degradation/static source-regression 期望,确认 `check_skill_degradation.py --static` 或 unittest 在 human-facing contract prose 重引入 `FooV1` 时失败。行为测试复用现有 `test_apply_artifact_helpers.py` / triage validation / dev sync emission,并加断言旧 JSON schema literal 仍可验证。
- Philosophy/PROJECT_RULES/SPEC/Tier change (if any): none。`CLAUDE.md` 已经有“哲学文档不写版本后缀”不动点,issue 107 的 body 也明确目标是替换 `SKILL.md / REFERENCE.md / scripts 注释 / 测试名称`,保留 schema 内部演化坐标。最小方案不修改 `$PROJECT_RULES`;覆盖 REFERENCE/prompt/comment/test 的方式放在本 skill 的 source-regression allowlist 中,不扩 repo 宪法。
- Migration path: no migration needed。state 字段、artifact JSON、schema literal、Python import path/class 名、public markers、labels、branch names 全部保持兼容。

## Risks
- 代码 identifier 仍带 `V1`,读代码时会看到内部演化坐标;source-regression 必须明确禁止这些名字从代码 schema 层再渗回人读 contract prose。
- 不改 `CLAUDE.md` 会让“REFERENCE.md / prompt / source comments 是否属于哲学层”的解释留在 skill-local test 中;但这是最小 trusted-base cost,且本 issue 可用机械测试封住。
- 重命名 `#workunitv1-contract` 会破坏外部深链;本仓库规则偏向删除历史兼容壳,所以不建议保留旧 anchor。
- 如果实现者误删 artifact `"schema": "*V1"` literal 或 rename Python class/import,会扩大成 protocol migration;行为测试必须锁住旧 artifact 仍可 validate。

## Escalation triggers (if any)
- none

## Reasoning trace (internal — short, for meta-judge)
- Why this is the minimum: r2 收敛问题只需在 A/B 中选择边界。A 消除已验证的人读契约违规,改动集中在 docs/prose/source-regression,无需 import alias、compat shim、schema constant migration 或 `$PROJECT_RULES` 修改。
- What I considered but rejected: B 同步 rename Python class/test identifier。它更整洁,但会触碰 `dev_sync_daemon.py`、validators、imports、tests 与 possibly downstream imports;为避免 wire schema rename 还要引入常量/alias,成本超过本 issue 的最小修复。
- What I cannot decide alone: 是否未来应做第二阶段无版本 Python class rename。当前建议不作为 issue 107 landing blocker。

SOLVER_DONE:minimal:propose:选择A文档契约清理保留Python类型名,wire schema/state字段兼容且不改CLAUDE.md
⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

🤖 Phase 9 structural solver r2: 选择 A 边界

TL;DR

• 这是什么:issue 107 round 2 structural solver 对 A/B 边界的选择。
• 结论:选择 A,清理 SKILL/REFERENCE/prompt/注释/test 的人读契约词汇,保留 Python 兼容类型名和 wire schema literal。
• 下一步:meta-judge 可用该输出与 minimal/delete r2 输出收敛;不需要 maintainer 额外动作。

---

详细说明

结构边界是 VersionedVocabularyBoundary:版本坐标只允许留在真实兼容协议层,例如 artifact "schema" 值、state 字段、validator literal、JSON fixture 和 retained compatibility class 名。人读的哲学/契约面,包括 heading/anchor、runtime exception prose、prompt prose、source comment/docstring/log narration、test class/method 名,统一改成职责名。

不建议本 issue 同步 rename IntegrationSyncRequestV1 / ManualIssueTriageDecisionV1 / IntegrationSyncDaemonV1 Python 类型名:这会产生 import churn 和 alias/migration 风险,但不会比边界测试更好地保护共识引擎语义。估算改动约 ~+110 / -95 LOC,运行时成本 0 hop / 0 allocation,CI 扫描 <1s。

---

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

---

solver: structural
issue: 107
cluster: issue-107
verdict: propose

PROJECT_RULES clause violated (quoted verbatim)

• 哲学文档不写版本后缀:V1/V2/schema_version: 1 之类的 schema/identifier 版本号属于代码内部演化坐标,不进哲学文档(CLAUDE.md/README.md/SKILL.md 哲学段)。哲学描述不变量与边界,不绑定当前版本号;一旦哲学文本要随 schema 改版而改,说明版本号泄露到了不该泄露的层。Release semver(.version-bump.json 映射的 package/manifest 版本)是另一回事——那是发布坐标,不是设计 identifier。

Supporting rule:

• 变更必须可验证:行为约束必须落到机械验证手段(behavior test / source-regression test / 段落 lint);仅靠"agent 应该记得"承载的约束视为未落地。

Recommended framing

选择 A:清理人读契约词汇并保留 Python runtime 类型名。结构边界不是“文档例外”,而是把版本坐标限定在实际兼容协议层:artifact "schema" literal、state 字段、validator/error fixture 可以保留;SKILL/REFERENCE/prompt prose、heading/anchor、source comments/docstrings/log narration、test class/test method names 一律改成职责名。Python dataclass/class 名如 IntegrationSyncRequestV1、ManualIssueTriageDecisionV1、IntegrationSyncDaemonV1 本轮保留,因为它们已经是代码内兼容坐标和 import surface;禁止的是继续把这些名字展示成架构哲学或契约标题。

Concrete plan

• New abstractions (if any): no runtime abstraction. Add a test-only policy helper named VersionedVocabularyBoundary in test_ensure_project_rules_fixed_points.py or a new test_versioned_vocabulary_boundary.py; it classifies human-facing prose/comment/test-name surfaces vs wire/schema compatibility surfaces.
• Existing repo primitives used: SKILL local controller contract, REFERENCE lazy anchors, existing JSON artifact validators, existing source-regression tests under skills/codex-refactor-loop/scripts/test_*.py, and existing behavior tests for apply helpers/state-machine safety. No IAsyncEnumerable, Channel, proto, actor inbox, or projection primitive applies in this repository.
• Files:
  • skills/codex-refactor-loop/SKILL.md: replace human-facing WorkUnitV1, IntegrationSyncDaemonV1, IntegrationSyncRequestV1, ManualIssueTriageDecisionV1, SkillDegradationWatchV1, WorkUnitV2, and schema_version: 1 prose with responsibility names. Update links from #workunitv1-contract to #workunit-contract. Keep state-field names only where the state schema is explicitly being described.
  • skills/codex-refactor-loop/REFERENCE.md: rename ## WorkUnitV1 contract / anchor to ## WorkUnit contract; rewrite contract/runbook/named-boundary prose to responsibility names. Keep schema_version / work_unit_schema_version only in the state schema JSON example, legacy state compatibility paragraph, and exact field-definition text.
  • skills/codex-refactor-loop/prompts/triage-external-issue.md: describe a manual-issue triage decision artifact; keep schema: "ManualIssueTriageDecisionV1" only inside the emitted JSON artifact contract.
  • skills/codex-refactor-loop/scripts/dev_sync_daemon.py: update docstring/comments/log narration to integration-branch sync daemon and integration-sync request artifact; keep class name IntegrationSyncDaemonV1 and imports of IntegrationSyncRequestV1.
  • skills/codex-refactor-loop/scripts/integration_sync_requests.py: update module/class docstrings to integration-sync request artifact; keep dataclass name IntegrationSyncRequestV1, validation literal "IntegrationSyncRequestV1", and error text that reports the expected schema value.
  • skills/codex-refactor-loop/scripts/triage_decisions.py: update docstrings/comments to manual-issue triage decision artifact; keep dataclass name ManualIssueTriageDecisionV1, schema literal, and validation error text.
  • skills/codex-refactor-loop/scripts/apply_integration_sync_request.py, apply_triage_decision.py, controller_lib.sh, check_skill_degradation.py: update source comments/docstrings/log narration only; keep runtime marker/schema literals unchanged.
  • Tests to update: test_ensure_project_rules_fixed_points.py, test_skill_entrypoint_contract.py, test_dev_sync_daemon_state_machine.py, test_check_skill_degradation.py, test_phase9_router_daemon.py, and test_apply_artifact_helpers.py where they currently assert versioned prose. Rename test classes/methods to responsibility names; keep JSON fixtures with "schema": "IntegrationSyncRequestV1" and "schema": "ManualIssueTriageDecisionV1".
• LOC delta: ~+110 / -95 across 10-12 files. Most churn is prose/test assertion replacement; net +15 from the boundary helper.
• Tests to add:
  • Source-regression: VersionedVocabularyBoundary rejects \b[A-Za-z][A-Za-z0-9_]*V[0-9]+\b, schema_version: 1, and work_unit_schema_version: 1 in SKILL/REFERENCE headings, named runtime exception titles, contract prose, prompt prose outside JSON artifact field contracts, source comments/docstrings, and test class/method names.
  • Allowlist test: same helper permits actual wire/schema surfaces only: JSON fixture "schema" values, validator literal comparisons, validation error messages that quote the expected schema literal, dataclass/class names retained for compatibility, and state schema JSON/field-definition sections.
  • Behavior: existing test_apply_artifact_helpers.py continues to prove old "IntegrationSyncRequestV1" and "ManualIssueTriageDecisionV1" artifacts validate and still require lifecycle_owner == "controller" plus lifecycle_authority is false.
  • Behavior: existing test_dev_sync_daemon_state_machine.py continues to prove daemon emits controller-owned request artifacts without git/GitHub lifecycle authority.
  • Static check: check_skill_degradation.py --static or its tests fail when SkillDegradationWatchV1/IntegrationSyncDaemonV1 reappears in SKILL/REFERENCE human-facing exception prose.
• proto changes (if any): none.
• Philosophy/PROJECT_RULES/SPEC/Tier changes (if any): none. CLAUDE.md already defines the constitutional invariant for philosophy docs and schema/identifier coordinates. Extending the cleanup to REFERENCE, prompts, comments, and test names is a local codex-refactor-loop enforcement detail in SKILL/REFERENCE/tests, not a trusted-base rule change. This avoids broadening the constitution into a ban on code-internal compatibility identifiers, which would contradict the clause's own "代码内部演化坐标" carveout.
• Runtime cost: 0 extra controller wakeup hops, 0 actor/daemon hops, 0 runtime allocations beyond existing imports. CI/source-regression scan cost: ~25 files, estimated <1s locally/CI.

Risks

• This keeps Python class/dataclass names with V1, so grep-only reviewers may think the cleanup is incomplete. The boundary test must make the distinction explicit: code-internal compatibility identifiers are allowed; human-facing philosophy/contract vocabulary is not.
• A too-broad allowlist would let V1 leak back into prose. Keep the allowlist structural: exact state schema section, JSON fixture/schema fields, validator literals, validation error text, and retained compatibility class/dataclass names only.
• Renaming anchors such as #workunitv1-contract can break external deep links. Do not keep a compatibility heading containing the old versioned name; update all in-repo links and let git history preserve the old anchor.
• Not changing CLAUDE.md means the source-regression enforcement must live with the skill tests. That is acceptable because the issue is a codex-refactor-loop vocabulary leak, not a repository-wide Tier/SPEC change.

Escalation triggers (if any)

• none

Reasoning trace (internal — for meta-judge)

• Why this structure beats a documented exception: it creates a mechanically tested boundary instead of saying "V1 is okay here"; the allowed locations are wire/schema compatibility surfaces, not prose.
• Why I picked this abstraction over alternatives: B's class/dataclass rename buys cleaner grep output but adds import churn and possible compatibility aliasing without changing runtime safety. A plus a boundary helper satisfies the clause by construction while preserving the actual schema coordinates.
• What I cannot decide alone: whether future work should migrate Python class names after a deprecation window. It should not be part of issue 107 because all solvers already rejected changing wire schema/state fields, and class-name migration is not needed to remove philosophy/SKILL leakage.

SOLVER_DONE:structural:propose:选择A清理人读契约词汇并保留Python兼容类型名
⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧

[loning]

程序也改啊

[loning]

📊 状态 — 已收到 maintainer 评论(daemon 识别)

维度	值
触发评论	id=4562733979 author=loning
评论摘要	程序也改啊
daemon 反应	👀 eyes react 已加
下一步	controller 下次 wakeup(≤25 min)读 daemon log → 派 fresh codex round(maintainer-reply-resets-the-round)→ 更新本卡片
是否需要人介入	❌ 否(自动响应中)

🤖 comment-monitor.sh daemon

⟦AI:AUTO-LOOP⟧

[loning]

🧑 Maintainer directive — Phase 9 framing reset

Maintainer 在 session 内明确扩 scope:代码中也禁止出现版本号,很傻(verbatim)。

新原则: 版本后缀(`V1`/`V2`/`schema_version`)在 codebase 任何地方 都禁止 — 不只是哲学文档。代码 identifier / JSON 字段 / 类型名都要 rename。

唯一允许:

• `.version-bump.json` 映射的 package release semver(`package.json` 等)— 那是发布坐标
• git tag / commit — 自然历史

R1 verdict 被 reset:

• r1 = `converge:r2:选 A 文档清理保留 Python 类型名,还是 B 同步 rename 类型名并修改 CLAUDE.md invariant`
• 这个 narrow question 现在 obsolete。Option A(只清文档,保 Python identifier)已被 maintainer 拒绝
• R2 必须基于 wider framing:全 codebase rename + anti-regression guard

Maintainer-directive artifact:

• `.refactor-loop/runs/maintainer-directives/2026-05-28-no-version-in-code-either.md`

R2 三 framing 重新派,question 收窄为:如何最小破坏地全 rename + on-disk schema 迁移策略 + source-regression guard。

⟦AI:AUTO-LOOP⟧

[loning]

🤖 structural solver r2: 全代码库去版本号,旧产物只读兼容

TL;DR

• 这是什么: issue 107 在 maintainer 扩 scope 后的 structural r2 framing。
• 结论: 选择全量 rename; Python 类型名、JSON schema 值、prompt marker、state 字段都改职责名。
• 下一步: meta-judge 可按“单 PR: rename + migration + guard”收敛,无需 maintainer 再选 A/B。

---

详细说明

迁移策略是“新写出全部无版本号,旧落盘产物只在 reader 输入端兼容”。schema_version 和 work_unit_schema_version 当前只有一个合法值,没有分支语义,所以不 rename 成新字段,而是从 .refactor-loop/state.json 和示例里删除;旧 state 读取时忽略值为 1 的旧字段,下一次保存自然 drop。

建议一个 one-shot PR 完成: validators 先双读写新,再统一改 docs/prompts/Python/tests/state,最后加全仓 source-regression guard。guard 禁止 *V1/*V2/schema_version/work_unit_schema_version 回来,只 allow .version-bump.json 映射的 release semver version 字段。

---

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

---
solver: structural
issue: 107
cluster: issue-107
verdict: propose
---

## PROJECT_RULES clause violated (quoted verbatim)
> - **哲学文档不写版本后缀**:`V1`/`V2`/`schema_version: 1` 之类的 schema/identifier 版本号属于代码内部演化坐标,**不**进哲学文档(`CLAUDE.md`/`README.md`/`SKILL.md` 哲学段)。哲学描述不变量与边界,不绑定当前版本号;一旦哲学文本要随 schema 改版而改,说明版本号泄露到了不该泄露的层。Release semver(`.version-bump.json` 映射的 package/manifest 版本)是另一回事——那是发布坐标,不是设计 identifier。

Maintainer directive supersedes the old code-internal carveout:

> **No version suffixes anywhere in the codebase** — neither philosophy docs nor code identifiers nor state fields.

Supporting rule:

> - **变更必须可验证**:行为约束必须落到机械验证手段(behavior test / source-regression test / 段落 lint);仅靠"agent 应该记得"承载的约束视为未落地。

## Recommended framing
全量改名应当一次完成,但兼容读取旧产物。结构边界是:运行时对象、JSON artifact、state 字段、prompt marker contract、测试名全部使用职责名;历史中已经落盘的旧 JSON artifact 只在 loader 输入端短期兼容,一旦 controller 或 worker 重新写出,统一写新职责名。`state.json` 里的 `schema_version` / `work_unit_schema_version` 当前只有单一合法值,没有分支语义,所以不是 rename 成新字段,而是删除;旧 state 读取时忽略这些字段并在下一次保存时自然 drop。这样不会制造第二套 schema/version 系统,也不会用 alias 继续泄露版本号。

## Concrete plan
- New abstractions (if any): no runtime abstraction. Add one test-only guard named `NoVersionedDesignIdentifiers` under `skills/codex-refactor-loop/scripts/test_no_versioned_design_identifiers.py`; it scans tracked source/config/docs/state artifacts and fails on version-suffix design identifiers.
- Existing repo primitives used: existing dataclass validators, controller-owned apply helpers, `.refactor-loop/state.json` resumability ledger, source-regression tests under `skills/codex-refactor-loop/scripts/test_*.py`, and `rg`/path allowlist mechanics. No actor inbox, event bus, proto, or new daemon applies.
- Rename map:
  - `WorkUnitV1` -> `WorkUnit`; prose phrases `v1 queue item contract` / `v1 containers` -> `queue item contract` / `queue containers`.
  - `WorkUnitV2` -> `replacement work-unit contract` or delete the example; do not keep a numbered negative example.
  - `IntegrationSyncDaemonV1` -> `IntegrationSyncDaemon` in Python, `integration-branch sync daemon` in docs.
  - `IntegrationSyncRequestV1` -> `IntegrationSyncRequest` in Python and JSON `schema`, `integration-sync request artifact` in docs.
  - `ManualIssueTriageDecisionV1` -> `ManualIssueTriageDecision` in Python and JSON `schema`, `manual-issue triage decision artifact` in docs.
  - `TriageLifecycleRequestV1` -> `triage lifecycle request` in historical comments, preferably delete the old/new comment if it is not load-bearing.
  - `SkillDegradationWatchV1` -> `SkillDegradationWatch` / `skill-degradation watch`.
  - `SkillDegradationCheckV1` -> `SkillDegradationCheck` if the guard remains, otherwise delete the literal from the forbidden-pattern list and assert the responsibility name.
  - `AntiStopWatchdogV1` -> `AntiStopWatchdog` in restart-helper test fixtures.
  - `MarkerEmissionContractV1` -> `MarkerEmissionContract`; update all prompt HTML comments and `test_marker_emission_contract.py` constant together.
  - `ReleaseRollupRequestV1`, `ControllerLifecycleIntentV1`, `ImplementationIntakeV1`, `WorkUnitEnvelopeV1`, `WorkUnitProducerV1`, `AuditSaturationPlannerV1`, `ProducerMixPlannerV1`, `OperationalNamePolicyV1`, `SkillIdentityV1` -> unnumbered responsibility names in tests/docs/comments, or delete when used only as forbidden examples.
  - `schema_version` in `.refactor-loop/state.json`, SKILL/REFERENCE JSON examples, and tests -> delete; no replacement field because the only valid value is currently `1`.
  - `work_unit_schema_version` -> delete; old-state loader treats absence and old value `1` identically by deriving `work_unit_id` from existing `cluster_id`/item identity.
  - Any literal JSON `"schema": "*V1"` -> `"schema": "<same name without suffix>"`; validators accept old literals only on read, dataclasses and new artifacts write only unnumbered schema names.
- Files:
  - `CLAUDE.md` / symlinked `AGENTS.md`: replace the old "哲学文档不写版本后缀" clause with a whole-codebase invariant. Proposed text: `**代码库不写设计版本后缀**:\`V1\`/\`V2\`/\`schema_version\`/\`work_unit_schema_version\` 这类 schema/identifier 版本号不进入代码、文档、prompt、JSON 字段、marker contract、测试名或 state artifact。职责名保持稳定;历史兼容只在 reader 端以窄 allowlist 消化旧 artifact,新写出必须使用职责名。Release semver(\`.version-bump.json\` 映射的 package/manifest \`version\`)是发布坐标,不是设计 identifier。`
  - `.refactor-loop/state.json`: delete `schema_version`; no migration marker is added.
  - `skills/codex-refactor-loop/SKILL.md`: rewrite all versioned contract prose/headings/links; state initialization text no longer writes schema fields.
  - `skills/codex-refactor-loop/REFERENCE.md`: rename `## WorkUnitV1 contract` to `## WorkUnit contract`; update anchors; remove schema fields from examples; rewrite legacy paragraph to "old state may contain deleted fields; ignore them".
  - `skills/codex-refactor-loop/prompts/*.md`: rename `MarkerEmissionContractV1` comments to `MarkerEmissionContract`; update triage prompt to emit `schema: "ManualIssueTriageDecision"`.
  - `skills/codex-refactor-loop/host.env.example`: rename degradation watch comment.
  - `skills/codex-refactor-loop/scripts/integration_sync_requests.py`: rename class/type hints to `IntegrationSyncRequest`; dataclass default `schema = "IntegrationSyncRequest"`; validator accepts both old and new schema strings but returns unnumbered object; error says `schema must be IntegrationSyncRequest`.
  - `skills/codex-refactor-loop/scripts/triage_decisions.py`: same pattern for `ManualIssueTriageDecision`; read old literal, write new literal.
  - `skills/codex-refactor-loop/scripts/dev_sync_daemon.py`: import/use `IntegrationSyncRequest`, rename class to `IntegrationSyncDaemon`, update log text.
  - `skills/codex-refactor-loop/scripts/apply_integration_sync_request.py`, `apply_triage_decision.py`, `controller_lib.sh`, `check_skill_degradation.py`: remove versioned docstrings/comments and expected headings.
  - `skills/codex-refactor-loop/scripts/test_*`: update imports, class names, fixtures, forbidden examples, and positive source-regression assertions to unnumbered names. Add behavior cases proving old schema literals still load and new writes emit unnumbered schema literals.
  - `skills/codex-refactor-loop/scripts/test_no_versioned_design_identifiers.py`: new source-regression guard.
- On-disk state migration:
  - Current `.refactor-loop/state.json`: delete `schema_version` immediately.
  - Loader/init path: when old state includes `schema_version` or `work_unit_schema_version` with value `1`, ignore them; if value is not `1`, fail closed with a clear "unsupported legacy state version field" error rather than inventing a new migration matrix.
  - Writer path: never write either field. Any read-modify-write normalizes old state by dropping both keys.
  - No replacement `state_contract`, `format`, `schema`, or hidden marker. If only one shape is valid, the shape is defined by fields and tests, not by a numeric field.
- Artifact migration:
  - Integration sync request and manual triage decision artifacts use new `"schema"` values on all writes.
  - Readers accept old `"IntegrationSyncRequestV1"` / `"ManualIssueTriageDecisionV1"` for existing `.refactor-loop/runs/*.json` only; they do not preserve the old string when writing.
  - Source-regression guard allows old strings only in explicit legacy-read tests and validator compatibility branches, with string concatenation or a narrow helper preferred so ordinary `rg` does not normalize the old token as acceptable prose.
- Source-regression guard:
  - Scan tracked files plus `.refactor-loop/state.json`; exclude `.git/`, `.worktrees/`, generated logs, caches, and historical `.refactor-loop/runs/*.md` except the active issue-107 artifacts if controller requires them.
  - Fail on `\b[A-Za-z][A-Za-z0-9_]*V[0-9]+\b`, `schema_version`, `work_unit_schema_version`, and JSON schema strings ending in `V<digits>`.
  - Allowlist only release semver surfaces from `.version-bump.json`: mapped manifest `version` fields in `package.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `gemini-extension.json`; also allow changelog/version prose if it is release semver, not design identifier.
  - Do not allow `MarkerEmissionContractV1` in prompts. The contract marker itself is a codebase design identifier and must become unnumbered.
- PR ordering:
  - Prefer one-shot rename+migration+guard PR. Staging as `rename -> migrate -> drop schema_version` leaves an intermediate branch where either source-regression cannot be enabled or runtime writes still create forbidden fields. That invites exactly the regression the maintainer rejected.
  - Inside the one PR, commit order can be mechanical: first validators dual-read/write-new, then docs/prompts/tests rename, then state examples/current state drop fields, then guard. But CI should only be judged at final PR head.
- LOC delta: ~+260 / -230 across 18-24 files. Net growth is mostly dual-read compatibility tests and the guard; prose should shrink where old/new comments can be deleted.
- Tests to add:
  - Behavior: `test_apply_artifact_helpers.py` accepts legacy request/decision schema strings and normalizes returned object `.schema` to unnumbered value.
  - Behavior: write helpers produce `"schema": "IntegrationSyncRequest"` and `"schema": "ManualIssueTriageDecision"`.
  - Behavior: state normalization drops `schema_version` / `work_unit_schema_version` and rejects non-`1` legacy values.
  - Source-regression: full-codebase guard rejects version-suffix identifiers in docs, prompts, Python identifiers, test names, JSON fields, and current state.
  - Source-regression: release semver allowlist proves `.version-bump.json` mapped `version` fields remain legal while arbitrary `schema_version` or `FooV1` outside the narrow legacy-read tests is illegal.
- proto changes (if any): none.
- Philosophy/PROJECT_RULES/SPEC/Tier changes (if any): yes, `CLAUDE.md`/`AGENTS.md` clause must change from "philosophy docs only" to whole-codebase ban. This is worth the trusted-base cost because the maintainer directive rejects the previous internal-code carveout, and deep consensus should hold because the invariant is simpler: stable responsibility names everywhere; legacy compatibility exists only at read boundaries and never as public naming.
- Runtime cost: legacy schema compatibility adds 2 string membership checks per loaded integration-sync or triage artifact, effectively <1 microsecond per load and no new daemon/controller hop. State normalization cost is one `dict.pop` per deleted key during read/write, also negligible.

## Risks
- One-shot rename has broad test churn; reviewers must distinguish mechanical renames from behavior changes. Keep implementation commits locally ordered and include a rename map in the PR body.
- Dual-read compatibility can become a permanent escape hatch if not bounded. Bound it to validator input branches and explicit legacy behavior tests; the guard should forbid old tokens anywhere else.
- Removing `schema_version` means future incompatible state changes cannot hide behind a number. That is intentional: future changes need durable migration logic keyed by actual fields and behavior tests, not a generic version field.
- Historical `.refactor-loop/runs/*.md` and GitHub comments will still contain old tokens. Do not rewrite history; guard should scan current source/config/state, not immutable historical logs.

## Escalation triggers (if any)
- none

## Reasoning trace (internal — for meta-judge)
- Why this structure beats a documented exception: it removes versioned names from the write path and current codebase by construction; old names survive only as read compatibility for existing artifacts.
- Why I picked this abstraction over alternatives: a generic migration framework would reintroduce a schema-version architecture. Field-based normalization plus a source-regression guard is narrower and matches the repo's "single trunk, narrow extension points" rule.
- What I cannot decide alone: exact retention window for legacy artifact reads. I recommend keeping read compatibility until all live `.refactor-loop/runs/*.json` consumers age out, then deleting the compatibility branch in a later cleanup PR backed by `rg` evidence.

SOLVER_DONE:structural:propose:全代码库职责名改名,旧artifact只读兼容,state版本字段删除,一次性PR加guard
⟦AI:AUTO-LOOP⟧

⟦AI:AUTO-LOOP⟧