fix: complete all P3 audit findings — empty modules, docs drift, detekt, worktree
P3-1: Delete 17 empty Gradle modules (core:agents/observability/policies/stages,
infrastructure:scheduler/security/telemetry, all 7 plugins/*, all 3
interfaces/*). Zero source files, zero dependents, identical build.gradle
stubs. Remove from settings.gradle. Keep .adoc spec docs as roadmap refs.
P3-2: Fix docs drift — rename :core:orchestration to :core:kernel in
core-orchestration-submodule-spec.md, rewrite stale chat-transcript
modules-and-spec.md as proper doc.
(CLAUDE.md Router context isolation clarification is local-only,
file is gitignored.)
P3-3: Reduce detekt maxIssues from 999999 to 120 (actual current count ~107).
(CLAUDE.md detekt description updated locally; file is gitignored.)
P3-4: Remove stale locked worktree agent-a98d45277ce4b0040 (contained only
cosmetic test style changes and an unused kotlinx-datetime dep).
This commit is contained in:
@@ -1,20 +1,20 @@
|
||||
---
|
||||
name: "Core Orchestration Submodule Spec"
|
||||
description: "Specification for :core:orchestration – execution kernel"
|
||||
name: "Core Kernel Submodule Spec"
|
||||
description: "Specification for :core:kernel – execution kernel"
|
||||
depth: 2
|
||||
links: ["../index.md", "./core-module-spec.md", "./core-sessions-submodule-spec.md", "./core-transitions-submodule-spec.md"]
|
||||
---
|
||||
|
||||
# :core:orchestration module specification
|
||||
# :core:kernel module specification
|
||||
|
||||
version: 0.1-draft
|
||||
status: foundational specification
|
||||
version: 0.2
|
||||
status: implemented (SessionOrchestrator + ReplayOrchestrator)
|
||||
|
||||
---
|
||||
|
||||
# 1. purpose
|
||||
|
||||
`:core:orchestration` is the execution kernel of correx. It coordinates the entire workflow lifecycle by composing:
|
||||
`:core:kernel` is the execution kernel of correx. It coordinates the entire workflow lifecycle by composing:
|
||||
|
||||
* session management
|
||||
* stage scheduling
|
||||
@@ -30,7 +30,7 @@ It is the "brain" that wires together all other core modules and ensures work pr
|
||||
|
||||
# 2. responsibilities
|
||||
|
||||
`:core:orchestration` owns:
|
||||
`:core:kernel` owns:
|
||||
|
||||
* workflow execution loop
|
||||
* stage scheduling and sequencing
|
||||
@@ -46,7 +46,7 @@ It is the "brain" that wires together all other core modules and ensures work pr
|
||||
|
||||
# 3. non-responsibilities
|
||||
|
||||
`:core:orchestration` MUST NOT own:
|
||||
`:core:kernel` MUST NOT own:
|
||||
|
||||
* domain logic (that’s in events, transitions, validation, etc.)
|
||||
* persistence
|
||||
@@ -61,7 +61,7 @@ It coordinates; it does not implement low‑level mechanics.
|
||||
|
||||
# 4. architectural role
|
||||
|
||||
`:core:orchestration` acts as:
|
||||
`:core:kernel` acts as:
|
||||
|
||||
* the top‑level orchestrator
|
||||
* the only component that directly calls other core modules in a defined sequence
|
||||
@@ -112,7 +112,7 @@ Each iteration is a transaction in the event stream.
|
||||
|
||||
# 7. orchestration events
|
||||
|
||||
`:core:orchestration` emits high‑level events:
|
||||
`:core:kernel` emits high‑level events:
|
||||
|
||||
* `WorkflowStarted`
|
||||
* `WorkflowCompleted`
|
||||
|
||||
@@ -5,250 +5,37 @@ depth: 2
|
||||
links: ["../index.md", "./core-module-spec.md", "../design/structure.md"]
|
||||
---
|
||||
|
||||
yes. and good catch — consistency matters here because the structure itself becomes architecture documentation.
|
||||
# Module Organization and Documentation
|
||||
|
||||
i’d standardize on nested gradle modules only:
|
||||
## Module Layout
|
||||
|
||||
```text id="bllgjv"
|
||||
:apps
|
||||
:apps:cli
|
||||
:apps:server
|
||||
The project is organized into nested Gradle modules under these top-level groups:
|
||||
|
||||
:core
|
||||
:core:events
|
||||
:core:context
|
||||
:core:validation
|
||||
:core:transitions
|
||||
:core:orchestration
|
||||
:core:artifacts
|
||||
:core:sessions
|
||||
:core:approvals
|
||||
:core:policies
|
||||
:core:tools
|
||||
:core:inference
|
||||
|
||||
:infrastructure
|
||||
:infrastructure:persistence
|
||||
:infrastructure:providers
|
||||
:infrastructure:tools
|
||||
|
||||
:interfaces
|
||||
:interfaces:api
|
||||
:interfaces:cli
|
||||
```text
|
||||
:apps — applications (cli, server, tui, worker, desktop)
|
||||
:core — domain logic (events, sessions, transitions, kernel, context,
|
||||
inference, tools, artifacts, validation, approvals, router, config, risk)
|
||||
:infrastructure — adapters (persistence, inference providers, tools, workflow, artifacts-cas)
|
||||
:testing — test suites (replay, contracts, kernel, integration, fixtures,
|
||||
projections, transitions, approvals, deterministic)
|
||||
```
|
||||
|
||||
i would add:
|
||||
## Documentation
|
||||
|
||||
* `:core:orchestration`
|
||||
* `:core:artifacts`
|
||||
* `:core:sessions`
|
||||
Module specifications are maintained in AsciiDoc format under `docs/modules/`:
|
||||
|
||||
immediately.
|
||||
- `docs/modules/core/` — core module specs (.adoc)
|
||||
- `docs/modules/infrastructure/` — infrastructure module specs (.adoc)
|
||||
- `docs/modules/apps/` — application module specs (.adoc)
|
||||
- `docs/modules/testing/` — testing module specs (.adoc)
|
||||
|
||||
because those are foundational.
|
||||
without them, responsibilities leak everywhere.
|
||||
These `.adoc` files are the authoritative source for module responsibilities,
|
||||
invariants, boundaries, and contracts.
|
||||
|
||||
and yes — writing specs/design docs module-by-module is the correct approach.
|
||||
## Spec Template
|
||||
|
||||
BUT:
|
||||
you need two document types per module:
|
||||
Each module spec covers these sections:
|
||||
|
||||
1. contract/spec
|
||||
defines:
|
||||
|
||||
* responsibilities
|
||||
* invariants
|
||||
* boundaries
|
||||
* public interfaces
|
||||
* forbidden dependencies
|
||||
* event ownership
|
||||
* lifecycle guarantees
|
||||
|
||||
2. implementation/design
|
||||
defines:
|
||||
|
||||
* concrete architecture
|
||||
* classes
|
||||
* flow
|
||||
* persistence
|
||||
* threading
|
||||
* algorithms
|
||||
* data structures
|
||||
|
||||
this separation matters a lot.
|
||||
|
||||
recommended documentation structure
|
||||
|
||||
```text id="3ktksg"
|
||||
docs/
|
||||
├── architecture/
|
||||
│ ├── system-overview.md
|
||||
│ ├── event-model.md
|
||||
│ ├── replay-model.md
|
||||
│ ├── context-layers.md
|
||||
│ └── security-boundaries.md
|
||||
│
|
||||
├── modules/
|
||||
│ ├── core-events/
|
||||
│ │ ├── spec.md
|
||||
│ │ └── design.md
|
||||
│ │
|
||||
│ ├── core-context/
|
||||
│ │ ├── spec.md
|
||||
│ │ └── design.md
|
||||
│ │
|
||||
│ ├── core-validation/
|
||||
│ │ ├── spec.md
|
||||
│ │ └── design.md
|
||||
│ │
|
||||
│ └── ...
|
||||
│
|
||||
└── decisions/
|
||||
├── adr-0001-event-sourcing.md
|
||||
├── adr-0002-kotlin-choice.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
VERY important:
|
||||
use ADRs from the beginning.
|
||||
|
||||
Architecture Decision Records
|
||||
|
||||
because you WILL forget later:
|
||||
|
||||
* why replay works this way
|
||||
* why approvals are append-only
|
||||
* why projections are disposable
|
||||
* why router is isolated
|
||||
|
||||
future-you will otherwise rewrite old mistakes.
|
||||
|
||||
recommended order for specs
|
||||
|
||||
this order minimizes architectural drift:
|
||||
|
||||
1.
|
||||
|
||||
`:core:events`
|
||||
|
||||
first because:
|
||||
everything depends on event semantics.
|
||||
|
||||
must define:
|
||||
|
||||
* event contracts
|
||||
* causation/correlation ids
|
||||
* append guarantees
|
||||
* replay guarantees
|
||||
* snapshotting
|
||||
* versioning
|
||||
|
||||
2.
|
||||
|
||||
`:core:sessions`
|
||||
|
||||
defines:
|
||||
|
||||
* lifecycle FSM
|
||||
* ownership boundaries
|
||||
* session projections
|
||||
* cancellation semantics
|
||||
|
||||
3.
|
||||
|
||||
`:core:transitions`
|
||||
|
||||
defines:
|
||||
|
||||
* graph execution
|
||||
* rule evaluation
|
||||
* deadlock/cycle handling
|
||||
* retry semantics
|
||||
|
||||
4.
|
||||
|
||||
`:core:artifacts`
|
||||
|
||||
defines:
|
||||
|
||||
* artifact contracts
|
||||
* lineage
|
||||
* validation ownership
|
||||
* immutability guarantees
|
||||
|
||||
5.
|
||||
|
||||
`:core:validation`
|
||||
|
||||
defines:
|
||||
|
||||
* layered validation pipeline
|
||||
* semantic validators
|
||||
* policy interaction
|
||||
* approval interaction
|
||||
|
||||
6.
|
||||
|
||||
`:core:context`
|
||||
|
||||
probably hardest subsystem after validation.
|
||||
|
||||
must define:
|
||||
|
||||
* layering
|
||||
* token budgeting
|
||||
* compression contracts
|
||||
* dedup semantics
|
||||
* rebuild rules
|
||||
|
||||
7.
|
||||
|
||||
`:core:approvals`
|
||||
|
||||
must be isolated and heavily specified.
|
||||
|
||||
8.
|
||||
|
||||
`:core:orchestration`
|
||||
|
||||
only AFTER the primitives exist.
|
||||
|
||||
because orchestration composes:
|
||||
|
||||
* events
|
||||
* transitions
|
||||
* approvals
|
||||
* context
|
||||
* inference
|
||||
|
||||
9.
|
||||
|
||||
`:core:inference`
|
||||
|
||||
provider abstraction.
|
||||
|
||||
10.
|
||||
|
||||
`:core:tools`
|
||||
|
||||
tool contracts + receipts.
|
||||
|
||||
11.
|
||||
|
||||
infrastructure modules
|
||||
|
||||
ONLY after contracts stabilize.
|
||||
|
||||
this is important:
|
||||
do NOT start with providers/tools/ui.
|
||||
|
||||
that’s how orchestration architectures rot early.
|
||||
|
||||
for each module spec, define these sections
|
||||
|
||||
mandatory template:
|
||||
|
||||
```text id="n9z2y6"
|
||||
1. purpose
|
||||
2. responsibilities
|
||||
3. non-responsibilities
|
||||
@@ -266,56 +53,32 @@ mandatory template:
|
||||
15. extension points
|
||||
16. forbidden dependencies
|
||||
17. open questions
|
||||
|
||||
## Module Dependency Rules
|
||||
|
||||
```
|
||||
|
||||
this will massively reduce ambiguity later.
|
||||
|
||||
especially:
|
||||
“non-responsibilities”
|
||||
and
|
||||
“forbidden dependencies”
|
||||
|
||||
those prevent architecture erosion.
|
||||
|
||||
example:
|
||||
|
||||
```text id="a1qoqm"
|
||||
:core:context
|
||||
|
||||
non-responsibilities:
|
||||
- model execution
|
||||
- persistence
|
||||
- tool execution
|
||||
|
||||
forbidden dependencies:
|
||||
- infrastructure modules
|
||||
- websocket interfaces
|
||||
- provider implementations
|
||||
```
|
||||
|
||||
that sounds bureaucratic now.
|
||||
it becomes life-saving later.
|
||||
|
||||
one more recommendation:
|
||||
define module dependency rules EARLY.
|
||||
|
||||
example:
|
||||
|
||||
```text id="2vwe0o"
|
||||
core modules may depend on:
|
||||
- contracts
|
||||
- core:events (shared vocabulary)
|
||||
- lower-level core modules
|
||||
|
||||
core modules may never depend on:
|
||||
- infrastructure
|
||||
- interfaces
|
||||
- apps
|
||||
|
||||
infrastructure modules may depend on:
|
||||
- core modules
|
||||
- other infrastructure modules
|
||||
|
||||
apps may depend on:
|
||||
- core modules
|
||||
- infrastructure modules
|
||||
```
|
||||
|
||||
enforce this automatically eventually with:
|
||||
No cross-core imports between sibling core modules (except `core:events` for
|
||||
shared event types). Enforced by project convention.
|
||||
|
||||
* archunit
|
||||
* detekt custom rules
|
||||
* dependency analysis plugin
|
||||
## Architecture Decision Records
|
||||
|
||||
because modular architectures silently decay otherwise.
|
||||
Major decisions are recorded under `docs/decisions/` as ADRs. See existing
|
||||
records for the format.
|
||||
|
||||
Reference in New Issue
Block a user