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
+85 -10
View File
@@ -21,6 +21,10 @@ without Git, or register a single existing Git repository using `repo add app --
No enclosing workspace or additional repositories are required. Regression coverage
includes fresh processes without Git on PATH and single-repository root discovery.
Pilot usability improvements include explicit `work update` refinement and UTF-8
`discussion add --text-file` input. Scope fields can now be maintained through the CLI,
and long proposals can be authored as ordinary Markdown files before persistence.
Acceptance demonstration: initialize a project with two independent Git repositories,
create a Work referencing both, append discussion, persist a draft decision and
evidence, export context, then reconstruct the same context in independent processes
@@ -35,16 +39,86 @@ distribution experiment must identify and validate a maintained compatible toolc
before enabling that native release target. CI configuration is not evidence that CI
has run; see actual local results in experiments.
## Milestone 2 — Intelligent Discussion (design only)
## Operational replacement baseline — expanded scope
Introduce a replaceable AgentAdapter using the portable context contract. Begin with
deterministic fakes and persist proposed questions/alternatives/assumptions as explicit
entries. Acceptance: two different adapters continue the same Work without private
history; humans retain authority over formal commitments. No model integration yet.
Implemented after the initial milestones at the user's request: provider-neutral
discovery instructions and manifest, root `AGENTS.md` integration, explicit DEC
approval/rejection/revision with history, lightweight plans and dependent steps,
status/next-actions, mechanical completion checks, criterion evidence mappings,
canonical knowledge integration snapshots, retained archives and reversible reopening.
No old Agenda/Lesson entity or automatic housekeeping deletion is introduced.
Recommended next experiment: two deterministic adapters read the same schema 1 context,
one proposes a clarification and another continues from its persisted response. First
confirm the context contract is sufficient; then choose provider integrations.
Acceptance: a fresh process reads the entry contract and reconstructs an approved,
planned, evidenced, completed and archived Work; another execution reopens it with
prior conclusions and delivery history intact. Invalid approval, dependency, evidence
and revision-history states are diagnosed. No agent/provider service is required.
The test suite verifies mechanics, not an arbitrary external AI's compliance.
Continue piloting the installed entry files and CLI in an existing real project,
with an external agent continuing a Work through human-reviewed closure. The first
Discussion refinement slice is described below. A separate future importer must
preserve origins/history for open agendas and valuable legacy Lessons, integrating
knowledge into canonical docs instead of requiring Lesson artifacts.
## Milestone 2 — Discussion refinement (first contract slice)
PLN-0001 implements the explicitly approved first slice: topics, surveys with options
and free text, append-only answer revisions, reversible proposal dispositions, a small
AgentAdapter API, general fallback/specialized routing and two deterministic fixtures.
Run provenance, idempotent completed requests and source-staleness diagnostics remain
portable. The framework applies validated proposals; human approval stays explicit.
Acceptance experiment: one fake organizes two topics and a survey; fixture answers
are revised, evidence attached, and another fake continues from a fresh process with
an investigation, reversible archive and DEC draft. Unchanged context matches across
executions. This verifies the contract, not real semantic intelligence. Actual build
and native outcomes are recorded in [experiments](experiments.md).
The subsequent local CLI slice below implements the selected real transports;
fixtures remain the default acceptance-test baseline without external accounts.
## EPIC coordination — second approved slice
PLN-0002 implements DEC-0003: Works can coordinate derived Works through versioned
EPIC policies. Children are important by default, with explicit optional subsets,
decomposition-only delivery, cycle/multiple-parent rejection and nested coordination.
Important cancellation remains pending until scope/importance review. Automatic
completion requires explicit policy delegation, local readiness and valid important
deliveries; receipts distinguish system results from human delivery approvals.
Lifecycle commands propagate outcomes/reopenings and return a deterministic report.
Reconciliation recovers missed propagation from files without an LLM. Acceptance
covers independent processes, repeated notification, policy/scope changes, history,
important/optional/cancelled children and native standalone execution. Actual observed
results are recorded in [experiments](experiments.md).
The EPIC slice itself does not choose providers or execute child repository changes.
Agent-generated decomposition and the agenda/Lesson importer remain separate work.
## Local Codex/Claude adapters — third approved slice
PLN-0003 follows SVY-0001: both installed CLIs, for Discussion/synthesis proposals
validated by AIE. Implements fixed process arguments, private workspaces, schemas,
timeout/output/cleanup limits, safe diagnostics, general classification/routing,
RUN provenance, local doctor and guided init for general/activity executors.
Credentials remain with the provider. No provider is activated automatically in the
AIE source project. Native distribution and ordinary protocol use still need no JVM,
Node or model service; optional real runs require the chosen CLI/authentication.
Acceptance uses deterministic JDK subprocess fixtures, including failure, invalid
output, ownership, timeout/descendants, cleanup and fresh-process reconstruction.
Bounded real-provider checks and native outcomes are reported separately in
[experiments](experiments.md). Provider-native config profiles, direct APIs, source
editing/execution and a generic orchestration engine are outside this slice.
## Plan consolidation — approved execution-state slice
WRK-0002/DEC-0001 adds a separately approved execution-state slice before further
OODA work: deterministic Step → Plan → Work consolidation, reviewed cancellation
scope, pending commitments, system receipts, idempotent recovery and EPIC propagation.
Acceptance requires offline multi-Plan/no-model tests, legacy/fresh-process continuity,
Modulith and actual local native/distribution verification. This is protocol state
management, not an autonomous OODA engine. Results are recorded in experiments.md.
## Milestone 3 — Adaptive OODA (design only)
@@ -60,9 +134,10 @@ validation and separate commit outcomes. Acceptance: partial success in one repo
remains visible; destructive actions, push and merge require explicit authorization.
Never assume atomic commit across repositories.
## Milestone 5 — Knowledge integration and conformance (design only)
## Milestone 5 — Extended knowledge integration and conformance (design only)
Check acceptance criteria against evidence; identify impacted canonical specs, tests,
Extend the operational baseline's explicit human-reviewed mappings with richer
checks against evidence; identify impacted canonical specs, tests,
code and documentation; expose conformance checks to agents and CI. Acceptance: a Work
can demonstrate its outcome and preserve actionable knowledge without a mandatory
Lesson model or redundant documentation trail.