kami
f7f237e29f
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).
85 lines
2.3 KiB
Markdown
85 lines
2.3 KiB
Markdown
---
|
|
name: "Modules And Spec"
|
|
description: "Guide to module organisation and documentation standards"
|
|
depth: 2
|
|
links: ["../index.md", "./core-module-spec.md", "../design/structure.md"]
|
|
---
|
|
|
|
# Module Organization and Documentation
|
|
|
|
## Module Layout
|
|
|
|
The project is organized into nested Gradle modules under these top-level groups:
|
|
|
|
```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)
|
|
```
|
|
|
|
## Documentation
|
|
|
|
Module specifications are maintained in AsciiDoc format under `docs/modules/`:
|
|
|
|
- `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)
|
|
|
|
These `.adoc` files are the authoritative source for module responsibilities,
|
|
invariants, boundaries, and contracts.
|
|
|
|
## Spec Template
|
|
|
|
Each module spec covers these sections:
|
|
|
|
1. purpose
|
|
2. responsibilities
|
|
3. non-responsibilities
|
|
4. invariants
|
|
5. public contracts
|
|
6. owned events
|
|
7. consumed events
|
|
8. state model
|
|
9. threading/concurrency model
|
|
10. failure semantics
|
|
11. replay semantics
|
|
12. persistence requirements
|
|
13. observability requirements
|
|
14. security boundaries
|
|
15. extension points
|
|
16. forbidden dependencies
|
|
17. open questions
|
|
|
|
## Module Dependency Rules
|
|
|
|
```
|
|
core modules may depend on:
|
|
- 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
|
|
```
|
|
|
|
No cross-core imports between sibling core modules (except `core:events` for
|
|
shared event types). Enforced by project convention.
|
|
|
|
## Architecture Decision Records
|
|
|
|
Major decisions are recorded under `docs/decisions/` as ADRs. See existing
|
|
records for the format.
|