feat: add agent coordination and automatic work completion

Add portable topics and surveys, decision approval history, execution plans, local Codex and Claude adapters, and general agent routing. Consolidate Plan and EPIC results through deterministic completion receipts, reviewed cancellation scope and recoverable reconciliation.

Track the completed WRK-0001 and WRK-0002 records, protocol documentation, source manifests and delivery evidence.

Validation: 117 tests including Modulith; GraalVM 25 native compilation, standalone smoke and ZIP/TAR verification on macOS ARM64; identical persisted context across JVM and native executions.
This commit is contained in:
Nilton Constantino
2026-11-14 01:12:21 +00:00
parent c84bb8d36f
commit bd2c9133da
355 changed files with 25740 additions and 154 deletions
+350 -4
View File
@@ -187,6 +187,282 @@ migrated with the native CLI. Original files were retained under the reported `.
backup directory. JSON context, Markdown context and `work.md` compared byte-for-byte
equal before/after conversion; project validation returned `valid: true`, no issues.
## H7 — Explicit Work refinement and discussion file input
`work update` now refines specified scope fields while preserving identity, creator,
creation time, lifecycle, repository snapshots and child references. Supplied list
values replace their whole list; dedicated clear flags distinguish intentional removal
from omission. Identical updates retain Work bytes/timestamps. Metadata writes also
preserve trailing Work notes, including later status and child-reference changes.
`discussion add --text-file` imports exact UTF-8 prose from a caller-relative file;
Picocli requires exactly one text source. Reads are bounded to 1 MiB and malformed,
blank, nonregular or oversized input is rejected before appending history. Missing
files receive exit 3. The source can be removed after import without affecting context.
Eight additional tests cover field/list updates, preservation of child files and other
Works, idempotence, invalid input without partial writes, trailing notes, exact Unicode
and mixed-line-ending imports, source resolution with an external `--project`, and
file failures. Existing process-continuity/root-repository tests now exercise updates
and file input as well. Result: **37 tests, 0 failures, 0 errors, 0 skipped**, including
Modulith and independent JVM processes without Git on PATH.
Executed `clean test bootJar nativeCompile` using the pinned SDKMAN GraalVM CE 25.5.5
toolchain. Native compilation and the expanded macOS ARM64 smoke passed; it imports a
discussion file, updates a Work containing discussion/decision/evidence references,
checks a repeated update leaves `work.md` byte-identical, and retains all prior
plain-folder, single-/multi-repository and migration checks. Help for both commands
also ran successfully through `~/.local/bin/aie` from the user's home directory.
## H8 — Hexadecimal Work identifiers
Works now use uppercase hexadecimal counters: `WRK-0009`, `WRK-000A` … `WRK-000F`,
`WRK-0010`. Validation and numeric ordering accept hexadecimal suffixes up to nine
digits; discussion/decision/artifact counters remain decimal. Sequence schema version 2
stores a quoted hexadecimal high-water mark. Legacy numeric counters are read without
writes and upgraded on creation, preserving prior identifier spellings and reservations
even when old Works have been removed. Existing Work files/references are not renamed.
Seven additional tests cover base-16 boundaries, child references and fresh context,
legacy reservation conversion, retained Work bytes, numeric ordering across the width
increase, capacity/invalid counters without partial writes, and canonical ID validation.
Result: **44 tests, 0 failures, 0 errors, 0 skipped**, including the previous update,
file-input, persistence, Modulith and process-continuity suites.
`clean test bootJar nativeCompile` passed on the pinned GraalVM CE toolchain. The
expanded macOS ARM64 native smoke also passed without a JVM on PATH: 16 sequential
Works crossed both hexadecimal boundaries, `WRK-000A` supported discussion/decision/
update/context across executions, and a removed legacy reservation at 16 produced
`WRK-0017` while converting the sequence. Existing plain-folder, single-/multi-repository
and discussion-migration scenarios remained successful. The `aie` symlink resolved the
rebuilt executable from the user's home directory.
## H9 — Operational replacement and agent discovery
The user expanded the scope: establish a complete operational replacement for the
old discussion workflow before adding an agenda/Lesson importer or intelligent
adapters. The implementation now installs a provider-neutral entry guide, local
instructions and a validated JSON manifest. A managed root `AGENTS.md` block points
agents to the protocol without replacing existing project rules. Onboarding is
idempotent and backs up changed instructions. Legacy projects without entry files
remain readable; partial/invalid contracts are diagnosed.
Implemented DEC review, human approval attestation, rejection, revision and
supersession; lightweight plans/steps with dependency checks and evidence; immutable
previous snapshots with SHA-256 links; derived status/next-actions; mechanical
readiness checks; explicit criterion evidence mappings and canonical integration
snapshots; retained archives and reasoned reopening. No agent executes inside the
CLI. No importer, Lesson entity, automatic deletion or autonomous OODA engine was added.
The new tests first failed against the previous implementation. Subsequent failures
exposed Picocli's annotation processor rejecting a shared optional argument-group
type and strict deserialization rejecting absent primitive operational fields in old
Work files. Both were corrected: optional DEC text options validate their exclusivity
explicitly, and legacy operational fields normalize absent values without rewriting
the source. A former context-isolation assertion was also made structural because
the exported guide legitimately contains example artifact IDs.
Executed on the pinned GraalVM CE JDK 25 toolchain:
```sh
./gradlew test --tests '*OperationalSafetyTest' --console=plain
./gradlew clean test bootJar nativeCompile --console=plain
```
Final result: **56 tests, 0 failures, 0 errors, 0 skipped**, including Modulith
verification of nine modules. Coverage includes old Work/draft DEC compatibility,
malformed/partial discovery contracts, instruction preservation/backups, decision
approval and supersession, plan cycles/missing dependencies, invalid completion
evidence, terminal-record guards, revision tampering and independent JVM executions.
Unchanged Markdown and JSON context are compared across separate processes.
Native compilation passed on **macOS ARM64**, using GraalVM CE 25.5.5.0.3. The build
reported seven upstream deprecation warnings and build-time SLF4J no-provider notices;
there were no compilation failures. No success is claimed for other native platforms.
The executable alone was copied to a separate temporary directory, without any
Native Image helper libraries, and the expanded `scripts/native-smoke.sh` passed with
`JAVA_HOME=/nonexistent`, `GRAALVM_HOME=/nonexistent` and a system-only PATH. Its
plain-folder sections additionally remove Git from PATH. This verifies the CLI does
not need a local JVM or adjacent GraalVM installation for the exercised operations.
The retained multi-repository fixture is
`/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/ai-engineering-smoke.7CZbPu`.
It created independent `runtime` and `studio` Git repositories, registered both,
and created a Work referencing their actual commits. Fresh native executions
recorded a question/conclusion, evidence, an approved DEC, a plan/result, reviewed
completion and archive. Context matched byte-for-byte from a nested directory.
Another execution reopened the Work, recorded a new agent's observation, approved
a superseding DEC and reopened/replanned the previous plan while retaining the
earlier completion. Final project validation passed. This is a disposable fixture,
not an assertion that a real rendering/game experiment was run.
The existing `~/.local/bin/aie` symlink executed the rebuilt native binary from the
user's home directory. No files in the Zelda project were changed by this experiment.
Tests prove discovery-file and CLI mechanics; compliance by an arbitrary external
AI agent still requires a real pilot using those entry files.
## H10 — Discussion topics, surveys and adapter continuity
PLN-0001 implements the first explicitly approved refinement slice. Discussion keeps
ideas as entries, organized by topics, with surveys and append-only answer revisions.
Reversible dispositions preserve the original proposals and require explicit project
policy plus owned evidence. The general executor provides fallback; specialized
activity configuration wins. Two deterministic adapters exercise the same immutable
context/proposal contract. They never perform real research or approve commitments.
Four acceptance tests first failed against the preceding CLI because the commands
were absent. After implementation the original and new tests ran together. Expanded
coverage exposed an overly broad Markdown assertion matching `text:` in the new
guide; it now checks only discussion rendering. A symlink test exposed RUN/raw-task
publication before detecting an unsafe topic directory; preflight now rejects unsafe
publication directories before any canonical write.
The complete suite passed: **70 tests, 0 failures, 0 errors, 0 skipped**, including
Modulith verification of ten modules. New tests cover invalid adapter bundles without
mutation, legacy reads without rewriting, cross-Work references, options/free text,
multiple selections, answer supersession, history tampering, archive policy/evidence,
restoration, request idempotency, stale summaries, unsafe paths and noninteractive input.
`ProcessContinuityTest` ran four scenarios in independent JVMs. The new refinement
scenario persisted two topics, a generated survey, fixture human answers and a revised
answer, evidence and analysis by the second adapter. A DEC stayed DRAFT. Fresh
processes reconstructed all meaningful state and produced byte-identical JSON and
Markdown context. Existing no-Git, root-repository, multi-repository and operational
closure/reopening regressions also passed. No Zelda source or Work was modified.
Executed with GraalVM CE 25.5.5.0.3 / JDK 25.0.5.0.3 on **macOS ARM64**:
```sh
./gradlew clean test bootJar nativeCompile --console=plain
./gradlew test bootJar nativeDistZip nativeDistTar -PtargetPlatform=macos-arm64 --console=plain
```
Both builds passed, including the repeated 70-test suite. Native Image reported
seven upstream deprecation warnings and SLF4J build-time no-provider notices.
The executable alone passed the expanded native smoke with JAVA_HOME and GRAALVM_HOME
pointing to `/nonexistent` and a system-only PATH. Plain/refinement sections also
removed Git from PATH. The final ZIP-extracted binary passed the same complete smoke;
the TAR-extracted executable had identical bytes and executed `--version` without JVM.
ZIP/TAR preserve executable permission. No adjacent GraalVM helper libraries were used.
The native refinement fixture verified guided answers from an explicit input file,
answer revision history, two topics/adapters, synthetic analysis, archive/restore,
draft-only DEC, completed-request replay without Work changes and derived staleness.
Context matched across fresh executions from nested directories. The existing
multi-repository and completion/archive/reopen scenarios passed again. Onboarding
refreshed this project's installed guide/manifest and preserved root AGENTS.md bytes.
Final source hashes and observed results are attached to WRK-0001. Other platforms
were not built/tested in this experiment.
## H11 — Deterministic EPIC coordination and recovery
The next approved slice, PLN-0002 under DEC-0003, keeps EPICs as Works and adds
versioned coordination policies. The first six executable acceptance scenarios
compiled and failed because the preceding CLI had no EPIC commands. Implemented
definition/history, project-scoped forest links, importance, RESULTS/DECOMPOSITION
modes, explicit automatic-completion authority and deterministic ancestor checks.
No model/provider was selected or called to evaluate protocol state.
Automatic closure creates an owned aggregate ART receipt and SYSTEM_EPIC completion
with humanApproved=false, referencing the actual human-authorized policy snapshot.
Important cancellations remain pending; optional children may stay open. Reopening
an important child reopens ancestors while preserving unchanged-scope authority.
Design review identified that explicit EPIC reopening must suspend that authority
so the parent remains available for replanning. Scope/link edits require renewed
authorization. Empty important sets and manual BLOCKED/CANCELLED parents cannot
trigger automatic completion.
The initial six scenarios passed. The expanded intermediate suite then passed:
**85 tests, 0 failures, 0 errors, 0 skipped**, including ten-module Modulith checks.
New safety cases cover scope changes, local questions/blocking, manual reopening,
optional-child reopening, revision tampering, symlink refusal, legacy completed-Work
digests and reuse of an already-published receipt after interrupted completion.
An additional fresh-JVM scenario and the standalone native smoke exercise persisted
coordination across independent executions. Hash inputs use ordered maps to avoid
process-dependent iteration order.
Final `clean test bootJar nativeCompile` passed on GraalVM CE 25.5.5.0.3 / JDK
25.0.5.0.3, macOS ARM64: **86 tests, 0 failures, 0 errors, 0 skipped**, across 15
suites and ten verified modules. The five process experiments passed; the new EPIC
scenario alone used independent JVM invocations for configuration, cancellation,
scope review, automatic completion, context reload, reopening and notification replay.
Native Image reported seven upstream deprecation warnings and build-time SLF4J
no-provider notices, with no compilation failures.
The executable alone was copied to a separate directory and the expanded native
smoke passed with absent JAVA_HOME/GRAALVM_HOME and a system-only PATH. EPIC commands
additionally had no Git on PATH and no agent configuration. The scenario exercised
important/optional/cancelled children, explicit scope delegation, system receipts,
important-child reopening, notification replay without rewrite, explicit parent
reopening that remains open, DECOMPOSITION closure and nested-directory context
equality. Existing discussion, Git registry and operational-cycle smoke scenarios
also passed. No helper libraries were copied beside the executable.
The same persisted native EPIC fixture was then loaded by the executable JAR in a
fresh JVM. JSON and Markdown contexts matched native output byte-for-byte, and JVM
project validation returned valid=true with no issues. This verifies record/history
and frozen-digest compatibility across runtimes, not only within one process type.
Onboarding refreshed this project's guide/manifest while keeping root AGENTS.md
byte-identical. Zelda was not modified. Source hashes, complete command outcomes and
archive checks are retained with the PLN-0002 delivery evidence in WRK-0001.
## H12 — Local Codex/Claude proposal adapters
PLN-0003 follows the explicit choices preserved in WRK-0001/SVY-0001: both local
CLIs, initially Discussion/synthesis proposals only. Four acceptance tests compiled
and failed against the preceding CLI. After implementation, 13 targeted transport/
setup scenarios passed, and the intermediate full suite passed **101 tests** with
zero failures/errors/skips. Tests use JDK subprocess fixtures, not provider accounts.
Implemented fixed argument vectors, private working directories, stdin context,
bounded streams/output file, timeout/descendant termination, version/help doctor,
JSON schemas, canonical proposal validation, optional RUN provenance, general
classification/routing and guided init. Prior RUN outputs are passed as derived
interpretations; they do not become factual evidence. Profile is an AIE role rather
than a private vendor config. Artifact payloads remain references unless their
content has been recorded in Discussion; the adapter receives no repository root.
Actual installed CLIs were checked: Codex 0.169.0 and Claude Code 2.1.311. A small
temporary synthetic project then exercised real provider calls, with tools restricted
and a 60-second provider timeout. Codex produced RUN-0001 summarizing the goal and
DSC-0001. Claude produced RUN-0002 that explicitly continued Codex's persisted
interpretation and distinguished it from the canonical synthetic note. A third run
omitted --activity: general classified the natural-language request as summarize and
produced another synthesis; classification and proposal invocations were recorded.
These were transport/continuity probes, not real product research or code execution.
The first Claude call failed authentication despite the normal CLI reporting a login.
A local auth-status probe under the filtered process environment reproduced the
difference. Preserving USER and standard identity/XDG variables restored private
provider login lookup; retry succeeded without changing/copying credentials. Added
a deterministic identity-forwarding regression. A restricted tool sandbox also
blocked a JVM sysctl query during doctor; repeating that probe outside the tool
sandbox succeeded. Neither failure was hidden or converted to a successful RUN.
Final `clean test bootJar nativeCompile` passed with GraalVM CE 25.5.5.0.3 / JDK
25.0.5.0.3 on macOS ARM64: **104 tests, 0 failures, 0 errors, 0 skipped**, across
17 suites and ten verified Modulith modules. Native Image reported seven upstream
deprecation warnings and build-time SLF4J no-provider notices, with no build failures.
Additional regressions cover process identity, incomplete guided setup and configured
projects continued in fresh JVMs without installed providers or Git on PATH.
The executable alone passed the complete native smoke with JAVA_HOME/GRAALVM_HOME
pointing to /nonexistent. The new CLI section uses controlled shell executables and
removes Git/tools from PATH, exercising private process workspaces, both wire codecs,
classification, specialized routing, provenance, guided file setup, replay and reload
without JVM/model accounts. All previous discussion, EPIC, multi-repository and
operational-cycle native scenarios passed as well.
The native executable loaded the three actual provider RUNs produced by the JAR;
its complete JSON context matched the fresh JVM output byte-for-byte and project
validation returned valid=true with no issues. Actual provider inference was tested
on the JVM; native process transport was tested with controlled executables. These
are separate results. Onboarding refreshed the source project's entry resources
without changing root AGENTS.md. No real executor was enabled automatically in this
project, and no Zelda files were changed. Final sources/archive checks are attached
to WRK-0001 with PLN-0003 delivery evidence.
## Limits and next experiment
CI workflows are provided but have not been executed from this local workspace.
@@ -197,8 +473,78 @@ Filesystem atomicity is per file/directory publication, not a transaction across
child record and parent manifest. Orphans after interruption are detected, not
automatically repaired. Manual concurrent editors and adversarial path replacement
require external coordination/sandboxing. Artifact attachment is limited to small
files, and no full provenance/environment capture or agent intelligence is implemented.
files. External command provenance/environment capture remains manual; the run
records cover adapter inputs/proposals, and real agent intelligence is not implemented.
Next recommended experiment: define a deterministic AgentAdapter test contract and
demonstrate two fake adapters continuing the same Work. Keep that work in Milestone 2;
no adapter implementation is included here.
Next recommended experiment: let an external agent start from only the installed
`.ai-engineering` entry contract and complete a real Work with explicit human review.
Then design the separate importer for open agendas and useful legacy knowledge.
Fixture adapters remain the reproducible offline baseline. Local Codex/Claude
proposal transports and deterministic EPIC propagation are now implemented. Next,
pilot a real bounded discussion with human survey answers and explicit DEC review.
Provider-native config profiles, direct APIs, automatic decomposition proposals,
repository execution and the legacy importer remain separate work.
## WRK-0002 — deterministic Plan consolidation (2026-11-14)
Hypothesis: existing Plan/step completion, results and evidence are sufficient for
framework state aggregation, without asking a model to judge Work completion or
creating another acceptance checklist at Work level. DEC-0001 and SVY-0001 in
WRK-0002 record the human direction and accepted cancellation/pending rules.
Observed: four test-first cases compiled and failed before implementation. The final
clean test/bootJar run passed **117 tests in 19 suites, zero failures/errors/skips**,
including Modulith. Targeted consolidation/safety/operational cases passed 16 tests.
Old manual-closure fixtures were updated to assert automatic completion; two added
fixture assertions needed corrected DEC content and provenance assertions. No
unresolved test failures remain. A configured must-not-run adapter verifies that
consolidation does not require a model or a default-registry executor.
Implemented: last step consolidates Plan, all required Plans consolidate Work,
SYSTEM_PLANS provenance and owned versioned receipts bind exact Plan revisions.
Reviewed cancellation retains content-bound history; unresolved surveys/questions
and draft DECs, explicit blocking states and empty sets remain pending. Explicit
reopening suspends immediate reclosure while Plans are revised. Reads are pure;
mutation commands/reconciliation report pending state and existing EPIC effects.
Tests cover interrupted last-step/receipt publication and repeat recovery, invalid
evidence, changed scope reviews, dependencies and independent processes.
Commands executed:
```sh
./gradlew test --tests '*PlanConsolidationTest' --console=plain
./gradlew test --console=plain
./gradlew -Dorg.gradle.java.home=/path/to/graalvm25 test \
--tests '*PlanConsolidation*' --tests '*OperationalWorkflowTest' --console=plain
./gradlew -Dorg.gradle.java.home=/path/to/graalvm25 clean test bootJar nativeCompile --console=plain
JAVA_HOME=/path/to/graalvm25 GRAALVM_HOME=/path/to/graalvm25 ./gradlew nativeCompile --console=plain
```
The clean command's test/JAR tasks passed; its native task failed because Native
Build Tools used SDKMAN `current`, which had changed to Amazon JDK 25 without
native-image. Explicit JAVA_HOME/GRAALVM_HOME corrected selection. Native compilation
then passed with GraalVM CE 25.5.5.0.3 / JDK 25.0.5.0.3 on macOS ARM64 in 1m28s,
with seven upstream warnings and build-time SLF4J notices. Gradle Wrapper is 9.3.1.
No dependency version or Java target was changed.
The isolated executable alone passed all native smoke sections with nonexistent
JAVA_HOME/GRAALVM_HOME and no JVM on PATH: single/multiple repositories, refinement,
controlled local CLI transports, EPICs, the operational cycle and new two-Plan
consolidation/cancellation/replay. No adjacent GraalVM libraries were copied. New
native JSON mutation output and content-bound exclusion were exercised directly.
No real model request was sent during this Work.
Retained fixture:
`/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/ai-engineering-smoke.YUYSGM`.
Its plan-consolidation project reloaded in a fresh JVM and native execution with
byte-identical JSON context and valid structure. The pre-existing WRK-0001 also
remained valid. Raw logs, source hashes and distribution checks are attached to
WRK-0002. Other native platforms and CI were not executed locally.
The public coordination API/CLI handles notifications; low-level storage-service
callers explicitly reconcile. File publication remains per-file atomic, with
deliberate repair for malformed/orphan records. Aggregation trusts recorded Plan
results and checks integrity; it does not prove prose or command provenance
semantically. Repository execution and the legacy importer remain separate work.
Next experiment: exercise automatic closure on a bounded real multi-Plan Work and
review the returned pending-state report before expanding execution capabilities.