feat(orchestration): plan grounding, positive-pattern mining, stage-prompt audition rig

Vikunja #167/#168/#169.

#167 PlanGrounder (infrastructure/workflow): build-prereq + touches-scope
existence grounding, emits PlanGroundingEvaluatedEvent. Deterministic fold
over recorded workspace/plan events (invariants #8/#9).

#168 positive-pattern mining (SessionOrchestratorPlanPatterns): mine
SuccessfulPlanShape from cross-session log — a locked plan whose own
workflow later completed — and inject the closest-resembling plan shape as
L0/SYSTEM advisory context for the planning stage. Keyword-Jaccard
resemblance, no LLM/embedder, replays identically. Advisory only (#3).

#169 stage-prompt audit + CORREX_STAGE_GUIDANCE ON/OFF toggle in
SessionOrchestratorExecution. RunCommand gains --intent to seed a
freestyle session over REST.

Also: workspace verification events + concept-compiler wiring. ./gradlew
check green.
This commit is contained in:
2026-07-16 14:55:56 +04:00
parent ed7efb6072
commit 53d8108189
27 changed files with 1379 additions and 53 deletions
+35
View File
@@ -8,6 +8,41 @@
- AGENTS.md files are binding work contracts for their subtrees
- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it
## Project Architecture
- Correx is a local-first, event-sourced orchestration kernel for LLM workflows, built with Kotlin/JVM 21 and Gradle.
- The event log is the sole source of truth. State is rebuilt from events; projections are disposable and owned by their bounded context.
- Keep deterministic core logic separate from nondeterministic inputs: LLM and tool outputs are untrusted proposals until validation; policy denials are terminal and cannot be overridden.
- Record each nondeterministic environment observation (for example filesystem, network, retrieval, or clock data) as an event when observed. Replay and downstream logic must use recorded facts and make no external calls.
- Tools must declare an execution tier and record every side effect as events. Compression and other derived representations are non-authoritative and cannot replace original events.
- New `EventPayload` implementations must be registered in `core/events/.../serialization/Serialization.kt` in the `eventModule` polymorphic block; otherwise runtime deserialization can fail silently.
## Module Boundaries
- `core/` contains domain logic and may not depend on `infrastructure/` or `apps/`.
- `infrastructure/` implements adapters against core contracts; `apps/` composes core and infrastructure into runnable processes.
- Do not introduce circular dependencies or dependencies from a module to a sibling core module unless the module architecture explicitly establishes one. Shared event vocabulary belongs in `core:events`.
- Inject dependencies rather than constructing concrete collaborators inside domain classes; use existing interfaces at boundaries.
## Kotlin Work Guidance
- Keep reducers limited to deterministic state transitions; do not put domain decisions or side effects in reducers.
- Convert exceptions to sealed domain results at the earliest practical boundary. Do not use broad `try`/`catch` that silently returns a fallback.
- Use coroutine-safe patterns: put blocking I/O in `Dispatchers.IO`, never use `Thread.sleep()`, and do not swallow `CancellationException`.
- Before finalizing a Kotlin file, remove unused imports and verify direct imports only.
## Verification and Context
- Tests for production modules may live under `testing/`; search there before deciding a module has no tests.
- Run focused tests with `./gradlew :path:to:module:test --rerun-tasks`. Run `./gradlew check` for the full test, Detekt, and Kover verification suite.
- Detekt failures are enforced. Prefer correcting violations; use the narrowest suppression only for a genuine false positive.
- Use `python scripts/ctx.py <query>` for ranked code context and `python scripts/ctx.py --deps <file>` for symbol dependency context when relevant.
## Task Tracking
- Use the Vikunja **Correx** project (`project_id: 4`) as the cross-session, user-visible backlog for follow-up work the user wants retained, such as deferred fixes, unverified QA gates, and designed-but-unimplemented work.
- Use the available Vikunja integration to review, create, and close tasks. Keep each task self-contained with its root cause, chosen fix, and relevant file paths so it can be resumed without prior session context.
## Read Before Editing
1. Read the root AGENTS.md