Plan incremental AUTH module boundary recovery

[Abiorh001]

Workstream PR Trust Bundle

Chunk

WS-AUTH-003-PLAN - Incremental AUTH module-boundary recovery planning

Goal

Make app.modules.authorization.api the sole public AUTH boundary and eliminate private cross-module imports capability by capability.

Intent And Planning Context

• Intent: .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/INTENT.md
• Plan: .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/PLAN.md
• First chunk: .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/chunks/WS-AUTH-003-01-boundary-foundation.md

What Changed

• Defined the target AUTH public API and permanent dependency rules.
• Recorded exact bidirectional private-import debt.
• Chose a small foundation followed by capability repair, starting with POL-03A.
• Required fail-closed detection of static, wildcard, aliased, computed, and dynamic import bypasses.
• Required REV allow_reviews to begin only through clean AUTH and ART interfaces.
• Defined incremental test-structure recovery: one primary observable behavior per test, frozen measurable debt, assertion-parity maps, and no new skip/xfail paths.

Why It Changed

The modular-monolith rule already exists, but implementation accumulated direct imports in both directions. A single large rewrite is too difficult to verify; deferring enforcement allows more debt.

Design Chosen

Merge a minimal API/import/test-structure-gate foundation, then require each feature chunk to expose and migrate only the capability it touches while shrinking the exact ledger.

Alternatives Rejected

• Repository-wide AUTH rewrite: too broad to localize security regressions.
• Deferral until REV: deepens violations.
• Cosmetic file splitting: does not repair dependency direction.
• Permanent allowlists or compatibility aliases: preserve bypasses.

Scope Control

