docs(catalog): add IP-030 machine configuration revision-guarded apply

[BigDataDZ]

Summary

• Add IP-030 Machine Configuration Preview And Revision-Guarded Apply to docs/concepts/interaction-pattern-catalog.md under the Human Decision family, with its catalog row, full detail entry, and pattern-to-canary matrix registration.
• Describe a shipped interaction that was not yet catalogued: machine-config preview returns a plan_revision, and apply, remove, and rollback refuse to write unless the caller presents that exact revision via --expected-plan-revision plus --execute.
• List every built-in namespace the composition registry actually registers — change_quality_qualification, manager_runtime, periodic_report, pull_request_review, todo_replan_cadence — and name the public catalog from loopx machine-config describe as the authority for that inventory, so the list has a stated source rather than being an approximation.
• Record pull_request_review's semantics: review_priority defaults to other-developers-first, with owner-first as an explicit opt-in that changes ordering only.
• Extend examples/interaction-pattern-catalog-smoke.py so every registered built-in namespace has to appear in the catalog, which keeps the inventory from drifting again.
• Documentation plus one smoke assertion. No behavior, CLI contract, or existing IP entry is changed.

Issue Or Task

• Closes [Task]: Add IP-030 for machine configuration preview and revision-guarded apply #4320
• Contributor task ID: GH-C37

Validation

• Tested revision: 6c938bddb9d4a6bc6c70533a6f64ca9c3842bc8f
• Run state: finished
• Input classes: synthetic

Check kind	Result	Public-safe evidence / limitation
static	passed	loopx check --scan-path docs/concepts/interaction-pattern-catalog.md --scan-path examples/interaction-pattern-catalog-smoke.py → ok: True, errors=0, public boundary scan clean: 2 files.
unit	passed	pytest -q tests/capabilities/test_machine_configuration_contract.py tests/capabilities/test_machine_configuration_goal_defaults.py → 23 passed. These are the behavior evidence for the interaction IP-030 describes: the revision guard, namespace merge preserving siblings, Goal-override precedence, and fail-closed rejection cases.
smoke	passed	python3 examples/interaction-pattern-catalog-smoke.py → interaction-pattern-catalog-smoke: ok; pytest -q tests/canary/test_smoke_fleet_health.py → 3 passed.

• Coverage and gaps: The new namespace-coverage assertion was checked in both directions rather than assumed — it passes on the fixed tree, and temporarily renaming manager_runtime in the catalog makes it fail with namespaces missing from the catalog: ['manager_runtime']. Catalog table/detail order and the pattern-to-canary matrix were re-verified programmatically: all five families consistent, IP-030 present in the Human Decision matrix row. The smoke asserts catalog coverage of registry namespaces; it does not assert that each documented namespace is described correctly, which remains a review concern.

Frontend / Visual Evidence

• UI impact: none
• Before:
• After:
• States and viewports shown:
• Source data: none

Type of Change

• Bug fix
• New feature
• Breaking change
• Refactoring (no functional changes)
• Documentation update
• Test update

LoopX Area

• Control plane (goals, todos, quota, scheduler, registry, runtime)
• Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
• Capability or extension (providers, adapters, skills)
• Public docs or presentation surface (README, protocols, dashboard)
• Build, packaging, installer, or CI
• Host or runtime integration

Technical Direction

• Core control-plane hardening

• Long-horizon benchmark evidence

• Operator surface and IM integration

• Shared Goal Authority and cross-host coordination

• Architecture and research incubator

• Target base branch: main

[huangruiteng]

动机

本 PR 为交互模式目录增加 IP-030，描述机器配置的 preview、精确 plan_revision、owner 审批、revision-guarded apply/remove/rollback，以及 Goal override 与 live machine default 的关系。这个模式填补了一个真实的公共文档空白：配置变更不能只展示“将要写入什么”，还要把审批绑定到用户实际看到的 revision，并明确未知字段和 sibling namespace 的 fail-closed 行为。改动范围保持在一个目录文件内，方向和问题匹配；但目录同时承担前端/操作员发现能力的职责，因此其中看似说明性的 built-in namespace 清单必须与已发布 registry 保持完整。

