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:
2026-11-14 01:12:21 +00:00
parent 94e3135c2e
commit a8a8faf5d8
355 changed files with 25740 additions and 154 deletions
+142 -11
View File
@@ -41,11 +41,13 @@ its explicit public API; implementation-only Git adapters live in `project.inter
|---|---|---|
| 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 |
| work | Work identity/lifecycle, repository snapshots, references and versioned EPIC policy/graph | project, filesystem |
| discussion | Entries, topics, surveys, answer history and proposal dispositions | work, project, artifact, filesystem |
| decision | Draft, approval, revision and supersession records | work, filesystem |
| planning | Lightweight plans, dependencies, step results and revision history | work, decision, artifact, filesystem |
| artifact | Small evidence payloads and integrity metadata | work, filesystem |
| verification | Structural conformance and portable context assembly | all protocol modules |
| agent | Adapter contract, deterministic fixtures, routing and proposal application | project, work, discussion, decision, planning, artifact, filesystem |
| verification | Structural conformance, context, reviewed closure and deterministic EPIC coordination | 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
@@ -54,8 +56,8 @@ cache. This keeps direct tests and fresh instances simple. Infrastructure depend
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
Context assembly, readiness and evidence-mapped closure belong to Verification because they combine independently persisted
modules and refuse 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
@@ -64,9 +66,18 @@ using `.`, and a larger workspace can register several child repositories. The s
configuration schema and services support each case; no separate project mode or
additional repository type is needed.
Work refinement uses an immutable update value that distinguishes omitted fields from
explicitly emptied lists. The domain preserves identity, lifecycle and references;
the filesystem service locks the project and replaces front matter while retaining
trailing notes. Discussion file input belongs to the CLI adapter: Picocli enforces
exclusive text sources and a bounded strict UTF-8 read supplies the existing domain
entry. Neither feature changes canonical record schemas or introduces new modules.
## Persistence and native execution
Writers take an OS file lock per project. Complete UTF-8 files are written to a sibling
Writers take an OS file lock per project. Nested service calls on the same thread reuse
the outer lock; other threads/processes cannot interleave the proposal application.
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.
@@ -82,9 +93,128 @@ 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.
YAML-only text as well. Explicit discussion migration backs up originals, preserves
semantic state and skips converted files. New decision narrative (`text`) and plan
description use the same Markdown-body codec; legacy draft DECs remain readable.
Work front matter remains canonical, with additive operational fields. Markdown
context renders discussion/decision prose without YAML escaping.
## Operational replacement baseline
The user expanded the original bootstrap scope to replace the existing discussion
workflow before introducing intelligent adapters or a legacy importer. Planning is
a concrete ninth module, not a custom workflow engine. A plan records editable scope,
dependencies and externally executed results. Starting/completing steps checks their
dependencies and accepted decisions. No repository command is executed by Planning.
Plans/steps can be reopened and revised when observations change.
DEC approval is an explicit human-attestation command, with actor, reason and time.
Accepted records are immutable through the CLI; revision creates a new linked draft.
Acceptance supersedes the prior accepted DEC. Decision and plan changes preserve
the previous complete file under `.history`, linked by SHA-256. Hashes detect broken
chains; they are not signatures or protection against someone rewriting every file.
Cross-record supersession uses per-file atomic publication; validation diagnoses
incomplete links. There is no distributed transaction or automatic history repair.
Verification separates structural validity, mechanical readiness and human judgment.
PlanCoordinator consolidates valid Plan results without invoking an adapter, records
SYSTEM_PLANS receipts and invokes existing EPIC propagation. Planning owns content-bound
scope reviews of cancellations; Verification coordinates public mutations/reconciliation
without a reverse dependency. Reads expose the same pending reasons without writes.
Explicit reopening leaves time to change Plans. Legacy optional fields are omitted
to preserve historical digests. See [the contract](plan-consolidation.md).
For inspection-only Works without Plans, manual
readiness requires explicit criteria, resolved questions, reviewed DECs and terminal
plans. Completion records criterion-to-artifact mappings, a stable scope digest,
human approval, and canonical integration file digests or a reason no update is
needed. Canonical-file hashes are historical snapshots; later source evolution does
not invalidate an old delivery. Current completed Work records must still match
their frozen scope. Archive retains every file. Reopening preserves completion and
lifecycle history and permits new discussion/evidence.
Project owns provider-neutral entry resources copied into `.ai-engineering` by
`init`/`onboard`, including a machine-readable manifest. A managed root `AGENTS.md`
block points to those resources while preserving surrounding rules. Changed
instructions are backed up; repeated onboarding is idempotent. Context includes the
guide. This supports agents that inspect the project; it cannot force discovery by
an arbitrary agent. `status` and `next-actions` derive diagnostics from persisted
state without executing work or inventing human approval.
## Discussion refinement and adapter boundary
Discussion still owns refinement; DEC and Plan remain its downstream commitments.
Topics and surveys are functional records in Discussion. Legacy threads are derived
as implicit topics; reads never migrate files. Answers append explicit supersession
links. Archive/restore dispositions retain proposals and require policy/evidence.
There is no separate Idea entity. See [record contracts](discussion-slice.md).
Agent is the tenth module. `AgentAdapter` accepts immutable context/task/executor
values and returns a typed `AgentProposal`; it receives no filesystem Path, persistence
service or execution tools. Only two deterministic adapters are registered. General
selects an activity when omitted and provides fallback for unspecialized activities;
an explicit activity selects its configured executor. Classification in fixtures uses
task markers, not natural-language model interpretation.
AgentService validates the entire proposal before applying it through domain APIs.
It rechecks the source fingerprint under the project lock to reject concurrent stale
application. A RUN preserves source digest, selected executor, requester, task,
proposal, applied references and terminal/error state. Completed request IDs provide
idempotent replay of identical input. An interrupted APPLYING run blocks new runs
pending inspection. Publication is atomic per file, not a rollback transaction;
FAILED records and validation expose partial application for deliberate repair.
Verification reads run provenance and computes staleness from canonical semantic
sources, excluding run bookkeeping. State checks never invoke an adapter. A summary
is a recorded result; fresh context does not implicitly rerun it. Adapter output
cannot provide human survey answers, approve DECs, complete Works or execute commands.
Typed records and nested proposal values have Native Image reflection hints.
The initial slice did not add provider integration; the local CLI slice below extends it.
## Local provider CLI transport
PLN-0003 implements the human-selected Codex/Claude CLI transport for Discussion and
synthesis. The agent module retains the same public adapter boundary. Its internal
LocalProcess uses fixed ProcessBuilder vectors, bounded streams, virtual threads,
timeout/descendant termination and private temporary workspaces. It receives no
engineering root. Provider tool/configuration controls constrain proposals, while
OS/provider policy remains separate. The full contract and verified CLI references
are in [cli-adapters.md](cli-adapters.md).
Versioned wire schemas normalize provider output into existing AgentProposal values;
the framework assigns identity and performs ownership/policy preflight. Classification
can request clarify surveys. An explicit activity skips that provider call. Immutable
previous RUNs travel in context, but derived run bookkeeping stays out of semantic
source fingerprints. Only validated results publish canonical RUNs. Earlier transport
failures return safe diagnostics without mutating Work state or storing raw stderr.
Optional invocation provenance captures observed version, configured role/model,
duration and output digest. Absent optional fields are omitted to preserve older
fingerprints/digests. Setup collects/validates all answers before initialization and
does not invoke providers. No Node SDK, HTTP client framework or external service is
required by tests. Deterministic JDK subprocess fixtures use the production transport.
## EPIC coordination
PLN-0002 implements DEC-0003 within the existing modules. Work owns the EPIC marker,
definition, forest topology, revision history and explicit policy authorization.
Verification coordinates lifecycle writes and checks affected ancestors, using
Artifact for owned aggregate receipts. No extra module, broker, workflow engine or
agent invocation is needed. Low-level storage callers must reconcile explicitly;
public CLI/Verification lifecycle entry points propagate within the project lock.
Policy authority binds parent/important-child scopes and links, excluding execution
status. Important child completions and local readiness control RESULTS completion;
DECOMPOSITION remains a reviewed human delivery. System completions record their
origin, policy delegation and receipt, with humanApproved=false. Historical direct
human completions keep their existing digest/approval semantics.
Frozen EPIC scope digests include current important delivery records; optional
execution can continue independently. Deterministic serialization uses ordered maps
and canonical records across JVM/native processes. Automatic receipts exclude prior
receipts from their input key, allowing reuse after interrupted publication.
Reconciliation derives state from files; no mutable in-memory index is authoritative.
Details and explicit reopening/reauthorization rules are in [epics.md](epics.md).
## Earlier framework review and migration
@@ -107,7 +237,8 @@ No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic hou
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
There is no automated legacy importer. Migration is deferred until the operational
replacement is established. A future importer 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.
+92
View File
@@ -0,0 +1,92 @@
# Local CLI adapter contract
PLN-0003 implements the transport/capability choices recorded in WRK-0001/SVY-0001:
Codex and Claude local CLIs, for Discussion and synthesis returning proposals.
DEC-0002 supplies the accepted routing/portable-context direction. Source repository
editing, command execution, direct provider APIs and arbitrary CLI arguments are
outside this slice. The AIE binary itself still requires neither JVM nor Node.
Using an optional adapter requires that provider's CLI and its own authentication.
## Invocation boundary
Adapters launch a fixed argument vector with ProcessBuilder, never a shell. Each
invocation has a private temporary working directory containing only schema/output
files; task and immutable portable context arrive through stdin. AIE does not give
the provider an engineering root, source repository working directory or mutation
service. Claude built-in tools are disabled. Codex command/agent/app/hook features
are disabled and it runs in read-only sandbox mode with approval escalation off.
No bypass-permissions flag is used. Provider/OS policies remain authoritative;
these controls are not a claim that AIE is an OS sandbox.
Codex uses exec, ephemeral mode, ignored user config, disabled shell/agent/hooks/apps
features, JSON Schema and a bounded final-message file. Claude uses print mode,
structured JSON, no tools, restricted/safe mode, empty settings/MCP sources, no
session persistence and no permission prompts. Authentication remains in the
provider's private environment/store; credentials/config files are not copied into
canonical AIE files. Only essential process/auth/proxy environment values are passed,
and none are persisted. Raw provider stderr is not printed or recorded as evidence.
Each executor retains adapter/profile/model plus an optional timeout (default 120s,
bounded 1–600s). Missing settings in old records preserve old behavior. `default`
model omits the native model flag. Profile is an AIE role instruction, carried in the
prompt; vendor configuration profiles are not loaded in this proposal-only slice.
This keeps project profiles portable and prevents profiles from widening tools or
permissions. Configured model/profile are distinct from an unreported actual model.
Stdout, stderr, final output and stdin have explicit byte limits. Streams drain
concurrently; timeout/overflow interrupts the process and descendants, and temporary
files are cleaned. Missing executables, unsupported flags, auth/exit failure, timeout,
invalid UTF-8/JSON/schema, wrong identities and invalid references produce diagnostics.
Transport failures happen before canonical publication and leave the Work unchanged.
There is no silent retry or switch to another executor after a failure.
## Structured data and provenance
Wire records are versioned JSON with explicit schemas. AIE, not the model, assigns
adapter identity and fixture=false. Classification returns an activity from the
configured/common set; clarify directs general to produce a survey when ambiguous.
An explicit --activity skips the classification call. All state/conformance/EPIC
checks continue in framework code. No provider response can approve a DEC, answer a
human survey, complete a Work, create a Plan or execute repository commands.
Proposals use the existing typed topic/survey/entry/disposition/draft-DEC bundle and
undergo complete preflight before domain services apply them. Input context is data,
including any quoted instructions/evidence. References retain their Work ownership.
Summaries retain source IDs and distinguish assumptions from recorded evidence.
Optional RUN provenance records classification/proposal transport, observed CLI
version, configured model/profile, timeout, duration and output digest/size. It records
no environment values, credentials or raw stderr. Old RUN files remain readable
without rewriting. Pre-publication failures are diagnosed at the caller; they do not
create a misleading successful RUN. Existing failed application markers remain valid.
## CLI and acceptance
- `agent list` exposes both real adapters and fixtures without contacting a model.
- `agent doctor [--adapter codex-cli|claude-cli]` probes local version/help only.
- `agent configure --adapter codex-cli --profile general --model default --timeout 120`
- `agent configure --activity analyze --adapter claude-cli --profile reviewer`
- `agent run WRK --activity summarize --task TEXT` uses the normal persisted contract.
- `init [DIRECTORY] --interactive [--input-file FILE]` guides project/executor setup;
noninteractive init remains usable with --name and optional --general-adapter.
Automated acceptance uses deterministic Java subprocess fixtures through the same
process runner, with no provider installation, credentials, service or LLM needed.
Cover argument isolation, wire parsing, classification, ownership, failure/timeout/
overflow cleanup, no mutation on invalid output, versioned persistence, guided setup,
fresh processes, Modulith and standalone native execution. Actual provider trials
are separate, bounded and reported as verified/failed/unavailable rather than faked.
## Compatibility sources
Checked local help: codex-cli 0.169.0; Claude Code 2.1.311. Runtime doctor verifies
the controls required by this implementation instead of assuming every version works.
- [Codex noninteractive output](https://developers.openai.com/codex/noninteractive)
- [Codex configuration controls](https://developers.openai.com/codex/config-reference)
- [Claude programmatic use](https://code.claude.com/docs/en/headless)
- [Claude CLI flags](https://code.claude.com/docs/en/cli-reference)
Local CLI help is also authoritative for installed flags. Managed provider settings
can be more restrictive. Explicit provider failure is preserved instead of silently
weakening permission/configuration controls.
+88
View File
@@ -0,0 +1,88 @@
# Discussion refinement contract
Discussion remains the refinement space inside Work; DEC and Plan retain their
existing roles. There is no separate Idea entity or mandatory extra workflow stage.
## Records and compatibility
Topics (`TOP`), surveys (`SVY`), dispositions (`DSP`) and agent runs (`RUN`) have
Work-local decimal IDs. Work IDs remain hexadecimal. Work reference lists for these
records default to empty when absent. Reading legacy records never rewrites them.
Existing free-form discussionId threads remain valid and appear as implicit topics;
an empty Work presents implicit topic `main`. Formal topics can reference original
discussion entries without rewriting those entries.
Records reside in Work-local `topics/`, `surveys/`, `dispositions/` and `agent-runs/`.
Prose uses Markdown bodies with documentVersion 2 and schemaVersion 1 metadata.
Topic and survey revisions preserve complete prior files with SHA-256 links under
their `.history/` directories, following decision/plan conventions. New files are
published before Work references; interrupted cross-file writes are diagnosed.
A survey owns immutable question definitions and append-only answers. QST and ANS
IDs are survey-local. Each question identifies a topic and nonempty options numbered
from 1, optional recommended option, single/multiple selection and discussion sources.
An answer selects valid options and/or supplies nonblank free text. Recommendation
alone is never an answer. Revised answers explicitly supersede the preceding answer
to that question, keeping all versions; only the latest determines pending questions.
Revised answers are exposed for review and never rewrite accepted decisions/plans.
Dispositions archive/restore a proposal in Discussion, with actor, reason and source
entry. Archive requires owned, integrity-checked ART evidence and project policy
`reversible`; the default is `review-only`. It preserves the source and can be undone.
Questions/responses are resolved through their own contracts, not hidden by archive.
## Adapter contract
Project configuration optionally contains `agents`: general executor, per-activity
executors and archivePolicy. Executor fields identify adapter, profile and model.
The first general configuration is explicit; absent configuration leaves ordinary
CLI usage available and agent execution reports a missing configuration.
The first slice provides `fixture-general` and `fixture-reviewer`. They are deterministic
test adapters, not real semantic intelligence or provider integrations. Refinement
fixtures accept one idea per line, optionally prefixed `Topic: idea`. Activities are
refine, analyze and summarize; fixture classification uses explicit task markers.
The later [local CLI slice](cli-adapters.md) adds actual Codex/Claude proposals using
the same domain contract and optional invocation provenance.
Input includes immutable Work/project/context records, task, optional activity and
requester. Output is a typed proposal bundle: topics, surveys/questions, entries,
dispositions, optional DEC draft and summary. Output identifies fixture provenance
and sources. The adapter receives no persistence service, project Path or execution
tools. Framework validation checks ownership and all proposed references before
application. An invalid bundle has no side effects. Agent proposals cannot supply
survey answers, approve DECs, complete Works or execute source commands.
General is selected when an activity has no configured specialization. Explicit
activity overrides fixture classification. Canonical RUN records preserve requester,
selected executor, task, source fingerprint, proposals, applied references and result.
An optional request ID makes identical completed requests idempotent; reuse with a
different request is invalid. Interrupted/failed application remains diagnosable.
Fingerprints exclude run bookkeeping; summaries expose whether semantic sources
changed. State checks use framework code, never an adapter invocation.
## CLI surface
- `topic create/list/show/update WRK ...`
- `survey create/list/show/history WRK ...`
- `survey question WRK SVY --text ... --option ... [--topic ...]`
- `survey answer WRK SVY QST [--choice 1] [--text ...|--text-file ...]`
- `survey ask WRK SVY [--input-file ...]` for guided answering
- `discussion archive/restore WRK DSC --reason ... [--evidence ART]`
- `agent list`, `agent configure --adapter ... [--activity ...]`
- `agent run WRK --task ... [--activity ...] [--request-id ...]`
- `agent history/show WRK ...`
Inspection supports JSON. Context includes topics, surveys, dispositions and run
provenance, references actual evidence and remains deterministic. Structural
validation covers new references/history; mechanical readiness includes unanswered
survey questions and empty surveys. Interactive answering requires an actual console
or explicit input file; noninteractive commands never wait indefinitely for input.
## Acceptance experiment
In a temporary project, persist raw ideas and two topics, obtain a survey from the
first fake, answer/revise it, attach explicit fixture evidence, analyze and archive
a proposal reversibly, prepare a DEC draft, and resume from another process using
the second fake. Verify ownership, evidence, history, pending questions, stable
context, old-format reads, invalid bundles, paths and native execution without JVM.
+78
View File
@@ -0,0 +1,78 @@
# EPIC contract
An EPIC is a Work with `epic: true` and a versioned definition under
`epic/<Work ID>.md`. Ordinary schema-1 Works default to `epic: false`; reads never
rewrite them. Definition revisions retain SHA-256-linked snapshots under
`epic/.history/<Work ID>/`. Links point to project-scoped Work IDs, not source repos.
## Topology and policy
The initial topology is a forest: one parent per Work, nested EPICs allowed, no
self-links or cycles. Each child is important by default. Links and importance
changes require an actor/reason, preserve history and invalidate prior authorization.
Completed/cancelled parents must be reopened before policy or topology changes.
Modes: RESULTS waits for every important child to be COMPLETED with valid completion
evidence; an important CANCELLED child stays pending. Optional children are reported
without blocking. DECOMPOSITION leaves child results out of closure readiness and
requires the ordinary human-reviewed completion command for the parent's own output.
An empty important set never triggers automatic completion.
## Automatic completion and authority
RESULTS can close automatically only after `epic authorize --human-approved` records
explicit human delegation for the current policy, parent scope and child scopes.
The human authorizes the structured aggregate condition as sufficient for the parent's
criteria. Scope/policy changes make that authority stale. This is an audit attestation,
not authentication. Local questions, surveys, decisions, plans and evidence still need
to pass mechanical readiness. No model evaluates those conditions.
Automatic completion produces an owned ART receipt with policy/child completion
digests and maps parent criteria to that receipt. The completion has origin
SYSTEM_EPIC, humanApproved=false and a reference to the actual policy authorization;
ordinary completions remain HUMAN and require direct human approval. The receipt
does not pretend that the framework performed semantic acceptance or a source test.
## Propagation and recovery
The public lifecycle commands complete/cancel/reopen/update notify affected ancestors
inside the project lock and return a report to the requester. Important-child reopening
reopens RESULTS ancestors and clears archive while retaining old completion records.
Optional-child changes do not invalidate a delivery; DECOMPOSITION does not follow
child execution. A manually BLOCKED/CANCELLED parent is never automatically completed.
Nested completions propagate from descendants to ancestors.
An explicit `work reopen` on an EPIC suspends its automatic authority for replanning;
reopening caused by a changed important child preserves authority when scopes remain
the same. Adding children to a delivered EPIC therefore means explicitly reopening,
editing links/scopes and reviewing authorization again.
`epic check` is read-only. `epic reconcile` deterministically repairs missed
propagation from canonical child state, including after interruption between child
and parent writes. Repeated notifications do not duplicate completion or receipts.
No server, message broker, database or agent invocation is used. Invalid histories,
missing links and unsafe paths are diagnosed; arbitrary corrupted files still need
deliberate repair. Publication remains atomic per file, not a global transaction.
## CLI
Create ordinary Works, then configure/link them:
```sh
aie epic configure WRK-0001 --mode results --by agent --reason "Coordinate delivery"
aie epic link WRK-0001 WRK-0002 --by agent --reason "First slice"
aie epic link WRK-0001 WRK-0003 --by agent --reason "Second slice"
aie epic authorize WRK-0001 --by owner --reason "These results satisfy the EPIC criteria" --human-approved
aie epic show WRK-0001 --format json
aie epic check WRK-0001 --format json
aie epic importance WRK-0001 WRK-0003 --optional --by owner --reason "Explicit scope review"
# Review and authorize the revised policy before it can close automatically.
aie epic history WRK-0001 --format json
aie epic reconcile WRK-0001 --requester agent --request-id resume-1 --format json
```
`epic unlink` retains prior definitions in history. Context includes parent, policy,
children, pending reasons, authority and completion provenance. Results are stable
for unchanged canonical files. Configuring an EPIC does not create or execute children.
Real model adapters, automatic decomposition proposals and legacy import remain out
of this slice. Zelda is not modified by its implementation or temporary experiments.
+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.
+49
View File
@@ -0,0 +1,49 @@
# Deterministic Plan consolidation
WRK-0002/DEC-0001 defines Step → Plan → Work consolidation. A completed last
required step completes its Plan; each completed Plan rechecks all Plans owned by
the Work. Completion checks never invoke an agent. Acceptance criteria remain in
the Plans/steps, with their existing results, evidence and decision approvals.
The required set must contain a real completed delivery. Empty Works/Plans remain
open. OPEN/ACTIVE steps or Plans, unresolved questions/surveys, empty surveys and
draft decisions remain pending. Explicit BLOCKED/CANCELLED states require explicit
resumption. Cancelling an item does not deliver it: `plan exclude WRK PLN [--step
TSK] --by NAME --reason TEXT` records a scope review of a cancelled item, retains
it and its history, and excludes only the reviewed content from the required set.
Changing that content invalidates its exclusion. Dependencies still require actual
completion; an exclusion does not satisfy a dependency.
`work reconcile WRK [--requester NAME] [--request-id KEY]` recovers missed
coordination. Mutation commands call the same coordination API. `work check`,
status, next-actions and context are read-only. Context/JSON and mutation reports
expose consolidation state and pending Plans, plus the existing EPIC report.
Planning owns optional versioned `exclusions[]` on a Plan, with target, content
hash, actor, reason and timestamp. Verification owns coordination and receipts;
Planning never imports Verification. A new SYSTEM_PLANS Work completion has
humanApproved=false, by=system:plans and optional `aggregation` provenance naming
an owned ART receipt, input digest, requester and request ID. The receipt identifies
the exact Plan revisions/hashes, including reviewed cancellations. Work prose
criteria may be automatically linked to this aggregate receipt for compatibility;
this records execution aggregation, not semantic proof of prose or a new human
approval. No manual Work-level criterion mapping is required.
Receipts use origin `ai-engineering:plans:<receipt-sha256>`. Their input hash omits
framework receipts so a published receipt can be reused after interruption. Final
completion freezes the full scope including the receipt. Recovery validates
integrity/history, consolidates Plans, publishes/reuses a receipt, records completion
and invokes existing EPIC reconciliation. Publication is atomic per file; malformed
or orphan records require explicit repair rather than silent deletion.
Existing completed Works and legacy serialized hashes remain unchanged. New
optional fields are omitted when absent. Manual completion remains available for
inspection-only Works without Plans. Adding a Plan to a completed Work requires
explicit reopening; unchanged old Plans do not immediately reclose a reopened Work.
Existing EPIC policy/authorization continues to govern EPIC completion.
Acceptance tests use disposable fixtures and a configured adapter that fails if
called. Required cases cover multiple Plans, last-step completion, explicit Plan
completion, cancellations/scope revisions, unresolved discussion/surveys/DECs,
empty sets, reopening, interrupted publication/replay, legacy data, corruption,
EPIC propagation and independent-process/native continuity.
+317 -22
View File
@@ -57,6 +57,9 @@ processes. The adapter clears inherited `GIT_*` variables and disables optional
```text
.ai-engineering/
ai-engineering.yaml
README.md # portable agent entry point
AGENTS.md # provider-neutral instructions
protocol.json # discovery manifest and capabilities
.gitignore
.local/write.lock # ignored, no semantic state
contracts/ # reserved for project contracts
@@ -64,8 +67,19 @@ processes. The adapter clears inherited `GIT_*` variables and disables optional
.sequence.yaml # canonical high-water mark; commit this
WRK-0001-improve-scene-editor/
work.md
epic/WRK-0001.md # present when epic: true
epic/.history/WRK-0001/r0001.md
discussions/DSC-0001.md
topics/TOP-0001.md
topics/.history/TOP-0001/r0001.md
surveys/SVY-0001.md
surveys/.history/SVY-0001/r0001.md
dispositions/DSP-0001.md
agent-runs/RUN-0001.md # canonical provenance; version this
decisions/DEC-0001.md
decisions/.history/DEC-0001/r0001.md
plans/PLN-0001.md
plans/.history/PLN-0001/r0001.md
artifacts/
references/
experiments/
@@ -77,36 +91,119 @@ processes. The adapter clears inherited `GIT_*` variables and disables optional
```
`work.md`, discussion and decision files contain YAML front matter, delimited by
`---`. Work and draft DEC files retain their typed fields in front matter; trailing
Markdown in those documents remains noncanonical. Discussion files use the Markdown
body for prose as described below. There is no Java object serialization and no
`---`. Work fields remain in front matter; trailing Work notes are noncanonical.
New discussion/decision narrative and plan descriptions use version 2 Markdown
bodies, with typed metadata in front matter. Legacy YAML-only discussions and draft
DECs remain readable without rewriting. There is no Java object serialization and no
dependency on conversation state.
Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`,
`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`,
`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`. Each repository snapshot
`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`, `plans[]`,
`completions[]`, `events[]`, `archived`, `topics[]`, `surveys[]`, `dispositions[]`,
`agentRuns[]`, `epic`. Operational, refinement and EPIC fields default to empty/false
when absent in older schema 1 Works. Updated CLI versions write them explicitly;
older CLI binaries that reject unknown fields cannot read these extended records.
Each repository snapshot
records `repositoryId`, relative `path`, exact `head` commit and `dirty`. An empty
repository records `UNBORN`, not an invented commit. Snapshots are taken at Work
creation and remain stable; they are not claims about later experiments.
Work IDs are project-wide, monotonic `WRK-` numbers with at least four digits. A
persisted sequence reserves identity before publishing a Work; crashes may leave gaps.
Do not remove or rewind the sequence. Discussion/decision/artifact IDs are **Work-local**;
Work IDs are project-wide, monotonic `WRK-` identifiers with an uppercase hexadecimal
suffix of four to nine digits: `WRK-0001` through `WRK-FFFFFFFFF`. The sequence passes
from `WRK-0009` to `WRK-000A`, then `WRK-000F` to `WRK-0010`. Zero is not a Work ID;
lowercase, `0x` prefixes and non-hexadecimal characters are rejected. Listing uses
numeric hexadecimal order, including when the width grows beyond four digits.
A persisted sequence reserves identity before publishing a Work; crashes may leave
gaps. New `.sequence.yaml` files use their own schema version 2:
```yaml
schemaVersion: 2
lastWork: "000A"
```
`lastWork` is the highest reserved hexadecimal suffix, written as a quoted uppercase
string. `"0000"` represents no reservation. Work records and project configuration
continue to use protocol schema version 1; the sequence file has an independent format.
Legacy schema version 1 counters with a decimal numeric `lastWork` remain readable.
Existing Work IDs, directory names and references are not renamed. Their suffixes
are interpreted as hexadecimal from this version onward. To protect prior reservations,
the legacy high-water mark is converted by identifier spelling: decimal counter 16
reserved `WRK-0016`, so it becomes hexadecimal `"0016"` (0x16), even if that Work was
removed. The next identifier is `WRK-0017`. This deliberately leaves any gaps below
that reservation unused. Read/validation commands do not rewrite legacy counters;
the next creation atomically writes version 2 under the project lock. Use the updated
CLI for hexadecimal IDs and version 2 sequence files.
Do not remove or rewind the sequence. Discussion/decision/artifact/plan IDs remain decimal and are **Work-local**;
their full identity is `(project, Work ID, child ID)`. Work reference arrays determine
history order. Directory names are a convenience; ID stability does not depend on title.
Duplicate Work IDs and directory/record mismatches fail validation.
Initial statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` permits
reorientation without irreversible lifecycle gates. Completion currently records intent;
it does not prove acceptance criteria. Conformance automation belongs to Milestone 5.
Statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` changes an open
Work's state but cannot set COMPLETED. `work complete` records the evidence mapping
and explicit approval described below. Terminal or archived Works reject mutation
until `work reopen --by NAME --reason TEXT` returns them to ACTIVE. Reopening preserves
all prior completion records and lifecycle events. Nothing is irreversibly closed.
Legacy COMPLETED Works without completion evidence remain readable, but validation
diagnoses the missing record; reopen and record reviewed evidence before archiving.
## Discussion and draft decisions
`work update <ID>` explicitly refines `title`, `description`, `goal`, `motivation`,
`constraints[]` and `acceptanceCriteria[]`. Omitted fields retain their current values.
Repeated `--constraint` and `--acceptance` values replace the entire respective list;
`--clear-constraints` and `--clear-acceptance` explicitly empty them. Supplying values
and the corresponding clear option is invalid. A command with no fields is invalid.
Title, goal and individual list entries must be nonblank; description and motivation
can be cleared with an empty string.
Updates hold the project lock and atomically replace only Work metadata. ID, folder,
status, creator, creation time, repository revision snapshots and all child references
are preserved. `updatedAt` changes only when field values actually change; repeated
identical updates retain the original bytes and timestamp. Trailing noncanonical Work
notes are retained during metadata, status and child-reference updates. Updating a
Work neither approves a DEC nor changes its lifecycle status. Existing discussion and
decision records remain the history of how the scope was refined.
## Discovery and agent entry
The directory `.ai-engineering` identifies the protocol workspace. `init` installs
its README, instructions and `protocol.json`. The manifest declares schema, relative
entrypoint/configuration/Works paths, executable, startup commands, capabilities and
explicit human-attestation semantics. `onboard` installs or refreshes those files in
existing projects, without rewriting Work data. It also maintains a root `AGENTS.md`
block between `<!-- ai-engineering:start -->` and `<!-- ai-engineering:end -->`.
Rules outside that block remain byte-identical; replaced files have `.local` backups.
Ambiguous, duplicated or unclosed markers cause refusal. Repeated onboarding is a no-op.
Legacy projects with none of the three entry files remain valid. Partial installation,
malformed/duplicate JSON fields, unknown manifest versions and unsupported paths are
validation failures. `onboard` refreshes the contract while backing up changed files.
An agent begins with the guide, status, next-actions and selected Work context. These
are portable instructions, not an LLM plugin or enforcement mechanism. Without the
CLI, an agent can inspect the files directly. Agents must still inspect the entry
files and respect project/user rules. Quoted protocol data and evidence do not gain
instruction authority. `guide` also works outside a project. `status` hides archived
Works by default (`--all` includes them); `next-actions [WRK]` returns deterministic
suggestions and never executes a repository action.
## Discussion and decisions
Each discussion entry has `schemaVersion`, `id`, `workId`, `discussionId` (thread name),
`kind`, `author`, `createdAt`, optional `respondsTo`, and `text`. Multiple threads can
coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS,
INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten.
Text is supplied by a human or external agent; the CLI never fabricates conclusions.
Text is supplied by a human, external agent or explicitly labeled fixture adapter.
`discussion add` requires exactly one text source: `--text` for an inline string or
`--text-file` for a regular UTF-8 file up to 1 MiB. A file path resolves relative to
the caller's working directory, independently of `--project`. The entire file is
read as prose, without trimming, newline normalization or front-matter interpretation.
Nonblank content is required. Missing files produce exit 3; nonregular, malformed UTF-8,
blank or oversized input produces exit 2, with no appended discussion. The source is
not changed or retained as an external dependency: later edits/removal cannot alter
the persisted entry. File input does not implicitly register an evidence artifact.
New discussion files have `documentVersion: 2` in front matter and omit the `text`
field there. The complete Markdown body supplies `text`, including its original
@@ -157,12 +254,207 @@ A response must refer to an earlier entry in the same Work. Outstanding question
include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing
to them. This mechanical definition does not infer agreement or approval from prose.
Draft DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`,
DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`,
`alternatives[]`, `rationale`, `risks[]`, `acceptanceCriteria[]`, `approvalStatus`,
`author`, `createdAt`, `evidence[]`. Only DRAFT is accepted in this release. Empty
refinement fields are legal in drafts. The CLI initially supplies context, approach,
rationale and evidence; remaining fields can be refined in the canonical YAML.
No approval, supersession or autonomous operational decision is implemented.
`author`, `createdAt`, `evidence[]`, narrative `text`, `revision`, `previousHash`,
`updatedAt`, `updatedBy`, `changeReason`, `approvals[]`, optional `revises` and
`supersededBy`. Legacy draft fields default to revision 1, no approvals/links and
empty narrative. Narrative uses document version 2; the JSON `text` field remains explicit.
Statuses: DRAFT, ACCEPTED, REJECTED, SUPERSEDED. `decision update` changes only drafts,
recording actor/reason and a snapshot. Lists replace entire lists; explicit `--clear-*`
options clear them. `--text`/`--text-file` supplies narrative. Acceptance requires
nonblank context/approach/rationale, actor/reason and `--human-approved`. This flag is
an attestation that approval occurred, not authenticated identity or OS permission.
An agent cannot infer approval from a proposal or a prior status. Rejection retains
the proposal. `decision revise` creates a new draft linked to an accepted/rejected
DEC. Accepting that draft supersedes the prior accepted DEC, preserving both records.
Operational choices during execution remain distinct from these formal commitments.
## Topics, surveys and adapter runs
[Discussion refinement contracts](discussion-slice.md) specify TOP/SVY/DSP/RUN records,
questions, answers, sources and commands. These IDs are decimal and Work-local;
QST/ANS IDs are survey-local. Topic and survey revisions use the same SHA-256 history
convention as decisions/plans. Existing discussionId threads are implicit topic views,
including `main` for an empty Work, without canonical file changes.
Questions have a topic, suggestions, optional recommendation, single/multiple selection
and discussion sources. Free-text answers are always available. A revised answer
supersedes the prior one without deletion; only the latest determines pending status.
Revision signals a review and does not change accepted decisions/plans. Guided console
answering and noninteractive commands use the same persisted contract.
Project configuration can optionally include:
```yaml
agents:
general:
adapter: fixture-general
profile: fixture
model: deterministic
activities:
analyze:
adapter: fixture-reviewer
profile: fixture
model: deterministic
archivePolicy: review-only
```
Without agents configuration ordinary commands still work. Agent execution requires
an explicitly configured general. Unknown activities fall back to general; configured
specializations win. Fixture adapters and local codex-cli/claude-cli are available. An explicit
`reversible` policy permits archive with owned ART evidence and a reason; restore
preserves the source and disposition history. Questions/responses cannot be hidden
through proposal archive. Policies are metadata, not OS enforcement.
RUN records preserve request ID, raw task, requested/chosen activity, requester,
executor, sourceHash, fixture proposal bundle, applied references, status, error and
timestamps. Proposals have typed source links; `@request` in a proposal resolves to a
persisted raw Discussion NOTE. Framework checks validate output before application.
Adapters cannot generate survey answers or human approvals. Fixture analyses are
synthetic observations, never claims about a real experiment or investigation.
Source fingerprints include semantic project/Work/discussion/survey/evidence/decision/
plan state, excluding run bookkeeping and Work modification time. Context derives
staleness without invoking an adapter. A proposal-changing run can already be stale
against its own resulting state; sourceHash identifies the input it actually saw.
Identical completed request IDs replay the recorded result even if context later
changes; use a new ID for a new computation. Changed request input with the same ID
is invalid. Interrupted APPLYING records block further runs pending inspection;
FAILED records retain applied references. This is diagnostic publication, not rollback.
## Local provider executors
Executor adds optional timeoutSeconds, bounded 1–600; omission means 120 seconds.
Old records remain readable without writing. Null timeout/provenance fields are
omitted from serialized values so legacy fixture digests remain stable. Local CLI
profile/model names are constrained tokens, not arbitrary flags; default model omits
the provider flag. Profile is an AIE role instruction. Provider configuration profiles,
private session state and credentials do not become portable AIE configuration.
The [CLI adapter contract](cli-adapters.md) defines bounded process invocation,
required controls, versioned schemas, failure semantics and setup. Wire output cannot
set adapter/fixture identity or human authority. The normal complete proposal bundle
must validate before publication. RUN adds optional provenance with classification
and/or proposal invocation: transport, observed CLI version, configured role/model,
durationMillis, timeoutSeconds, outputSha256 and outputBytes. No raw environment or
stderr is canonical. A pre-publication transport failure leaves the Work unchanged.
General can classify a request into configured/common activities. Explicit activity
skips classification. Clarify requires a survey with suggestions and leaves human
answers pending. Prior RUN outputs are supplied as derived interpretations; source
fingerprints still follow canonical semantic sources. State/conformance/EPIC checks
never invoke a provider. Setup/doctor similarly never sends a model request.
## Plans and execution records
Plans are optional, proportional Work-local records (`PLN-0001`). A plan contains
title, Markdown description, referenced decisions, steps, lifecycle status, creator,
timestamps and revision metadata. Each step (`TSK-0001`, decimal and plan-local)
records title/description, acceptance criteria, dependencies, status, result, evidence
and modification time. Statuses match Work's five values but describe external work.
Step dependencies must exist in that plan and be acyclic. Starting or completing a
step requires completed dependencies and accepted referenced decisions. Completion
requires result text (`--reason`) and owned evidence. `plan status COMPLETED` requires
at least one completed step and all required steps completed; cancelled steps need
explicit scope review with `plan exclude --step`. Exclusions retain the cancelled
record and bind its content hash, actor and reason. Legacy Plans remain readable
without rewriting. Reopen a terminal plan with
`plan status ACTIVE` before editing; reopen terminal steps before changing scope.
Reopening a prerequisite first requires reopening/cancelling its dependent steps.
If a DEC is superseded, reconsider the plan and update its references before execution.
Plan/step changes retain previous plan snapshots. `decision history` and `plan history`
walk `.history/<ID>/rNNNN.md`; `previousHash` links each revision to the complete prior
UTF-8 file. Validation checks identity, numbering and hashes. Hashes are integrity
links, not signatures: manual rewriting of an entire chain is not prevented. New
records start at revision 1. A snapshot published before an interrupted current-file
replacement can be reused only when identical; conflicting history is never overwritten.
The CLI does not execute steps, tests or validation-command metadata. Humans/agents
run real commands externally and record observations, commands, source revisions and
results in evidence. Plans support explicit adaptation; no autonomous OODA engine or
fixed four-phase pipeline is implemented.
## Completion, integration and archive
Works with executable Plans derive completion from those Plans. Mutation commands
and `work reconcile WRK` consolidate the last completed step into its Plan and
recheck all associated Plans. Completed required Plans and no pending questions,
surveys, draft DECs or explicit blocking states produce SYSTEM_PLANS completion,
without a model call, repeated human delivery approval or manual Work-level criterion
mapping. Empty sets never auto-complete; reviewed cancellations retain history.
New Plans after delivery require reopening. Unchanged old Plans do not immediately
close an explicitly reopened Work/Plan. See [Plan consolidation](plan-consolidation.md)
for records, provenance and recovery. `work check` reports consolidation pending
reasons; status/context/next-actions remain read-only. Existing EPIC authority and
policy continue to govern EPIC completion.
For inspection-only Works without Plans, `work check` checks mechanical readiness: explicit acceptance criteria,
no unresolved questions/issues or draft DECs, and terminal plans. Noncancelled plans
must reference currently accepted decisions. Small Works can close without a DEC/plan.
The check cannot determine whether arbitrary prose/evidence proves the desired outcome.
`work complete` requires human attestation, actor, summary and one unique
`--criterion N=ART-0001[,ART-0002]` mapping per criterion (1-based). Artifacts must
belong to the Work and pass integrity checks. Completion captures criterion text,
evidence IDs, approval metadata and a deterministic SHA-256 digest of scope, source
snapshots, discussion, decisions, plans and artifact metadata. Current COMPLETED Work
data must still match that digest. Reopened Works retain earlier snapshots as history.
Supply updated canonical project files via `--integration PATH` or explicitly state
`--no-integration-needed REASON`. Integration paths are safe project-relative regular
files outside `.ai-engineering`; their hashes identify contents at closure. Those
files can evolve later without invalidating a historical completion. The CLI records
the attestation/snapshot; it does not prove that the file changed or infer its meaning.
Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is required.
`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work
archived. It retains all files and prior approvals/results. `work reopen` clears
archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion.
Importing legacy agendas and Lessons is deferred to a later, separately tested importer.
## EPIC policy and system completion
[The EPIC contract](epics.md) defines topology, authority and recovery. An EPIC remains
a project Work, marked `epic: true`, with one versioned definition in its `epic/`
directory. Links use Work IDs, with important=true by default. Definitions preserve
mode, links, explicit authorization, editor/reason, revision and previousHash.
History follows the DEC/Plan snapshot convention. Initial topology is a forest.
RESULTS tracks verified important deliveries; optional children are reported without
blocking. Important CANCELLED remains pending. DECOMPOSITION uses ordinary reviewed
closure for the parent's own output and does not wait for execution. Empty important
sets never auto-close. Policy edits require an open parent and invalidate automatic
authority; `epic authorize --human-approved` binds the parent/important-child scopes
and current policy. Authorization is delegation for the structured aggregate condition,
not an inferred human approval of a future delivery.
Completion records add optional `origin` and `delegation`. Old records default to
HUMAN with no delegation and retain their digest semantics. HUMAN requires direct
humanApproved=true. SYSTEM_EPIC requires humanApproved=false, actor system:epic,
an actual policy authorization/history hash and request correlation. Its criteria map
to a framework-owned aggregate ART receipt containing policy/input and important-child
completion digests. The human's policy delegation attests that this condition suffices
for the parent criteria; the framework performs no semantic inference about prose.
Frozen RESULTS scope includes important completion records; optional execution can
continue independently. Important reopening reopens ancestors and clears their archive,
retaining prior completions. Explicit reopening of an EPIC suspends its authority for
replanning. Child-caused reopening preserves unchanged-scope authority. BLOCKED and
CANCELLED parents require explicit resumption. Nested propagation runs from descendants
to ancestors under the project lock, without calling any AgentAdapter.
Public CLI/Verification lifecycle APIs return the changed Work plus affected EPIC
reports when linked; plain Work output remains compatible. `--requester` and
`--request-id` correlate results. IDs correlate notifications rather than acting as a
global transaction log. `epic reconcile [WRK]` derives missed updates from canonical
files and does not duplicate a satisfied completion. A matching published receipt is
reused after interrupted completion. Invalid histories, missing children and orphan
publication are diagnosed; arbitrary corruption still needs deliberate repair.
Low-level storage callers must explicitly reconcile after lifecycle writes.
## Evidence and integrity
@@ -183,10 +475,13 @@ for large temporary results. No command creates large output files by default.
`work context --format markdown|json` loads only canonical project/Work files. It
includes all Work fields (metadata separately in Markdown), stored source revisions,
ordered discussion history/conclusions, explicit draft decisions, unresolved questions
ordered discussion history/conclusions, explicit decisions and approvals, plans/results, unresolved questions
and complete artifact references with integrity metadata. JSON has top-level
`schemaVersion`, `work`, `discussionHistory`, `decisions`, `outstandingQuestions`,
`artifacts`. It does not embed arbitrary evidence payloads.
`artifacts`, `plans`, `protocolGuide`, `topics`, `surveys`, `dispositions`, `agentRuns`,
`agents`, `epic`, `parentEpic`. Completion and lifecycle history are included
in `work`. It does not embed arbitrary evidence payloads or all revision snapshots;
use history commands when prior versions are relevant.
No export timestamp, current absolute path or live Git state is injected. Unchanged
files yield byte-identical output across new instances and processes. Export rejects
@@ -215,9 +510,9 @@ entry durability under sudden power loss depends on the host filesystem.
## Future contracts (design only)
- AgentAdapter: accept versioned context and return proposed questions, suggestions,
assumptions or draft content with provenance. The caller decides what to persist;
no provider or orchestration dependency is part of schema 1.
- Additional AgentAdapter transports and execution permissions: local proposal-only
Codex/Claude CLIs are implemented; direct provider APIs, repository execution and
vendor-native configuration profiles need separate contracts and authorization.
- OODA iteration: identify Work and prior observations, orientation, operational
choices and attempts. Phases can repeat or be skipped; no four-stage workflow gate.
- Attempt: stable identity, hypothesis, input references, exact repository revisions,
+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.