docs(arch): plan incremental debt retirement

[Abiorh001]

What changed

• codifies delivery-coupled technical-debt retirement under WS-ARCH-001
• blocks new debt while keeping unrelated frozen debt non-blocking for v0.1 delivery
• requires directly touched debt to shrink and makes any unsafe deferral durable and owner-bound
• preserves WS-AUTH-003 and WS-QUAL-002 ownership instead of creating a competing cleanup initiative
• corrects stale merged PLAN3 state wording

Why

The existing incremental strangler principle did not state precisely what a feature PR must repair versus what can remain frozen. This plan prevents both blanket cleanup gates and indefinite debt growth.

Impact

Planning and documentation only. No backend, schema, CI, authorization, or product behavior changes. WS-ARCH-001-07 remains non-executable and current v0.1 capability work may continue.

Validation

• Markdown links
• stale Workstream wording
• stale authorization docs
• chunk-state synchronization
• git diff check
• architecture review: pass
• senior engineering review: pass
• docs review: pass

Summary by CodeRabbit

• Documentation
  • Clarified the planned sequencing and status of architecture work.
  • Added incremental technical-debt retirement guidelines, including debt classifications, deferral requirements, and safeguards against introducing new debt.
  • Documented acceptance criteria, verification steps, review focus, and ownership for future debt cleanup.
  • Added risk tracking and updated initiative status to reflect the new planned work.

[coderabbitai]

Warning

Review limit reached

@Abiorh001, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 112 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 55c503fe-cc0c-4e14-8ff7-0be1c219d028

📥 Commits

Reviewing files that changed from the base of the PR and between 4220546 and f68f469.

📒 Files selected for processing (1)

• .agent-loop/CURRENT_STATE.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 28e2f882-8932-4b13-937b-ed55812d128c

📥 Commits

Reviewing files that changed from the base of the PR and between 9d1a714 and 4220546.

📒 Files selected for processing (7)

• .agent-loop/CURRENT_STATE.md
• .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md
• .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md
• .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md
• .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md
• .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md
• .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md

---

📝 Walkthrough

Walkthrough

WS-ARCH-001 documentation now classifies PLAN3 as planned and non-runtime, adds PLAN4, and defines incremental technical-debt retirement rules, ownership, baselines, acceptance criteria, and closure conditions.

Changes

WS-ARCH-001 planning updates

Layer / File(s)	Summary
PLAN3 and PLAN4 sequencing .agent-loop/CURRENT_STATE.md, .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/CHUNK_MAP.md, .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/STATUS.md	PLAN3 is marked as planned and planning-only. PLAN4 is added for delivery-coupled debt retirement. CP01–CP09 sequencing now uses each child’s current-main contract.
Debt-retirement policy and ownership .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/DECISIONS.md, .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/PLAN.md, .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/RISKS.md	The documentation defines debt classifications, same-PR removal for directly touched debt, documented deferrals, authoritative ledgers, coverage rules, closure ownership, and related risks.
PLAN4 chunk contract .agent-loop/initiatives/WS-ARCH-001-modular-monolith-boundaries/chunks/WS-ARCH-001-PLAN4-incremental-debt-retirement.md	The new chunk contract defines PLAN4 scope, baselines, restrictions, acceptance criteria, verification commands, review responsibilities, stop conditions, and planned merge state. It adds no runtime or CI behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 42205

This documentation-only change does not alter backend, schema, CI, authorization, or product behavior, and no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• Flow-Research/workstream#302: Introduced related engineering-state documentation that this PR updates.
• Flow-Research/workstream#310: Established related WS-ARCH-001 boundary and debt-ledger planning.
• Flow-Research/workstream#330: Added the PLAN3 and CP01–CP09 sequencing that this PR refines.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the change and impact but omits most required template sections, including scope, evidence, acceptance proof, test delta, risks, and reviewer results.	Complete the required trust-bundle sections and provide commands, results, acceptance-criteria proof, test delta, remaining risks, follow-up work, and review statuses.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the documentation change to plan incremental technical-debt retirement.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-arch-001-plan4-incremental-debt-retirement

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}