改动思路

IP-030 以 machine-configuration contract 为权威背景，先 preview 形成精确结果和 plan_revision，再把该 revision 呈现给 user，最后由 apply/remove/rollback 使用 --expected-plan-revision 重新推导并拒绝过期计划。文档还说明 namespace patch 不应丢失 sibling namespace、whole-envelope 写入需显式命名全部内容、Goal override 优先于 machine default、清除 override 会回到 live default，以及未知 namespace/字段应在 effect 前失败。这个流程与当前 CLI/contract 的职责边界一致，目录 smoke 也能读到新增 section。问题在于 Trigger 的第二个 bullet 把 built-in namespace 写成只有三个：periodic_report、todo_replan_cadence、change_quality。当前 main 的 composition registry 已注册第四个 pull_request_review，其公开 machine default 是 review_priority（默认 other-developers-first，owner-first 为显式选项）。因此文档的发现入口没有覆盖实际可配置面。

具体改动

关键内容讲解

• docs/concepts/interaction-pattern-catalog.md:90 将 IP-030 加入 Human Decision family 的索引，使模式在总目录中可发现。
• docs/concepts/interaction-pattern-catalog.md:1191-1200 新增 IP-030 Trigger，说明 typed namespace 变更、plan_revision、envelope/namespace patch、Goal override 与 live default 的适用场景。
• docs/concepts/interaction-pattern-catalog.md:1202-1213 给出 Expected behavior，明确 preview 与 effect 分离、revision guard、sibling 保留、override precedence 和 fail-closed 输入边界。
• docs/concepts/interaction-pattern-catalog.md:1215-1228 用 sequence diagram 展示 agent preview、user approval、apply 和 stale rejection；1230-1243 给出 bad smell 与 validation 命令。
• 这些文字与现有 build_builtin_machine_configuration_registry、pull_request_review_machine_configuration_namespace 的公共配置契约形成同一发现面；但 1195-1198 的清单遗漏 pull_request_review，使新增模式对 PR review 配置不完整。

对主干的风险

这是 P1 文档/配置发现风险而不是运行时写入 bug。用户在 IP-030 的 Trigger 位置读取 built-in 列表，会得到一个看似穷尽的三项集合；随后即使前端或 CLI 已支持 pull_request_review.review_priority，也无法从该公共交互目录发现它。当前 interaction-pattern-catalog-smoke.py 只证明 section 结构和关键语句存在，因此会通过，而不会发现 registry 与目录之间的缺口。最小修复是把 pull_request_review 加入列表，并注明 review_priority 的当前默认/可选语义；或者把句子改成明确的“包括但不限于”，同时给出 registry-backed discovery/readback，避免未来每增加 capability 都留下静默缺项。建议为 catalog smoke 增加一个轻量完整性断言：对已注册 built-in namespace，要么在 IP-030 中出现，要么有明确的 intentional omission 记录。该修复不改变 runtime behavior，只恢复公共文档与实际配置 surface 的一致性。

我的整体评价

这是一个聚焦、可读、对 owner approval 语义有帮助的文档改动；IP-030 的 preview/apply 说明、坏味道和验证入口都覆盖到位。我在 exact head 59b7c5cff9588374660e94e9ae8cd757cfa141ad 上运行 interaction-pattern-catalog-smoke.py，结果为 ok，且确认当前 main 的 machine-configuration registry 已包含 pull_request_review。由于新增 section 的 namespace inventory 不完整，当前不能批准；补齐该项并增加覆盖性 smoke 后即可快速复审。

