docs(arch): core boundaries, governance, doc.go archtest, enterprise extension boundaries (Phase 5 + 7)

[matdev83]

Summary

• Executes Phase 5 (core boundary tightening) + Phase 7 (governance and long-term maintenance).
• Phase 5: docs/core-boundaries.md classifies all 35 internal/core/* packages by role (use-case orchestration / policy / state seam / canonical contract / support) with adapter-leakage risk. The 6-question core admission checklist is included. TestCorePackagesHaveDocGo archtest requires every core package to have doc.go (14 added for packages that lacked one).
• Phase 7: Architecture PR checklist added to docs/architecture-guardrails.md. CI arch-report artifact upload added to .github/workflows/qa.yml (advisory, non-failing, continue-on-error). docs/enterprise-extension-boundaries.md defines allowed (pkg/lipsdk facades, BuildOptions, control-plane ports, hook bus, secure-session authority) and forbidden (editing runtime.Executor, importing deep runtime internals, forking the composition root) enterprise integration points.
• No behavior change; docs + archtest + CI only.

Test plan

• TestCorePackagesHaveDocGo passes (all 33 core packages with .go files have doc.go)
• make quality-checks (gofmt, tidy, build, vet, goroutine allowlist, regex hotpath, archtest)
• make test-unit (zero failing packages)
• Reviewer: confirm the 14 new doc.go files have accurate one-line package descriptions

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 42 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1bbc72c9-7700-48a9-a156-1b6d59f5beab

📥 Commits

Reviewing files that changed from the base of the PR and between d7829de and 3bbbe9a.

📒 Files selected for processing (3)

• docs/architecture-guardrails.md
• docs/core-boundaries.md
• internal/archtest/core_docgo_test.go

📝 Walkthrough

Walkthrough

This PR adds architecture governance documentation (core-boundaries.md, enterprise-extension-boundaries.md, and updates to architecture-guardrails.md), a new archtest enforcing doc.go presence in internal/core packages, doc.go files for fourteen existing core packages, and a QA workflow step that generates and uploads an architecture report artifact.

Changes

Core boundary governance and enforcement

Layer / File(s)	Summary
Architecture guardrails and boundary documentation docs/architecture-guardrails.md, docs/core-boundaries.md, docs/enterprise-extension-boundaries.md	Adds core admission checklist, architecture PR checklist, enterprise extension boundaries section, a package classification table, contributor admission checklist, and enterprise seam/forbidden integration rules.
doc.go enforcement test internal/archtest/core_docgo_test.go	Adds TestCorePackagesHaveDocGo, scanning internal/core subdirectories for non-test Go files and asserting each has a doc.go.
doc.go files for core packages internal/core/accounting/doc.go, internal/core/affinity/doc.go, internal/core/auxreq/doc.go, internal/core/execbackend/doc.go, internal/core/interleavedstate/doc.go, internal/core/interleavedthinking/doc.go, internal/core/jsonpresence/doc.go, internal/core/leglifecycle/doc.go, internal/core/lineage/doc.go, internal/core/modelregistry/doc.go, internal/core/policy/doc.go, internal/core/streamrecovery/doc.go, internal/core/traffic/doc.go, internal/core/workspace/doc.go	Adds package-level documentation comments and package declarations satisfying the new doc.go archtest.

QA Workflow Architecture Report

Layer / File(s)	Summary
Architecture report generation and upload .github/workflows/qa.yml	Adds a step to run make arch-report (allowed to fail) and a step to always upload the generated report as an arch-report artifact.

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

Related issues: None specified.

Related PRs: None specified.

Suggested labels: documentation, architecture, ci

Suggested reviewers: matdev83

🐰 A doc.go here, a doc.go there,
Fourteen packages now declare;
Guardrails drawn in careful lines,
Enterprise stays behind its signs,
While QA quietly reports the shape,
Of architecture, no escape.

🚥 Pre-merge checks | ✅ 8

✅ Passed checks (8 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the PR’s architecture docs, archtest, and governance changes.
Description check	✅ Passed	The description matches the PR scope and describes the docs, CI, and archtest updates.
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.
No Secrets	✅ Passed	No hardcoded creds, keys, passwords, private keys, or sensitive URLs appear in the PR diff; changes are docs, archtest, and CI plumbing.
Context Propagation	✅ Passed	PASS: touched CLI/runtime code keeps cancelable contexts and timeout bounds; Bedrock init defers cancel, and no new goroutines were added in changed source files.
No Accidental Public Api Break	✅ Passed	PASS: diff only touches cmd/, internal/, docs, and CI; no pkg/** files or exported public package signatures changed, so no public API break.

---

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: 4

🤖 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 @.github/workflows/qa.yml:
- Line 33: The workflow uses actions/upload-artifact@v4 by tag instead of a
pinned commit SHA, which static analysis flags as an unpinned action reference.
If supply-chain hardening is desired, update the upload-artifact step to use a
specific commit SHA and keep it aligned with the existing pinned-action
convention used in this workflow.

In `@docs/architecture-guardrails.md`:
- Around line 53-57: The admission checklist text overstates the scope of
TestCorePackagesHaveDocGo, since that archtest only applies to immediate
internal/core/* packages with top-level non-test Go files, not nested packages
like internal/core/securesession/app. Update the wording in the architecture
guardrails doc to say “top-level core packages” wherever the test coverage is
described, or broaden the test first if you want to keep claiming all core
packages are covered. Keep the references aligned with docs/core-boundaries.md
and TestCorePackagesHaveDocGo.

In `@docs/core-boundaries.md`:
- Around line 3-17: The package classification table in core-boundaries is
incomplete because it only lists top-level internal/core packages and omits
nested packages, so update the document to either explicitly scope it to
immediate children or add the missing nested entries. Use the existing
classification table in docs/core-boundaries.md and ensure nested symbols such
as internal/core/securesession/app, internal/core/tokenaccounting/app, and
internal/core/runtime/failclosed are covered so the admission checklist includes
them.

In `@internal/archtest/core_docgo_test.go`:
- Around line 24-40: Handle the per-directory os.ReadDir failure in
core_docgo_test.go instead of discarding it. In the loop that builds dir and
reads subEntries, capture the error from os.ReadDir(dir) and fail the test with
t.Fatal/t.Fatalf so unreadable directories do not get silently skipped. Keep the
change localized to the directory scan logic around the subEntries read and the
hasNonTestGo check.

🪄 Autofix (Beta)

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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9ce03eeb-1f41-4f17-9656-abba649d8417

📥 Commits

Reviewing files that changed from the base of the PR and between a52adf1 and d7829de.

📒 Files selected for processing (19)

• .github/workflows/qa.yml
• docs/architecture-guardrails.md
• docs/core-boundaries.md
• docs/enterprise-extension-boundaries.md
• internal/archtest/core_docgo_test.go
• internal/core/accounting/doc.go
• internal/core/affinity/doc.go
• internal/core/auxreq/doc.go
• internal/core/execbackend/doc.go
• internal/core/interleavedstate/doc.go
• internal/core/interleavedthinking/doc.go
• internal/core/jsonpresence/doc.go
• internal/core/leglifecycle/doc.go
• internal/core/lineage/doc.go
• internal/core/modelregistry/doc.go
• internal/core/policy/doc.go
• internal/core/streamrecovery/doc.go
• internal/core/traffic/doc.go
• internal/core/workspace/doc.go

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: qa

🧰 Additional context used

📓 Path-based instructions (5)

**/*.go

