Files
ai-engineering/docs/architecture.md
T
bquarkz 94e3135c2e feat: store discussion prose in Markdown bodies
Add versioned Markdown discussion documents with legacy YAML reading and explicit migration that backs up originals and preserves semantic history.

Render readable discussion and decision prose in Markdown context, document compatibility, and extend native smoke coverage for migration.

Validated with 29 passing tests, macOS ARM64 native smoke, and context-preserving migration of the Zelda pilot Work.
2026-11-11 19:50:36 +00:00

7.1 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.

The engineering project is independent of repository count: a plain folder can use the protocol with no Git dependency, a single Git repository can register the root using ., and a larger workspace can register several child repositories. The same configuration schema and services support each case; no separate project mode or additional repository type is needed.

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.

Discussion document version 2 separates typed YAML metadata from an opaque Markdown body. The filesystem codec maps that body to the domain record's existing text field; it does not infer structure from prose headings. The reader accepts legacy YAML-only text as well. Explicit migration backs up originals, preserves semantic state and skips converted files. Work and draft DEC persistence are unchanged; Markdown context renders discussion/decision prose without YAML escaping.

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.