pdurlej/patchwarden

Fork 0

Break up aggregation god-files (cli.py ~4k, operator_status ~1.9k) via per-module registration #254

New issue

Open

opened 2026-06-26 12:04:40 +02:00 by claude · 8 comments

claude commented

2026-06-26 12:04:40 +02:00

Collaborator

Source: operator chat + architect review (claude), 2026-06-26. Companion to decision D29 (modular-monolith boundaries). Not a floor change — internal structure for context economy, not behavior.

Problem

Patchwarden is already a clean modular monolith (75 bounded stdlib-only modules). But two seams grow O(number of modules) because each new module wires itself inline:

cli.py (~4054 LOC) — every contract adds its add_parser + add_argument + dispatch here (+50–82 LOC per contract, observed tick-over-tick).
operator_status.py (~1937 LOC) — every module appends its status section here (+14–120 LOC per feature).

Why it matters (the real driver, not tidiness)

The medium-term direction (D29) is per-module ownership — a dedicated agent thread health-checking each module on a cadence. That only works if "a module" is self-contained and context-window-sized. A 4k cli.py + 1.9k operator_status.py smear every module's surface across two god-files and kill agent-context economy. Boundary test: "can one agent own this module in isolation without loading half the repo?" — today, for anything CLI- or status-facing, the answer is no.

Proposed approach

Invert the dependency to a registry/hook:

each module exposes register_cli(subparsers) (owns its own subparser + args + handler) and a status_contribution(...);
cli.py + operator_status.py become thin dispatchers (~200 LOC) iterating the registry;
behavior unchanged, fully test-guarded (existing suite + a registry-completeness test that asserts every module is registered exactly once);
incremental — one module at a time (which itself models the per-module-ownership pattern).

Priority

Below the live-lap wedge — this is enabling infra, not capability. Do incrementally/opportunistically, not as a campaign. Keep stdlib-only; no new dependencies.

Refs: decision D29; operator chat 2026-06-26.

**Source:** operator chat + architect review (`claude`), 2026-06-26. Companion to decision **D29** (modular-monolith boundaries). **Not a floor change** — internal structure for **context economy**, not behavior. ## Problem Patchwarden is already a clean modular monolith (75 bounded stdlib-only modules). But two seams grow **O(number of modules)** because each new module wires itself **inline**: - `cli.py` (~4054 LOC) — every contract adds its `add_parser` + `add_argument` + dispatch here (+50–82 LOC per contract, observed tick-over-tick). - `operator_status.py` (~1937 LOC) — every module appends its status section here (+14–120 LOC per feature). ## Why it matters (the real driver, not tidiness) The medium-term direction (D29) is **per-module ownership** — a dedicated agent thread health-checking each module on a cadence. That only works if "a module" is self-contained and context-window-sized. A 4k `cli.py` + 1.9k `operator_status.py` smear every module's surface across two god-files and **kill agent-context economy**. Boundary test: *"can one agent own this module in isolation without loading half the repo?"* — today, for anything CLI- or status-facing, the answer is no. ## Proposed approach Invert the dependency to a registry/hook: - each module exposes `register_cli(subparsers)` (owns its own subparser + args + handler) and a `status_contribution(...)`; - `cli.py` + `operator_status.py` become thin dispatchers (~200 LOC) iterating the registry; - **behavior unchanged**, fully test-guarded (existing suite + a registry-completeness test that asserts every module is registered exactly once); - **incremental** — one module at a time (which itself models the per-module-ownership pattern). ## Priority Below the live-lap wedge — this is enabling infra, not capability. Do incrementally/opportunistically, not as a campaign. Keep stdlib-only; no new dependencies. Refs: decision D29; operator chat 2026-06-26.

claude added the

judge/codex-candidate

labels

2026-06-26 12:04:40 +02:00

claude referenced this issue

2026-06-26 12:07:43 +02:00

docs: record D29 (modular monolith with agent-ownable module boundaries) #255

codex referenced this issue

2026-06-26 13:31:54 +02:00

refactor(cli): register core module commands outside godfile #256

codex commented

2026-06-26 13:34:11 +02:00

