Files
ai-engineering/docs/architecture.md
T
Nilton Constantino f0e0dd061a feat: bootstrap portable engineering protocol CLI
Implement milestones 0 and 1 with project and repository configuration, Work persistence, discussions, draft decisions, evidence integrity, and deterministic context exports.

Add Java 25, Spring Boot and Modulith, native distributions, CI workflows, protocol documentation, and the pinned SDKMAN GraalVM CE toolchain.

Validated with 20 passing tests and the macOS ARM64 native multi-repository continuity smoke.
2026-11-11 16:14:22 +00:00

6.2 KiB

Architecture

Technology selection

The project deliberately stays on a compatible maintenance pair: Spring Boot 4.0.9 and Spring Modulith 2.0.9. The published Modulith 2.0.9 POM declares Boot autoconfigure 4.0.9. Java compilation and bytecode target are both 25, without preview features. Gradle 9.3.1 supports running on Java 25; its Wrapper distribution is pinned with SHA-256 verification.

The local development JDK is pinned through .sdkmanrc to SDKMAN candidate 25.5.5.0+3-graalce (GraalVM CE 25.5.5.0.3, OpenJDK 25.0.5.0.3). This GraalVM innovation release still uses Java 25. It provides both JVM and Native Image tooling without changing compilation target or application dependencies. Use sdk env for project-scoped activation; the Gradle Wrapper remains responsible for the Gradle version.

Primary compatibility references checked during implementation:

Picocli 4.7.7 handles argument validation, help and dispatch. Jackson 3 YAML/JSON comes from Boot's BOM. JUnit is explicitly pinned to 5.13.4 because the requested test baseline is JUnit 5; the Boot BOM otherwise selects a newer major generation. AssertJ and Modulith/ArchUnit verify behavior and dependencies. There is no Spring AI, Embabel, web starter, persistence server or workflow framework.

Module boundaries

All packages below are under net.intrepid.aiengineering. A module's base package is its explicit public API; implementation-only Git adapters live in project.internal. package-info.java declares allowed dependencies. ArchitectureTest calls ApplicationModules.verify() to enforce cycles, visibility and dependency rules.

Module Owns May depend on
filesystem Protocol codecs, safe paths, atomic file writes, locks, errors none
project Configuration, discovery, repository policy, read-only Git adapter filesystem
work Work identity, lifecycle, repository snapshots and reference manifest project, filesystem
discussion Append-only refinement entries and thread grouping work, filesystem
decision Draft DEC records work, filesystem
artifact Small evidence payloads and integrity metadata work, filesystem
verification Structural conformance and portable context assembly all protocol modules
cli Picocli commands, formats, exit codes all APIs above

Spring owns the process lifecycle and CLI bean, and supplies AOT processing. Protocol services are ordinary Java classes with explicit path arguments and no retained Work cache. This keeps direct tests and fresh instances simple. Infrastructure dependencies remain inside services, outside immutable domain records. The small GitAdapter port is internal to Project and can be replaced without changing Work contracts.

Context assembly belongs to Verification because it combines independently persisted modules and refuses to export structurally inconsistent state. Work does not depend on Discussion, Decision or Artifact, avoiding cycles. It owns stable references only.

Persistence and native execution

Writers take an OS file lock per project. Complete UTF-8 files are written to a sibling temporary file, forced to disk and published atomically. New files use a hard link to avoid overwriting an existing destination. Existing files use atomic replacement; unsupported filesystems fail instead of quietly falling back to partial writes. New Works, projects and artifact payload bundles are staged before directory rename. See the protocol document for crash limits and recovery.

Jackson parses explicit records, rejects unknown fields, duplicate YAML keys and unsupported schema versions. Native hints register those records; Picocli's annotation processor provides command reflection metadata. The Spring AOT tasks are wired by the native build plugin. No application arguments are passed through Spring's property parser. The entry point explicitly chooses non-web mode and closes its context.

Earlier framework review and migration

Both implementations were inspected read-only:

  • The user-identified Python repository at /Users/niltonconstantino/personal/workspace.personal/intrepid/discussion-framework: README, model/locking/index persistence and structural validation.
  • The sibling Java discussion-framework: DiscussionOrchestrator, WorkflowValidator, WorkPacket, ArtifactDocumentParser and FilesystemDiscussionRepository concepts and implementations.

Reused concepts: deterministic context as the handoff surface, stable IDs, explicit references, file locks, atomic replacement, duplicate/reference checks and separating content from mechanical CLI state management. No Python code or dependency was copied. The old generic Markdown inference was replaced by typed, versioned front matter; semantic sections are explicit and cannot silently disappear from context parsing.

No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic housekeeping deletion or Lesson model was retained. Work is the project-scoped aggregate; Discussion is refinement within a Work. Source repositories were not changed.

There is no automated legacy importer in Milestone 1. A future migration should create one Work per coherent agenda, retain original discussion/decision text with origin references, and verify identifiers and links before publication. Legacy Lessons should be reviewed for integration into canonical docs, not recreated as a required entity.