spec: cover the rebase-merge modules and re-verify what it staled - #106
Conversation
Main has been red on `check_spec_freshness --strict` since the rebase-merge lineage landed: 13 pages stale, 38 modules uncovered, 3 pages orphaned by the v1/v2 cutover. This restores the gate to CLEAN (67 pages — 0 stale, 0 undeclared, 0 orphan, 0 uncovered) without weakening it. New coverage (8 pages; package pages per the SPEC/<pkg>.md mapping rule, precedent engine/steps/pr.md): - rebase_engine.md — the 26-module v3 engine package: per-module map, C4 push double-gate + WAL trichotomy, checkout-lock hygiene shield, mode/gate adjudication, token-in-header transport, wheel venv targeting - testing.md — the test-execution substrate package: hw-gate explicit skips, layered timeouts, PID-reuse-safe tree kills, GPU lock ownership, watchdog two-tier adjudication + append-only learning, credential scrub - engine/steps/rebase_v3.md (12-step table with published state keys), engine/steps/rebase_knowledge.md, engine/lifecycle.md, ci/buildkite.md, memory/curator.md, memory/paths.md Re-verified 13 stale pages against their sources' actual diffs — content amended where contracts moved, not just markers: _common (K3/K4/K7 helpers landed; debug-memory writes via KnowledgePaths), tools (extra-tool write_path_arg scoping opt-in, audit_ok classifier), adapters/base (HIGH_RISK_SECTIONS +rebase, expand_path extra fallback, AdapterNotFound), executor (durable checkpoint), config (v3 rebase knobs, expansion_env secret filter, PR4d fail-closed cutover, neutralized high_risk_modules), agent_runtime (runtime-first three-tier skill scoping, journal-side seed usage), debug_memory (schema v2 explicit-upgrade-only, readonly URI, curation), skills (durable candidates, usage-journal primitives), mcp_server (lock-loser reconcile signature), cli (migrate-knowledge, mode write-back, shared knowledge run-lock), chat, steps/__init__ (45 steps), PLAYBOOKS (marker only — the cutover already rewrote the content). Deleted the 3 orphaned pages of deleted modules (rebase_ext, rebase_native, rebase/monitor) and fixed the stale rosters that named them (SPEC README index, CODE_TOUR rebase branch, GUIDE step counts 38→45 with real per-kind numbers). Known docstring drift recorded, not silently fixed: agent_loop.py and rebase_tools.py call the tool choke point "C5" where _CONSTRAINTS.md numbers it C3 — noted in rebase_engine.md's refactor notes. Gates: check_spec_freshness --strict CLEAN, check_doc_links (300 files), check_doc_citations, full offline suite — all green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0165QsXAeLVPrKfj8Yk5zns3
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 183bc74a68
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | 规划数据 | `playbooks/store` `playbooks/PLAYBOOKS`（yaml） | | ||
| | 边缘 —— 语言 | `profiles/languages`（按语言的规则，共享） | | ||
| | 边缘 | `adapters/base` `ci/normalize` `ci/providers` `rebase/monitor` | | ||
| | 边缘 | `adapters/base` `ci/normalize` `ci/providers` `ci/buildkite` | |
There was a problem hiding this comment.
Keep this supposedly complete mirror index synchronized with the pages introduced by this commit. It still omits engine/lifecycle.md, rebase_engine.md, testing.md, memory/curator.md, and memory/paths.md, so contributors following the README before modifying those source modules cannot discover their new contracts from the declared index.
Useful? React with 👍 / 👎.
|
|
||
| <!-- verified-against: 2026-08-25 --> | ||
|
|
||
| `LOC ~7500（26 个模块） · repo-rebase-v3 的原生 rebase 引擎 · refactor-status: ok` |
There was a problem hiding this comment.
Correct the module count and add wheel.py to the per-module table. The reviewed tree contains 27 Python modules in rebase_engine/, including wheel.py, while this page claims 26 and maps only the other 26; this leaves wheel selection, installation, and pinning without the responsibility entry promised by the page's “逐模块图”.
Useful? React with 👍 / 👎.
| | `rebase.phase2_prepare` | read | 预检 curator + phase-2 进度初始化 | | ||
| | `rebase.phase2_finalize` | read | 两个 wave 完成后推进父标记 | | ||
| | `workspace.guard_clean_rebase` | write_workspace | rebase 专用脏树守卫（adapter 策略委托） | | ||
| | `rebase.v3_prelude` | read | 模式解析写回、substate/锁/终局 finalizer、知识开账 | |
There was a problem hiding this comment.
Describe this step as validating the resolved mode and publishing its flags rather than resolving and writing it back. _v3_prelude only reads params.rebase_mode and returns BLOCKED when it is absent or unknown; rebase_engine.modes is invoked by the CLI before the playbook to perform authoritative resolution and write-back, so the current row assigns a safety-critical responsibility to the wrong component.
Useful? React with 👍 / 👎.
1 participant
What
Restores
check_spec_freshness --strictto CLEAN (67 pages — 0 stale, 0 undeclared,0 orphan, 0 uncovered) without weakening the gate. Main has been red since the rebase-merge
lineage landed: 13 stale pages, 38 uncovered modules, and 3 pages orphaned by today's v1/v2
cutover — every open PR (#100–#105) inherits that failure.
New coverage (8 pages). Package pages use the checker's own
SPEC/<pkg>.mdmapping(precedent:
engine/steps/pr.md):rebase_engine.md— the 26-module v3 engine package (per-module map; C4 pushdouble-gate + WAL trichotomy with cited lines; checkout-lock hygiene shield; token-only
header transport; wheel venv targeting)
testing.md— the test-execution substrate (hw-gate explicit skips; layered timeouts;PID-reuse-safe tree kills; GPU-lock ownership rules; two-tier watchdog + append-only
learning; allowlist credential scrub)
engine/steps/rebase_v3.md(12-step table with publishedstate_updateskeys),engine/steps/rebase_knowledge.md,engine/lifecycle.md,ci/buildkite.md,memory/curator.md,memory/paths.md13 stale pages re-verified against their sources' diffs — content amended where the
contracts actually moved, not marker-bumped:
_common(K3/K4/K7 helpers landed),tools(extra-toolwrite_path_argopt-in scoping,audit_ok),adapters/base(
HIGH_RISK_SECTIONS+rebase,expand_pathfallback,AdapterNotFound),executor(durable checkpoint),
config(v3 knobs,expansion_envsecret filter, PR4d fail-closedcutover),
agent_runtime(runtime-first skill scoping),debug_memory(schema v2),skills(durable candidates, usage journal),mcp_server(lock-loser reconcile),cli(migrate-knowledge, mode write-back, knowledge run-lock),
chat,steps/__init__(45steps),
PLAYBOOKS(marker only — the cutover already rewrote its content).Deleted the 3 orphaned pages of deleted modules (
rebase_ext,rebase_native,rebase/monitor) and fixed every roster that still named them: SPEC README index,CODE_TOUR's rebase branch, and GUIDE §6's full step inventory (38→45 with the real
per-kind counts and the v3 step tables).
Recorded, not silently fixed:
agent_loop.py/rebase_tools.pydocstrings call the toolchoke point "C5" where
_CONSTRAINTS.mdnumbers it C3 — flagged inrebase_engine.md's refactor notes for a comment-only follow-up.Verification
tools/check_spec_freshness.py --strict— CLEAN (was: 13 stale / 38 uncovered / 3 orphan)tools/check_doc_links.py(300 files) andcheck_doc_citations.py— OKon the highest-stakes claims (push WAL, hw-gate, curator schema guard, migration marker)
re-read the cited lines directly.
Unblocks CI for #100–#105.
🤖 Generated with Claude Code
https://claude.ai/code/session_0165QsXAeLVPrKfj8Yk5zns3