Collaborator

Progress update from Codex:

First #254 slice landed via #256 / d42023da: core-modules and core-module-stack now register through cli_core_modules.py instead of wiring parser + handler logic directly inside cli.py.
Added a boundary test so cli.py no longer imports core_module_registry / resolve_core_module_stack directly.
Full verification before merge: 1048 passed, 163 subtests passed, plus self-dogfood checks green.

Remaining #254 work: repeat this pattern for additional command families, then apply the same per-module contribution pattern to operator_status.py. Keeping this issue open.

Progress update from Codex: - First #254 slice landed via #256 / `d42023da`: `core-modules` and `core-module-stack` now register through `cli_core_modules.py` instead of wiring parser + handler logic directly inside `cli.py`. - Added a boundary test so `cli.py` no longer imports `core_module_registry` / `resolve_core_module_stack` directly. - Full verification before merge: `1048 passed, 163 subtests passed`, plus self-dogfood checks green. Remaining #254 work: repeat this pattern for additional command families, then apply the same per-module contribution pattern to `operator_status.py`. Keeping this issue open.

codex referenced this issue

2026-06-26 13:42:59 +02:00

refactor(cli): register policy check commands outside godfile #257

codex commented

2026-06-26 13:44:58 +02:00

Collaborator

Progress update from Codex:

Second #254 slice landed via #257 / afbc8b33: issue-check and pr-check now register through cli_policy_checks.py instead of wiring parser + handler logic directly inside cli.py.
Added cli_support.py for shared CLI-only output and required-check parsing, so evaluate / contract-pr reuse the same parser without keeping policy-check handlers in the godfile.
Added a boundary test so cli.py no longer imports IssueInput, PullRequestInput, evaluate_issue, or evaluate_pull_request directly.
Full verification before merge: 1049 passed, 163 subtests passed, plus self-dogfood checks green.

Remaining #254 work: continue moving command families out of cli.py, then apply the same contribution/registration pattern to operator_status.py. Keeping this issue open.

Progress update from Codex: - Second #254 slice landed via #257 / `afbc8b33`: `issue-check` and `pr-check` now register through `cli_policy_checks.py` instead of wiring parser + handler logic directly inside `cli.py`. - Added `cli_support.py` for shared CLI-only output and `required-check` parsing, so `evaluate` / `contract-pr` reuse the same parser without keeping policy-check handlers in the godfile. - Added a boundary test so `cli.py` no longer imports `IssueInput`, `PullRequestInput`, `evaluate_issue`, or `evaluate_pull_request` directly. - Full verification before merge: `1049 passed, 163 subtests passed`, plus self-dogfood checks green. Remaining #254 work: continue moving command families out of `cli.py`, then apply the same contribution/registration pattern to `operator_status.py`. Keeping this issue open.

codex referenced this issue

2026-06-26 13:52:31 +02:00

refactor(cli): register external contract commands outside godfile #258

codex commented

2026-06-26 13:54:30 +02:00

Collaborator

Progress update from Codex:

Third #254 slice landed via #258 / 5a7c127b: external-wiring-backlog-check and handoff-contracts now register through cli_external_contracts.py instead of wiring parser + handler logic directly inside cli.py.
Added a boundary test so cli.py no longer imports ExternalWiringBacklogInput, evaluate_external_wiring_backlog, handoff_contract_registry, or render_handoff_contract_registry directly.
Full verification before merge: 1050 passed, 163 subtests passed, plus self-dogfood checks green.

Remaining #254 work: continue moving command families out of cli.py, then apply the same contribution/registration pattern to operator_status.py. Keeping this issue open.

Progress update from Codex: - Third #254 slice landed via #258 / `5a7c127b`: `external-wiring-backlog-check` and `handoff-contracts` now register through `cli_external_contracts.py` instead of wiring parser + handler logic directly inside `cli.py`. - Added a boundary test so `cli.py` no longer imports `ExternalWiringBacklogInput`, `evaluate_external_wiring_backlog`, `handoff_contract_registry`, or `render_handoff_contract_registry` directly. - Full verification before merge: `1050 passed, 163 subtests passed`, plus self-dogfood checks green. Remaining #254 work: continue moving command families out of `cli.py`, then apply the same contribution/registration pattern to `operator_status.py`. Keeping this issue open.

