Skip to content

docs(catalog): name what the retired setting projection actually carries - #5053

Merged
huangruiteng merged 1 commit into
loopx-project:mainfrom
NIU-123370:codex/ip037-projection-wording
Sep 25, 2026
Merged

huangruiteng merged 1 commit into
loopx-project:mainfrom
NIU-123370:codex/ip037-projection-wording

Conversation

@NIU-123370

Copy link
Copy Markdown
Contributor

Goal And Delivered Outcome

  • Goal/source and gap: docs(catalog): add IP-037 a retired setting is not an absent setting #5043 was approved on head a270a55bd and merged as
    bea36ae46 with one non-blocking wording finding: the IP-037 index row says
    the projection must "carry its reason", but the retired-setting summary
    actually carries status: "retired" (or invalid when malformed) plus
    replacement (loopx/control_plane/coordination/runtime_shadow.py:53-63).
    The standalone reason code exists only in the rejection message (:72) and in
    the migration row (loopx/state_migration.py:236-241). As written, that cell
    invites a reader to look for a reason field the summary never had.
  • Observable before → after, with the validation row that proves it: before, the
    row overstates what the projection carries; after, it names the two things
    that are actually there — retired status and replacement. Proven by the
    manual row below, which re-reads each cited source.
  • Issue/task and intended base: follow-up wording on the merged GH-C37 entry
    ([Task]: GH-C37 add IP-037 a retired setting is not an absent setting #5042, docs(catalog): add IP-037 a retired setting is not an absent setting #5043). Base main.

Scope And Continuation

  • Completed scope and remaining work: one table cell. The detail section needed
    no change: its three "reason" mentions point at the rejection message, the
    migration reason_code, and the reward-memory retirement_reason, and all
    three fields exist as cited.
  • Slice boundary / successor: N/A; complete within this scope.

Validation

Public-safe summaries only.

  • Tested revision: fe9b2f54b
  • Run state: finished
  • Input classes: none
Check kind Result Public-safe evidence / limitation
static passed python3 examples/interaction-pattern-catalog-smoke.py → interaction-pattern-catalog-smoke: ok.
static passed loopx check --scan-path docs/concepts/interaction-pattern-catalog.md → public boundary scan clean: 1 files, errors=0. Its two warnings are this scratch worktree having no local registry, not a finding about the diff.
manual passed Re-read of the three cited sources on this base: the summary returns status/enabled/configured/replacement and no reason; the reason code appears in the rejection text and in the migration notice. The corrected wording matches all three.
regression_parity passed The smoke's structural gates (row↔heading pairing, one-id-one-family) still pass; this edit changes no id, heading or family registration, so it introduces no new drift surface. git diff --check clean.
  • Coverage and gaps: documentation-only, one cell; no runtime path exists to
    cover, so no unit/integration/real_backend row applies. Interpreter note:
    the checks ran with repository-relative commands against a locally installed
    Python 3.12 environment (an editable install from another worktree on this
    machine), not uv sync --extra test.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A

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

  • Direction / acceptance reference, when applicable: Architecture and research
    incubator — wording accuracy on the GH-C37 catalog entry. No roadmap S/G/R id
    claimed.

Shared-authority RFC fixture impact

  • Production-scale fixture schema: N/A — no fixture or envelope changed.
  • Semantic dimensions changed, or reviewed no-impact rationale: N/A.
  • Provider conformance arms run: N/A — one documentation cell changed.
  • Read-only legacy/file/PostgreSQL three-arm rehearsal: N/A — no behavior,
    routing or projection code is touched.

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

Signed-off-by: NIU-123370 <191000457+NIU-123370@users.noreply.github.com>

@huangruiteng huangruiteng left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

English verdict: APPROVE — the catalog row now names the fields the retained-setting projection actually exposes; no blocker found on this exact head.

动机

合并后的 IP-037 索引行说投影会携带“reason”,但实际的保留配置摘要没有 reason 字段。这个错位会让读文档的维护者或集成方去寻找不存在的数据,并可能把拒绝消息或迁移通知中的原因码误当成配置投影的一部分。本 PR 只修正该索引行的字段描述,属于能独立交付的文档纠偏,不声称改变运行时行为。

改动思路

沿用现有 catalog 的一行一模式结构,只替换该行的目标表述,不引入新协议或第二份迁移规则。核对了 local_authority_shadow_summary 的返回值:合法保留项有 status: retired 和 replacement: coordination_runtime_shadow,格式不合法时 status 为 invalid;拒绝启用时的原因只在错误文本中,迁移通知另有 reason_code。这样能把“显示的状态”和“拒绝原因”分开,避免索引说明越权定义字段。

具体改动

关键内容讲解

唯一改动是 docs/concepts/interaction-pattern-catalog.md 的 IP-037 索引行:原句“carry its reason in the projection”改为“carry its retired status and replacement in the projection”。它仍要求在写入前拒绝已退役设置的激活、保留旧条目可见且只读,并明确清除旧设置不等于启用或 bootstrap 替代功能。索引行的模式编号、所属类别和详情节均未变;详情节提到的拒绝信息、迁移 reason_code、reward-memory retirement_reason 各自指向不同契约,不能把其中一个字段挪到摘要。该精度提升也不影响 catalog smoke 所守护的一号一族和索引/标题配对。

对主干的风险

风险低且局限于公开文档的一处措辞:不会改变配置解析、持久化、读回、CLI 或默认开关。可能的边界是 status 在损坏的保留配置中会是 invalid 而非 retired;此句描述的是有效退役项,详情与实现并未把异常态隐藏,因此不构成阻断。如果将来继续精修,可以写成“status (retired/invalid) and replacement”,但不应为此扩大本 PR。独立在 exact head 运行 catalog smoke 通过,git diff --check 通过;未查询远端 CI,按本次 review packet 的本地验证策略处理。

我的整体评价

APPROVE。它消除了一个真实的文档/实现歧义,并保持文档层边界:长期看减少集成方依据不存在字段实现逻辑的风险,阅读体验更准确;无新增运行时维护负担。当前 head 为 fe9b2f54b4a54f0bbc7919bf9cd6e31b5be97674,此结论只适用于该 head,不代表代替合并就绪或授权合并。

@huangruiteng
huangruiteng merged commit 27f0fc9 into loopx-project:main Sep 25, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants