diff --git a/.agent-loop/CURRENT_STATE.md b/.agent-loop/CURRENT_STATE.md index f98fbc9f3..07fb65235 100644 --- a/.agent-loop/CURRENT_STATE.md +++ b/.agent-loop/CURRENT_STATE.md @@ -28,7 +28,7 @@ authority; these records do not grant or withhold it. | Initiative | Durable state on `main` | Remaining boundary | |---|---|---| -| [WS-ARCH-001](initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md) | Complete through `WS-ARCH-001-02H`, including hidden preparation and atomic consumption/binding activation | PLAN2 binds one ContributionPolicyVersion at guide activation, locks it on TASK before claimability, carries it through assignment and 04E `allow_review`, then requires REV lease inheritance and atomic CON contribution/award participation; `02I` remains later | +| [WS-ARCH-001](initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md) | Complete through `WS-ARCH-001-02H`, including hidden preparation and atomic consumption/binding activation | PLAN2 binds one ContributionPolicyVersion at guide activation, locks it on TASK before claimability, carries it through assignment and 04E `allow_review`, then requires REV lease inheritance and atomic CON contribution/award participation; [WS-ARCH-001-PLAN4](initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md) is planned on merge and makes debt retirement delivery-coupled without blocking a feature on unrelated frozen debt; `02I` remains later | | [WS-ART-001](initiatives/WS-ART-001-immutable-artifact-storage/STATUS.md) | Active delivery initiative; verified ready-admission publication, hidden preparation, consumption and binding are merged through ARCH-02H | Implement exact post-submit materialization only after the unified guide/checker and PLAN2 public contracts are executable; live cutover remains later | | [WS-AUTH-001](initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md) | Active delivery initiative; project-policy authority and unified compilation authorization are merged through `12I` | POL-03B consumes 12I next; remaining AUTH activation chunks wait for their exact hidden owner behavior | | [WS-CON-001](initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md) | Active delivery initiative; ContributionPolicy persistence and shared lifecycle audit are merged | Complete the guide-activation validation/persistence contract before task readiness; assignment copies the task lock, Submission stamps the attempt version, and ReviewLease copies that stamp without claim-time lookup; ContributionRecord/CompensationAward persistence plus the atomic participant precede live Review decisions | @@ -93,15 +93,15 @@ Merged WS-CON-001-PLAN5 remains historical evidence for same-TaskAssignment human revision rebase; current PLAN2 supersedes its independent reviewer-policy selection wording. -## Proposed PLAN3 correction +## Planned PLAN3 correction -Do not start historical CON-05A directly. The proposed CP01-CP09 sequence owns +Do not start historical CON-05A directly. The planned CP01-CP09 sequence owns AUTH unavailable registration, hidden CON binding/policy behavior, exact AUTH activations, CON validation, PROJECT guide binding, TASK attempt lineage, and clean v0.1 legacy economic-path removal in that order. Every child remains -non-executable until PLAN3 merges and its current-main contract is expanded. +non-executable until its current-main contract is expanded. -- WS-ARCH-001-PLAN3 is proposed planning only. +- WS-ARCH-001-PLAN3 is planned; its planning merge changed no runtime behavior. - WS-ARCH-001-CP01 is a planned split and non-executable. - WS-ARCH-001-CP01A is complete on merge with adapter-binding actions registered but unavailable. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md index f4f5bf6f0..7c528f3ed 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md @@ -15,7 +15,8 @@ | `WS-ARCH-001-02H` | AUTH human/fixed-service consumption activation | L1 | Complete on merge; public route remains unchanged | | `WS-ARCH-001-02I` | Admission-only public API/dispatch cutover and complete legacy removal | L1 | Deferred after 02H plus split 03/04/05 remediation, revision, checker-output and REV admission prerequisites | | `WS-ARCH-001-PLAN2` | Current-main reconciliation around canonical Submission-to-`allow_review` | L1 | Planned; planning contract lands on merge | -| `WS-ARCH-001-PLAN3` | ContributionPolicy registration, behavior, activation, guide/task lineage and clean legacy-removal sequencing | L1 | Proposed planning correction; no runtime | +| `WS-ARCH-001-PLAN3` | ContributionPolicy registration, behavior, activation, guide/task lineage and clean legacy-removal sequencing | L1 | Planned; planning correction only and no runtime | +| `WS-ARCH-001-PLAN4` | Delivery-coupled technical-debt retirement policy and current-main baseline | L1 | Planned on merge; planning only and no unrelated v0.1 delivery block | | `WS-ARCH-001-CP01` | Combined AUTH registration planning parent | L1 | Planned split into CP01A/CP01B; non-executable | | `WS-ARCH-001-CP01A` | AUTH adapter-binding unavailable registration | L1 | Complete on merge; four actions remain planned/unavailable | | `WS-ARCH-001-CP01B` | AUTH ContributionPolicy unavailable registration | L1 | Complete on merge; five actions remain planned/unavailable | @@ -54,3 +55,8 @@ each must be replaced with a current-main contract that names exact allowed and not-allowed files, migration head, runnable commands, reviewers, and the public types it extends. Their sequencing is approved here; their current text does not authorize code changes. + +PLAN4 does not insert a new prerequisite into the product sequence. Each +current or future delivery chunk applies its no-new-debt and touched-debt rules +within the capability it already owns. WS-ARCH-001-07 is refreshed and split +only for stranded debt after remaining v0.1 delivery boundaries are known. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md index 9d5bf7d07..8d6f7190c 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md @@ -133,3 +133,17 @@ The consolidated baseline is the current schema authority. The retired guide-bound economic path is removed only after canonical lineage is live, with no alias, fallback, dual read/write, guessed conversion, or historical backfill unless future discovery proves an actual deployed-data obligation. + +## D18: Debt retirement follows delivery without blocking unrelated work + +New architectural and test debt is prohibited. A capability change removes the +existing debt it directly exercises, but unrelated frozen debt is not a merge +prerequisite. When safe removal would enlarge the approved product or safety +boundary, the exact stranded debt is recorded for a later owner-sized closure +chunk and cannot grow in the meantime. Repository-wide cleanup, arbitrary +per-PR quotas, and cosmetic test splitting are rejected. + +WS-ARCH-001 remains the general boundary owner, WS-AUTH-003 remains the AUTH +boundary and structural-debt owner, and WS-QUAL-002 remains the behavior/test +ownership authority. Their ledgers are reported independently where their +measurements overlap. diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md index d9283ca2b..1fe81b797 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md @@ -50,6 +50,59 @@ feature contract touching `artifacts`, `authorization`, `projects`, `tasks`, - proof that debt does not grow; - behavior, transaction, authorization, replay, and denial preservation. +## Incremental debt-retirement policy + +Technical debt is repaid through the capability work that encounters it. It is +not a repository-wide prerequisite for v0.1 delivery, and unrelated frozen debt +cannot block a bounded feature PR. + +Every implementation contract classifies its relationship to existing debt: + +1. **No relevant debt:** prove that the change adds no private edge, structural + violation, duplicated behavior owner, weakened test, or compatibility path. +2. **Directly touched debt:** when the change modifies or continues through a + protected private edge, oversized function, or behavior-owning test surface, + it must retire the relevant debt in the same PR. The proof names the exact + ledger entries or structural findings removed. +3. **Adjacent debt unsafe to remove:** when removal would broaden the product, + transaction, authorization, migration, or concurrency boundary beyond the + approved chunk, the PR records the exact debt and why removal is unsafe. It + may merge only if the debt does not grow and the changed capability no + longer introduces new work through that debt. A later capability-sized + contract owns the stranded repair. + +A deferral is durable initiative memory, not PR prose alone. It records the +exact ledger source/target edge or structural-finding identifier, owning +initiative, reason the repair exceeds the chunk, and intended owner-capability +contract or refreshed WS-ARCH-001-07 closure boundary. + +No arbitrary percentage, edge quota, or line-count quota applies to every PR. +Those quotas encourage unrelated edits and make review less reliable. The +binding rules are exact: no new debt, meaningful retirement of directly +touched debt, and no test weakening or cosmetic file splitting. + +Relevant trust bundles report before/after values from the authoritative +ledgers without adding overlapping ledgers together: + +- general protected private edges from + `.ci/module-boundaries/private-edge-debt.v1.json`; +- AUTH inbound/outbound private edges from the WS-AUTH-003 import ledger when + AUTH is touched; +- scoped structural findings from the WS-AUTH-003 test-structure ledger when + an indexed file is touched; +- behavior-ownership records added or updated under WS-QUAL-002. + +The repository-wide 78 percent coverage floor and the 90 percent floor for new +or materially changed backend subsystems remain blocking. Mutation testing is +not a current merge requirement; any future changed-line-aware mutation gate +requires its own approved WS-QUAL plan. + +After active v0.1 capability delivery, WS-ARCH-001-07 is refreshed against +current `main` and split by owner to remove only stranded debt that no remaining +delivery chunk will naturally encounter. Final closure requires empty general +and AUTH private-edge ledgers. Test-structure and behavior-ownership completion +remain owned by WS-AUTH-003 and WS-QUAL-002 respectively. + ## Submission capability correction Before contributor preparation activation or ART-05A replacement behavior: diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md index a2d157958..3d9576d56 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md @@ -28,3 +28,7 @@ | Binding management inherits retirement, fulfillment, callback, or delivery authority | Critical | CP01A through CP03 exclude retirement actions plus fulfillment, callback, and delivery action IDs, permissions, identities, routes, evaluators, and service-matrix rows entirely | | CON writes PROJECT or TASK aggregates | Critical | CP06 returns immutable validation facts only; CP07 and CP08 own their respective writes | | Consolidated v0.1 schema gains fake compatibility debt | High | CP09 performs a clean current-baseline cut and forbids aliases, dual paths, and invented backfills | +| Legacy debt becomes a blanket blocker for v0.1 delivery | High | Block new debt and require directly touched debt to shrink; never require unrelated frozen debt in a bounded feature PR | +| Debt repayment expands a feature beyond a reviewable safety boundary | High | Record exact stranded debt, prove no growth, and create a later owner-sized closure contract rather than mixing product boundaries | +| Mechanical quotas reward noisy or cosmetic cleanup | Medium | Use exact edge/finding deltas and behavior ownership; prohibit arbitrary per-PR percentages and cosmetic test splitting | +| Overlapping ledgers are added together and misstate debt | Medium | Report general, AUTH, structural, and behavior-ownership measurements separately under their existing owners | diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md index ebb44946c..b97df0ba3 100644 --- a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md @@ -54,10 +54,18 @@ non-executable split parent; CP01A is complete on merge with its four actions registered/unavailable, CP01B is complete on merge with five policy actions registered/unavailable, and CP02-CP09 remain non-executable skeletons. +- [WS-ARCH-001-PLAN4](chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md) is planned on merge + and changes no runtime. It makes the existing incremental strangler + operational: unrelated frozen debt cannot block delivery, new debt is + prohibited, directly touched debt must shrink, and unsafe adjacent debt is + recorded for a later owner-sized closure without widening the feature PR. + Current baselines are 115 general protected private edges, 99 AUTH-ledger + edges reported separately, and 89 AUTH structural findings. These measures + overlap and are never summed into one repository total. -## Proposed PLAN3 children +## Planned PLAN3 children -- WS-ARCH-001-PLAN3 is proposed planning only; runtime behavior is unchanged. +- WS-ARCH-001-PLAN3 is planned; its planning merge changed no runtime behavior. - WS-ARCH-001-CP01 is a planned split and non-executable. Current-main discovery proved adapter binding and ContributionPolicy are distinct resource/action families. - WS-ARCH-001-CP01A is complete on merge: exact adapter-binding identifiers, diff --git a/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md new file mode 100644 index 000000000..a0bb9757e --- /dev/null +++ b/.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md @@ -0,0 +1,109 @@ +# Chunk Contract: WS-ARCH-001-PLAN4 — Incremental Debt Retirement + +## Parent initiative + +WS-ARCH-001 — Modular Monolith Boundaries + +## Goal + +Make technical-debt retirement measurable and delivery-coupled without turning +unrelated legacy debt into a prerequisite for v0.1 capability work. + +## Why this chunk exists + +The architecture already requires an incremental strangler, but contributors +need an exact rule for what a bounded PR must repair, what it must merely avoid +growing, and what belongs to later stranded-debt closure. Without that split, +the rule can either permit debt indefinitely or expand every feature into an +unreviewable cleanup. + +## Current-main baseline + +- General protected private-edge ledger: 115 exact edges. +- WS-AUTH-003 import ledger: 63 inbound and 36 outbound AUTH private edges. +- WS-AUTH-003 structural ledger: 89 findings across production and test files, + functions, and helpers. +- WS-QUAL-002 behavior ownership: foundation exists; subsystem population is + incomplete. + +The general and AUTH import ledgers have different authorities and overlapping +views. Their counts are reported separately and must not be summed. + +## Approved plan reference + +- INTENT: `../INTENT.md` +- PLAN: `../PLAN.md` +- CHUNK_MAP: `../CHUNK_MAP.md` +- DECISIONS: `../DECISIONS.md#d18-debt-retirement-follows-delivery-without-blocking-unrelated-work` + +## Risk class + +L1 + +## Allowed files + +```text +.agent-loop/CURRENT_STATE.md +.agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/** +``` + +## Not allowed + +```text +backend application, migration, test, workflow, or dependency changes +product behavior, authority, schema, lifecycle, or public API changes +a new cleanup initiative or a competing debt ledger +fixed per-PR debt quotas or repository-wide cleanup prerequisites +mutation or coverage gate changes +``` + +## Acceptance criteria + +- [ ] Unrelated frozen debt is explicitly non-blocking for bounded v0.1 work. +- [ ] New private edges, structural debt, duplicated behavior ownership, + compatibility paths, and weakened tests remain prohibited. +- [ ] A PR directly exercising indexed debt must identify and remove its exact + relevant entries in the same capability boundary. +- [ ] Unsafe adjacent debt may be deferred only with an exact record, no + growth, and a later owner-sized closure boundary. The durable initiative + record names the ledger edge or structural-finding identifier, owner, reason + removal exceeds the chunk, and intended closure contract. +- [ ] General, AUTH, structural, and behavior-ownership measurements retain + their existing authoritative owners and are never combined misleadingly. +- [ ] Existing 78 percent global and 90 percent changed-subsystem coverage + floors remain unchanged; mutation remains outside the current merge gates. +- [ ] WS-ARCH-001-07 remains non-executable until refreshed against then-current + `main` and split into reviewable stranded-debt contracts. +- [ ] No runtime or CI behavior changes. + +## Verification commands + +```bash +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_stale_authorization_docs.py +python3 scripts/check_chunk_state_sync.py --base-ref "$(git merge-base HEAD origin/main)" +git diff --check +``` + +## Required reviewers + +- [ ] architecture +- [ ] senior engineering +- [ ] docs + +## Human review focus + +Confirm that the policy prevents new debt and retires debt encountered by +delivery without making unrelated historical debt a feature prerequisite. + +## Stop conditions + +Stop if the plan changes product behavior, weakens a test or CI gate, creates a +second debt authority, or makes repository-wide cleanup a delivery gate. + +## Merge state + +- Outcome on merge: `planned` +- Implementation starts only through an approved capability contract; this + planning PR does not start WS-ARCH-001-07.