📄 CodeRabbit inference engine (Custom checks)

**/*.go: For server, CLI, worker, or network Go code, ensure context.Context is propagated correctly, cancellation is respected, and new goroutines cannot leak indefinitely.
Do not make accidental public API breaks in Go code: under pkg/** or anywhere exported Go identifiers are changed, warn if the PR changes exported types, function signatures, error behavior, JSON fields, CLI flags, config keys, or documented behavior without clearly explaining the compatibility impact.

Files:

• internal/core/lineage/doc.go
• internal/core/streamrecovery/doc.go
• internal/core/interleavedstate/doc.go
• internal/core/leglifecycle/doc.go
• internal/core/policy/doc.go
• internal/core/execbackend/doc.go
• internal/core/modelregistry/doc.go
• internal/core/accounting/doc.go
• internal/core/traffic/doc.go
• internal/core/workspace/doc.go
• internal/core/jsonpresence/doc.go
• internal/core/auxreq/doc.go
• internal/core/affinity/doc.go
• internal/core/interleavedthinking/doc.go
• internal/archtest/core_docgo_test.go

---

⚙️ CodeRabbit configuration file

**/*.go: Review as production Go code. Prioritize correctness, race conditions, goroutine leaks, context cancellation, timeout handling, error wrapping, nil-pointer risks, resource cleanup, defer placement, API compatibility, interface design, dependency boundaries, and testability. Avoid generic style comments when gofmt/golangci-lint already covers the issue.