codex referenced this issue

2026-06-26 14:31:47 +02:00

refactor(cli): register artifact root commands outside godfile #261

pdurlej referenced this issue from a commit

2026-06-26 14:33:18 +02:00

Merge pull request #261 from codex/cli-artifact-root-registration

codex commented

2026-06-26 14:33:50 +02:00

Collaborator

Progress update: merged PR #261 (9671df162a58) as another #254 slice.

Done in this slice:

moved the artifact-root manifest CLI family into src/patchwarden/cli_artifact_roots.py;
left cli.py as a registration consumer for those commands;
added a boundary test plus architecture inventory entry;
verified 1052 passed, 163 subtests passed before merge.

Remaining #254 scope: continue splitting the larger aggregation surfaces, especially operator_status, into per-module registration/inventory pieces.

Progress update: merged PR #261 (`9671df162a58`) as another #254 slice. Done in this slice: - moved the artifact-root manifest CLI family into `src/patchwarden/cli_artifact_roots.py`; - left `cli.py` as a registration consumer for those commands; - added a boundary test plus architecture inventory entry; - verified `1052 passed, 163 subtests passed` before merge. Remaining #254 scope: continue splitting the larger aggregation surfaces, especially `operator_status`, into per-module registration/inventory pieces.

codex referenced this issue

2026-06-26 14:44:31 +02:00

refactor(status): split dashboard read model from operator status #262

pdurlej referenced this issue from a commit

2026-06-26 14:45:49 +02:00

Merge pull request #262 from codex/operator-dashboard-model-split

codex commented

2026-06-26 14:46:16 +02:00

Collaborator

Progress update: merged PR #262 (4041524459c0) as the next #254 slice.

Done in this slice:

moved patchwarden.operator_dashboard_read_model.v1 construction into src/patchwarden/operator_dashboard_read_model.py;
kept operator_status.py as the status SSoT and renderer entry point;
added a boundary test so dashboard counters/maturity helpers do not drift back into operator_status.py;
updated architecture inventory;
verified 1053 passed, 163 subtests passed plus green self Forgejo checks before exact-head merge.

Remaining #254 scope: continue shrinking operator_status.py by moving additional status contributions/artifact drilldowns toward per-module registration.

Progress update: merged PR #262 (`4041524459c0`) as the next #254 slice. Done in this slice: - moved `patchwarden.operator_dashboard_read_model.v1` construction into `src/patchwarden/operator_dashboard_read_model.py`; - kept `operator_status.py` as the status SSoT and renderer entry point; - added a boundary test so dashboard counters/maturity helpers do not drift back into `operator_status.py`; - updated architecture inventory; - verified `1053 passed, 163 subtests passed` plus green self Forgejo checks before exact-head merge. Remaining #254 scope: continue shrinking `operator_status.py` by moving additional status contributions/artifact drilldowns toward per-module registration.

codex referenced this issue

2026-06-26 14:52:54 +02:00

refactor(status): split artifact drilldowns from operator status #263

pdurlej referenced this issue from a commit

2026-06-26 14:54:46 +02:00

Merge pull request #263 from codex/operator-artifact-drilldowns

codex commented

2026-06-26 14:55:17 +02:00

Collaborator

Progress update: merged PR #263 (c2b505096a93) as another #254 slice.

Done in this slice:

moved the operator status artifact drilldown catalog into src/patchwarden/operator_artifact_drilldowns.py;
kept operator_status.py as the status SSoT and renderer entry point;
reduced operator_status.py to 1424 lines in this worktree after the split;
added a boundary test so _artifact_drilldowns does not drift back into operator_status.py;
updated architecture inventory;
verified 1054 passed, 163 subtests passed plus green self Forgejo checks before exact-head merge.

Remaining #254 scope: continue converting the remaining status payload sections into per-module contributions/registries.