Only .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/** changed. No files are outside scope.

Product Behavior

• No Workstream product behavior changed.

Evidence

python3 scripts/check_stale_authorization_docs.py
python3 scripts/check_markdown_links.py
python3 scripts/check_stale_workstream_wording.py
git diff --check

All passed.

Acceptance Criteria Proof

• Inbound and outbound dependency debt is explicit.
• Foundation scope moves no runtime authorization behavior.
• Later capability repair must reduce touched debt.
• POL-03A is preserved as the first capability proof.
• REV cannot begin allow_reviews through a private import exception.

Test Delta

No tests were added, modified, removed, skipped, or weakened. This is planning only; the foundation contract requires architecture tests for both validators. Line limits are guardrails; semantic review enforces one primary behavior and assertion parity.

Internal Reviewer Results

Reviewed the original plan and the test-structure amendment through exact head 747291d9. All valid findings were addressed.

Reviewer	Result	Notes
Architecture	PASS AFTER FIXES	Added exact bidirectional debt gate and bounded AUTH test-debt scope.
QA/test	PASS AFTER FIXES	Named the frozen debt ledger and made validation exact.
Security/auth	PASS AFTER FIXES	Preserved atomic, replay, revocation, evidence, and concurrency proof.
Senior engineering	N/A	Planning-only; architecture owns maintainability review.
Product/ops	N/A	No product behavior changes.
CI integrity	Pending	Hosted checks rerunning.
Docs	N/A	Canonical documentation gates passed.
Reuse/dedup	N/A	No implementation abstraction added.
Test delta	PASS AFTER FIXES	Added enforceable assertion maps and complete skip/xfail rejection.

External Review

Source	Status	Notes
CodeRabbit	Addressed	Dynamic imports, exact edges, wording, and description corrected.
GitHub checks	Running	Exact head 747291d9.

CI And Gate Integrity

• No workflow, lint, test, coverage, package, or action weakening.
• Checkout settings unchanged.

Remaining Risks

The foundation freezes rather than removes current import and structural-test debt. Static size gates cannot prove cohesion, so required semantic reviews remain part of every capability repair. Every touched capability must shrink the ledger; final closure requires zero violations.

Follow-Up Work

1. Implement WS-AUTH-003-01.
2. Resume POL-03A and repair its exact AUTH boundary.
3. Continue capability-level repair during feature work.
4. Remove untouched legacy entries in final bounded cleanup.

Human Review Focus

Inspect whether the bidirectional ledger is exact, the foundation is behavior-neutral, and the test policy enforces one primary observable behavior without cosmetic splitting or weakened security proof.

Human Merge Ownership

• Change, rationale, and remaining risks are documented.
• The user explicitly approves this specific PR for merge.

[coderabbitai]

📝 Walkthrough

Walkthrough

This planning-only change defines AUTH module-boundary recovery. It adds the public API contract, consumer matrix, import-debt ledger, staged recovery plan, foundation chunk contract, status record, risk register, and implementation decisions.

Changes

AUTH boundary recovery

Layer / File(s)	Summary
Boundary intent and architectural contracts .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/INTENT.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/CONSUMER_API_MATRIX.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/DECISIONS.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/DISCOVERY.md	Defines the AUTH public API, consumer-specific contracts, prohibited dependencies, target architecture, preserved behavior, existing violations, and staged recovery decisions.
Import ledger and staged recovery plan .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/IMPORT_LEDGER.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/PLAN.md	Records current private-import debt and specifies incremental capability repair, dependency rules, verification requirements, and final ledger closure.
Foundation chunk and initiative controls .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/chunks/WS-AUTH-003-01-boundary-foundation.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/STATUS.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/CHUNK_MAP.md, .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/RISKS.md	Defines the initial validator and bounded authorization.api chunk, tracks implementation status and future chunks, and records recovery risks with controls.

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

Possibly related PRs

• Flow-Research/workstream#90: The plan preserves and requires boundary repair for the post-submit approval work from this PR.
• Flow-Research/workstream#91: Both PRs define AUTH authorization architecture and public API/import boundaries.
• Flow-Research/workstream#279: WS-AUTH-003 preserves and requires an AUTH API amendment for the related WS-POL-003 work.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: planning incremental AUTH module-boundary recovery.
Description check	✅ Passed	The description covers the goal, planning context, scope, design, evidence, risks, follow-up work, and review status for this planning-only PR.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-auth-boundary-recovery

---

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.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
@.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/chunks/WS-AUTH-003-01-boundary-foundation.md:
- Around line 41-47: Update the validator requirements in criterion 3 to
explicitly reject dynamic import APIs such as __import__ and
importlib.import_module, including aliased forms, alongside wildcard imports. If
supported dynamic forms are retained, define a closed allowlist and reject
unknown forms; add architecture tests covering these bypass cases and ensure the
validator fails closed.

In
@.agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/IMPORT_LEDGER.md:
- Line 68: Update the Line 68 ledger entry referencing
backend/app/workers/project_setup.py to use the repository’s current
human-worker vocabulary so check_stale_authorization_docs.py no longer reports
HUMAN_WORKER_VOCABULARY. Only modify the checker if this path is intentionally
canonical, and rerun the stale-documentation gate to verify it passes.
- Around line 3-11: Update the inbound debt sections in IMPORT_LEDGER.md to
record each exact source-to-private-AUTH-module import edge, rather than only
source filenames. Alternatively, add a machine-readable count or hash that the
validator compares, ensuring existing entries cannot conceal newly added private
AUTH imports and neither violation count increases.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c4c04fea-d883-404a-8138-d961ea30ba12

📥 Commits

Reviewing files that changed from the base of the PR and between 3565b3c and d2a2d67.

📒 Files selected for processing (10)

• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/CHUNK_MAP.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/CONSUMER_API_MATRIX.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/DECISIONS.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/DISCOVERY.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/IMPORT_LEDGER.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/INTENT.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/PLAN.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/RISKS.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/STATUS.md
• .agent-loop/initiatives/WS-AUTH-003-module-boundary-recovery/chunks/WS-AUTH-003-01-boundary-foundation.md