Files:

• internal/core/lineage/doc.go
• internal/core/streamrecovery/doc.go
• internal/core/interleavedstate/doc.go
• internal/core/leglifecycle/doc.go
• internal/core/policy/doc.go
• internal/core/execbackend/doc.go
• internal/core/modelregistry/doc.go
• internal/core/accounting/doc.go
• internal/core/traffic/doc.go
• internal/core/workspace/doc.go
• internal/core/jsonpresence/doc.go
• internal/core/auxreq/doc.go
• internal/core/affinity/doc.go
• internal/core/interleavedthinking/doc.go
• internal/archtest/core_docgo_test.go

**/*

📄 CodeRabbit inference engine (Custom checks)

Do not introduce hardcoded credentials, API keys, tokens, private keys, passwords, production secrets, or sensitive internal URLs.

Files:

• internal/core/lineage/doc.go
• internal/core/streamrecovery/doc.go
• internal/core/interleavedstate/doc.go
• docs/enterprise-extension-boundaries.md
• internal/core/leglifecycle/doc.go
• internal/core/policy/doc.go
• internal/core/execbackend/doc.go
• internal/core/modelregistry/doc.go
• internal/core/accounting/doc.go
• internal/core/traffic/doc.go
• internal/core/workspace/doc.go
• internal/core/jsonpresence/doc.go
• docs/core-boundaries.md
• internal/core/auxreq/doc.go
• internal/core/affinity/doc.go
• internal/core/interleavedthinking/doc.go
• internal/archtest/core_docgo_test.go
• docs/architecture-guardrails.md

internal/**

⚙️ CodeRabbit configuration file

internal/**: Focus on package boundaries, hidden coupling, unexported API design, concurrency safety, deterministic behavior, and whether logic belongs in this internal package.

Files:

• internal/core/lineage/doc.go
• internal/core/streamrecovery/doc.go
• internal/core/interleavedstate/doc.go
• internal/core/leglifecycle/doc.go
• internal/core/policy/doc.go
• internal/core/execbackend/doc.go
• internal/core/modelregistry/doc.go
• internal/core/accounting/doc.go
• internal/core/traffic/doc.go
• internal/core/workspace/doc.go
• internal/core/jsonpresence/doc.go
• internal/core/auxreq/doc.go
• internal/core/affinity/doc.go
• internal/core/interleavedthinking/doc.go
• internal/archtest/core_docgo_test.go

.github/workflows/**

⚙️ CodeRabbit configuration file

.github/workflows/**: Review CI changes for Go version consistency, caching correctness, reproducibility, permissions minimization, race detector usage where appropriate, and whether tests/linting actually run on pull requests.

Files:

• .github/workflows/qa.yml

**/*_test.go