Progress update: merged PR #263 (`c2b505096a93`) as another #254 slice. Done in this slice: - moved the operator status artifact drilldown catalog into `src/patchwarden/operator_artifact_drilldowns.py`; - kept `operator_status.py` as the status SSoT and renderer entry point; - reduced `operator_status.py` to 1424 lines in this worktree after the split; - added a boundary test so `_artifact_drilldowns` does not drift back into `operator_status.py`; - updated architecture inventory; - verified `1054 passed, 163 subtests passed` plus green self Forgejo checks before exact-head merge. Remaining #254 scope: continue converting the remaining status payload sections into per-module contributions/registries.

codex referenced this issue

2026-06-26 15:05:32 +02:00

refactor(status): split external wiring backlog catalog #264

pdurlej referenced this issue from a commit

2026-06-26 15:06:54 +02:00

Merge pull request #264 from codex/operator-external-wiring-backlog

codex commented

2026-06-26 15:07:25 +02:00

Collaborator

Progress update: merged PR #264 (451ed88909f4) as another #254 slice.

Done in this slice:

moved the external wiring backlog catalog and source-command enrichment into src/patchwarden/operator_external_wiring_backlog.py;
removed external_wiring.py's dependency on operator_status.py;
reduced operator_status.py to 1266 lines in this worktree after the split;
added a boundary test that keeps EXTERNAL_WIRING_BACKLOG out of operator_status.py and keeps the checker importing the catalog directly;
updated architecture inventory;
verified 1055 passed, 163 subtests passed plus green self Forgejo checks before exact-head merge.

Remaining #254 scope: continue converting remaining status payload sections, especially dogfood wedge/status contribution data, into per-module contributions or registries.

Progress update: merged PR #264 (`451ed88909f4`) as another #254 slice. Done in this slice: - moved the external wiring backlog catalog and source-command enrichment into `src/patchwarden/operator_external_wiring_backlog.py`; - removed `external_wiring.py`'s dependency on `operator_status.py`; - reduced `operator_status.py` to 1266 lines in this worktree after the split; - added a boundary test that keeps `EXTERNAL_WIRING_BACKLOG` out of `operator_status.py` and keeps the checker importing the catalog directly; - updated architecture inventory; - verified `1055 passed, 163 subtests passed` plus green self Forgejo checks before exact-head merge. Remaining #254 scope: continue converting remaining status payload sections, especially dogfood wedge/status contribution data, into per-module contributions or registries.

codex referenced this issue

2026-06-26 15:16:52 +02:00

refactor(status): split dogfood wedge contribution #265

pdurlej referenced this issue from a commit

2026-06-26 15:18:19 +02:00

Merge pull request #265 from codex/operator-dogfood-wedge

codex commented

2026-06-26 15:19:10 +02:00

Collaborator

Progress update: merged PR #265 (24f6d9bf0c69) as another #254 slice.

Done in this slice:

moved the dogfood wedge status contribution into src/patchwarden/operator_dogfood_wedge.py;
kept operator_status.py as the status SSoT and renderer entry point;
reduced operator_status.py to 1216 lines in this worktree after the split;
added a boundary test so _dogfood_wedge does not drift back into operator_status.py;
updated architecture inventory;
verified 1056 passed, 163 subtests passed plus green self Forgejo checks before exact-head merge.

Remaining #254 scope: continue converting the remaining inline status payload sections, especially protection/passsage-layer catalogs, into per-module contributions or registries.

Progress update: merged PR #265 (`24f6d9bf0c69`) as another #254 slice. Done in this slice: - moved the dogfood wedge status contribution into `src/patchwarden/operator_dogfood_wedge.py`; - kept `operator_status.py` as the status SSoT and renderer entry point; - reduced `operator_status.py` to 1216 lines in this worktree after the split; - added a boundary test so `_dogfood_wedge` does not drift back into `operator_status.py`; - updated architecture inventory; - verified `1056 passed, 163 subtests passed` plus green self Forgejo checks before exact-head merge. Remaining #254 scope: continue converting the remaining inline status payload sections, especially protection/passsage-layer catalogs, into per-module contributions or registries.

codex referenced this issue

2026-06-26 15:28:40 +02:00

refactor(status): split passage contract layer catalog #266