English verdict: REQUEST_CHANGES for 4321@59b7c5cff9588374660e94e9ae8cd757cfa141ad. IP-030 documents only three built-in namespaces, but main also ships pull_request_review.review_priority. The catalog smoke passes without checking inventory completeness, so update the list or make it explicitly non-exhaustive and add a registry-backed assertion.

[BigDataDZ]

Thanks — fixed. Rebasing onto current main surfaced one more gap than you flagged.

Inventory corrected. build_builtin_machine_configuration_registry() on current main registers five namespaces, not three, and one of the original three was also wrong:

Before	Now
periodic_report	periodic_report
todo_replan_cadence	todo_replan_cadence
change_quality	change_quality_qualification — the name itself was wrong
—	manager_runtime — missing
—	pull_request_review — missing, the one you flagged

The Trigger now also names the public catalog from loopx machine-config describe as the authority for the inventory, and records pull_request_review's semantics: review_priority defaults to other-developers-first, with owner-first as an explicit opt-in that changes ordering only.

Coverage assertion added. examples/interaction-pattern-catalog-smoke.py now reads the registry and fails when a registered built-in namespace is absent from the catalog:

registered_namespaces = sorted(
    build_builtin_machine_configuration_registry().namespace_ids
)
undocumented = [ns for ns in registered_namespaces if ns not in catalog]
assert not undocumented, (...)

I verified it both directions instead of assuming: the smoke passes on the fixed tree, and temporarily renaming manager_runtime in the catalog makes it fail with namespaces missing from the catalog: ['manager_runtime'].

Rebased onto main at 6c1a4d2cc. Worth flagging why this was invisible before: my branch was based on 34710d17a, where the registry still registered only three namespaces. That is why the inventory looked complete to me, and why the previous smoke could not have caught it — the assertion only becomes meaningful on current main.

Validation on the rebased head:

• loopx check --scan-path docs/concepts/interaction-pattern-catalog.md --scan-path examples/interaction-pattern-catalog-smoke.py → ok: True, errors=0, public boundary scan clean: 2 files
• pytest -q tests/capabilities/test_machine_configuration_contract.py tests/capabilities/test_machine_configuration_goal_defaults.py → 23 passed
• pytest -q tests/canary/test_smoke_fleet_health.py → 3 passed
• Catalog table/detail order and the pattern-to-canary matrix re-checked programmatically: all five families consistent, and IP-030 present in the Human Decision matrix row

[huangruiteng]

结论：APPROVE。我复审了当前 exact head 6c938bddb9d4a6bc6c70533a6f64ca9c3842bc8f 的完整改动，并单独核对了上一轮 blocker。上一轮指出的配置目录缺项已完整修复：当前 composition registry 的五个 built-in namespace 全部进入 IP-030，错误的 change_quality 也改成真实 id change_quality_qualification；manager_runtime 与 pull_request_review 都已补齐，且 pull_request_review.review_priority 的默认 other-developers-first / 显式 opt-in owner-first 语义与当前 capability 配置一致。

非阻塞 P2：同一作者在约 21 分钟内提交了 #4321、#4322、#4324、#4326，均修改 interaction-pattern catalog，构成明显的 same-shape PR batch / PR-farming 风险。这个 exact head 本身不是无价值或重复 smoke：它补的是一个真实已发布交互契约，并把 registry 与公共目录绑起来；已经 merged/closed 的 sibling 现在也无法回收成一个 PR，所以我不因此阻塞本次批准。但后续同一 surface 的顺序、visual model、placement、inventory 等维护应合成一个 cohesive PR，避免把完整文档判断拆成多轮 reviewer overhead。本轮未发现此前已针对该 batch pattern 发出的 REQUEST_CHANGES 警告，因此不触发 contribution-restriction escalation。

动机

机器配置已经具备 preview、精确 plan_revision、revision-guarded apply/remove/rollback、namespace patch sibling 保留与 Goal override/live default 行为，但 interaction-pattern catalog 没有把它作为一个 human-decision pattern 讲清楚。缺少这层目录会让调用方看到命令，却不容易理解“审批绑定的是哪个结果”“另一个 writer 改变计划后为什么必须重新 preview”。