⚙️ CodeRabbit configuration file

**/*_test.go: Review tests for meaningful assertions, table-driven coverage, race-prone tests, t.Parallel misuse, nondeterminism, leaked goroutines, real network or filesystem dependencies, fragile sleeps, and missing edge cases. Prefer testing observable behavior over implementation details.

Files:

• internal/archtest/core_docgo_test.go

🧠 Learnings (1)

📚 Learning: 2026-07-01T22:57:42.953Z

Learnt from: matdev83
Repo: matdev83/go-llm-interactive-proxy PR: 101
File: pkg/lipsdk/scope/context.go:0-0
Timestamp: 2026-07-01T22:57:42.953Z
Learning: In this repository, when defining unexported Go `context` key constants of type `ctxKey int` (e.g., `const ( kFoo ctxKey = iota + N )`), preserve the `iota + <offset>` pattern and keep the existing `<offset>` values rather than simplifying to plain `iota`. These per-package offsets are part of the repo-wide convention to avoid key collisions across packages, and each such constant set should include a short explanatory comment (for example: “offset avoids collision with other packages' context keys”).

Applied to files:

• internal/core/lineage/doc.go
• internal/core/streamrecovery/doc.go
• internal/core/interleavedstate/doc.go
• internal/core/leglifecycle/doc.go
• internal/core/policy/doc.go
• internal/core/execbackend/doc.go
• internal/core/modelregistry/doc.go
• internal/core/accounting/doc.go
• internal/core/traffic/doc.go
• internal/core/workspace/doc.go
• internal/core/jsonpresence/doc.go
• internal/core/auxreq/doc.go
• internal/core/affinity/doc.go
• internal/core/interleavedthinking/doc.go
• internal/archtest/core_docgo_test.go

🪛 LanguageTool

docs/enterprise-extension-boundaries.md

[grammar] ~34-~34: Ensure spelling is correct
Context: ...ildOptions.Extensions.CompletionGates; BuildOptions.Policy.PolicyTimeoutBudgetSource`. | | Custom backends | Backend plugin v...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 zizmor (1.26.1)

.github/workflows/qa.yml

[error] 33-33: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🔇 Additional comments (13)

.github/workflows/qa.yml (1)

25-38: Advisory report/upload logic is sound.

The continue-on-error: true on the generation step plus if: always() and the default if-no-files-found: warn behavior on actions/upload-artifact@v4 together ensure this stays non-failing even if make arch-report errors out or produces no file, matching the PR's stated advisory intent.

docs/architecture-guardrails.md (1)

58-71: LGTM!

docs/enterprise-extension-boundaries.md (1)

1-46: LGTM!

internal/core/streamrecovery/doc.go (1)

1-2: LGTM!

internal/core/traffic/doc.go (1)

1-2: LGTM!

internal/core/workspace/doc.go (1)

1-2: LGTM!

internal/core/accounting/doc.go (1)

1-1: 📐 Maintainability & Code Quality | ⚡ Quick win

Garbled package comment.

// Package accounting Usage accounting price catalog and cost estimation. reads as broken English (redundant "accounting"/"Usage" mid-sentence), unlike the sibling doc.go files (e.g. leglifecycle, lineage, modelregistry, policy) which use clean noun-phrase descriptions. Since this PR's purpose is documentation quality, this comment should be cleaned up.

✏️ Proposed fix

-// Package accounting Usage accounting price catalog and cost estimation.
+// Package accounting provides usage accounting, price catalog, and cost estimation.
 package accounting

internal/core/affinity/doc.go (1)

1-2: LGTM!

internal/core/auxreq/doc.go (1)

1-2: LGTM!

internal/core/execbackend/doc.go (1)

1-2: LGTM!

internal/core/interleavedstate/doc.go (1)

1-2: LGTM!

internal/core/interleavedthinking/doc.go (1)

1-2: LGTM!

internal/core/jsonpresence/doc.go (1)

1-2: LGTM!