更具体地说，上一版文档还把看似穷尽的 built-in inventory 写错、写少：这会让已经发布的 manager_runtime 与 pull_request_review 从公共发现面消失。修复后，文档明确以 loopx machine-config describe 的公共 catalog 为权威来源，并通过 smoke 防止 registry 新增 namespace 后再次静默漏项。

改动思路

IP-030 的流程把 decision 和 effect 分开：agent 先 preview exact resulting plan，user 看到并批准对应 revision，apply/remove/rollback 在 store lock 下重新推导，只有 --expected-plan-revision 仍匹配才写入。namespace patch 保留 siblings；whole-envelope 写入必须显式给出完整目标；当 capability 同时存在 Goal override 与 machine default 时，override 优先，清除后回到 live default而非旧快照。

文档没有另造运行时概念，而是复用现有 machine-configuration contract、store 和 public describe surface。测试也没有新建一份重复 checker，而是在既有 interaction-pattern-catalog-smoke.py 里直接读取 build_builtin_machine_configuration_registry().namespace_ids，把已安装 registry 作为 inventory source。

具体改动

• Catalog family/matrix：Human Decision family 与 P1 表增加 IP-030。
• IP-030 Trigger：列出 change_quality_qualification、manager_runtime、periodic_report、pull_request_review、todo_replan_cadence 五个当前 namespace，并说明 describe 是权威 catalog。
• Expected behavior：覆盖 plan revision、stale rejection、sibling preservation、whole-envelope、Goal override/live default 以及未知 namespace/field/private field 的 fail-closed 边界。
• Visual model / bad smell / validation：给出 preview → user approval → apply/reject 的完整链路及对应测试入口。
• Smoke：从真实 composition registry 取 namespace ids，任何未在公共 catalog 文本中出现的 id 都会列入明确失败信息。
• 验证：interaction-pattern-catalog-smoke.py 通过；machine-configuration contract、goal-defaults 与 fleet-health 共 26 passed；Ruff 与 git diff --check 通过；machine-config describe 在当前 head 实际返回上述五项。远端 DCO、dependency、build、kernel static、dashboard、Node compatibility、四个 test shard、Windows、E2E、installed、pytest、Sonar 与 merge-gate 均已完成并通过；仅 presentation/deploy 按条件跳过。

对主干的风险

这是 docs + durable smoke，不改变 CLI、schema 或 store 写入行为。最大的内容风险是文档再次和 registry 漂移；新 smoke 已覆盖“注册项在公共 catalog 完全不可发现”的回归，并且作者给出了删除 manager_runtime 后 smoke 失败的反向证据。

残余风险只有一项：smoke 在整个 catalog 内检查 namespace occurrence，而不是只解析 IP-030 Trigger；未来某个 id 若恰好出现在别处，IP-030 的局部清单仍可能过期。这不影响当前五项的正确性，也不值得为 docs smoke 引入复杂 parser，后续可在真实误报出现时收紧 section boundary。当前远端 required checks 已全部通过。

我的整体评价

当前改动有明确的 shipped behavior 归属、公共用户价值和非重复维护收益，范围也保持在一个目录与一个既有 smoke。上一轮具体缺陷已被完整修复，没有引入第二套配置 authority。future-facing pass 中唯一值得保留的是未来同 surface 文档批次合并提交；本 PR 不需要再扩展成新的 catalog framework。可以批准。

English verdict: APPROVE 4321@6c938bddb9d4a6bc6c70533a6f64ca9c3842bc8f — the prior namespace-inventory blocker is fixed against the real five-entry registry, the new catalog smoke and 26 focused tests pass, and IP-030 accurately documents revision-guarded machine configuration. P2: consolidate future same-surface catalog batches instead of opening several minute-spaced PRs.