feat: add Work guidance and adaptive Plan experiments
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s

Persist explicit human discussion choices, DEC requests and approval policies. Add optional evidence-backed Plan experiments and align context, adapters and next actions under protocol contract 3.

Include WRK-000B decisions, plan history and verification evidence: 167 JVM tests, 25 focused checks, Jenkins fixtures and native smoke coverage.
This commit is contained in:
Nilton Constantino
2026-11-16 17:33:24 +00:00
parent a7e3a2fdfc
commit e7e8d95415
104 changed files with 4432 additions and 106 deletions
+11 -3
View File
@@ -41,10 +41,10 @@ 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, references and versioned EPIC policy/graph | project, filesystem |
| work | Work identity/lifecycle, human guidance/history, repository snapshots, references and 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 |
| planning | Plans, dependencies, step results, experiments and revision history | work, decision, discussion, artifact, filesystem |
| legacyimport | DF preview, original agenda evidence, provenance and prepared Work publication | filesystem, project, work, discussion, artifact |
| artifact | Small evidence payloads and integrity metadata | work, filesystem |
| agent | Adapter contract, deterministic fixtures, routing and proposal application | project, work, discussion, decision, planning, artifact, filesystem |
@@ -108,7 +108,15 @@ a concrete ninth module, not a custom workflow engine. A plan records editable s
dependencies and externally executed results. Starting/completing steps checks their
dependencies and accepted decisions. No repository command is executed by Planning.
Plan creation prepares deterministic draft-decision promotions through Decision,
Work owns optional human guidance and its choice/request history. New contract-3
Works begin without an inferred discussion mode and require human DEC approval.
Decision and Planning enforce that authority; explicit Work-wide waiver retains
system promotion provenance. Planning owns optional experiments inside its existing
revision chain and depends on Discussion to check unresolved planning commitments.
Verification and local CLI adapters expose the applicable conduct and OODA guidance.
Legacy absent fields are omitted to preserve historical digests.
Plan creation prepares eligible deterministic draft-decision promotions through Decision,
validates every reference before publication and records SYSTEM_PLAN provenance
with the causal Plan ID and no fabricated human attestation. Existing accepted
decisions are unchanged. Decision exposes prepared promotion/recovery operations;
+8 -1
View File
@@ -49,12 +49,19 @@ operations and onboarding from overwriting a newer contract. Compatibility inspe
remains available to explain the mismatch.
Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts
1 and 2, and existing contract-1 projects remain legacy compatible without any
1, 2 and 3, and existing contract-1 projects remain legacy compatible without any
Work migration. An import-enabled manifest requires contract 2 and the
`discussion-import` capability. This makes old contract-1 CLIs refuse the new
manifest before onboarding could overwrite its feature declaration. `onboard`
refreshes the entry files with backups; completed Works and history are unchanged.
Contract 3 adds human Work guidance and optional Plan experiments; it advertises
`work-guidance`, `human-decision-request` and `plan-experiments`. New Works ask for
mode and require DEC approval by default. Existing Works without guidance retain
their historical semantics until explicit adoption. Guidance is omitted when absent
and empty experiment collections are omitted, preserving completion digests.
See [Work conduct and OODA](work-guidance.md) for the behavior and commands.
The format catalog is deliberately small:
| Format | Current writer | Supported readers |
+2 -1
View File
@@ -7,7 +7,8 @@ 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
draft decisions remain pending. In guided Works, missing conduct, absent applicable
DEC approval, open experiments and unresolved DEC concerns also 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.
+13 -2
View File
@@ -391,8 +391,10 @@ 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.
`plan create --decision DEC` promotes referenced DRAFT decisions automatically,
without an adapter or LLM. Input, decision and revision-history validation runs
`plan create --decision DEC` promotes eligible DRAFT decisions without an adapter
or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC
needs human approval before Plan creation. Legacy Works retain prior promotion
semantics until explicit guidance adoption. Input, decision and revision-history validation runs
before promotion, under the project lock. Ordinary publication failures roll back
the attempted Plan and promotions. Publication is atomic per file, not a crash-proof
multi-file transaction: interrupted writes or failed recovery remain inspectable
@@ -574,6 +576,15 @@ incomplete staging outputs, ignored by readers; inspect and clean them manually
an interrupted write. Concurrent manual editors do not honor the CLI lock. Directory
entry durability under sudden power loss depends on the host filesystem.
## Work guidance and OODA
Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask
for human discussion mode and require human DEC approval by default; explicit
Work-wide waivers and requests retain human provenance. Guided operations enforce
the selected authority. See [Work conduct and adaptive implementation](work-guidance.md)
for commands, experiment criteria/results, affected execution and legacy behavior.
This preserves the existing loops and does not add a repository executor.
## Future contracts (design only)
- Additional AgentAdapter transports and execution permissions: local proposal-only
+8 -2
View File
@@ -123,12 +123,18 @@ Acceptance requires offline multi-Plan/no-model tests, legacy/fresh-process cont
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)
## Milestone 3 — Adaptive OODA
Contract 3 implements Work conduct and human DEC authority plus optional Plan
experiments, prior criteria, evidence-backed results and recorded reconsideration.
See [the implemented contract](work-guidance.md). Richer cross-repository Attempts
and autonomous orchestration remain future work.
Add observations, orientation, operational decisions and Attempts using the conceptual
contracts in protocol.md. Acceptance: experiment evidence changes the next action;
history prevents repeating an invalidated attempt without a stated new hypothesis.
No rigid Observe→Orient→Decide→Act pipeline or autonomous engine is implemented now.
The optional experiment records do not impose a rigid Observe→Orient→Decide→Act
pipeline or provide an autonomous repository engine.
## Milestone 4 — Coordinated repositories (design only)
+140
View File
@@ -0,0 +1,140 @@
# Work conduct and adaptive implementation
Contract 3 preserves the existing two loops: Discussion and implementation. DEC
connects the discussion to its autonomous Plan. Discussion depth and authority to
approve a DEC are independent human choices, persisted in `work.md` as `guidance`.
There is no new lifecycle or mandatory four-phase OODA pipeline.
## Human choices
A new Work starts with mode `UNSPECIFIED` and DEC approval `REQUIRED`. Ask the
human to choose `DIRECT` or `EXPLORATORY` when absent. Never infer the choice from
task simplicity, urgency, a model proposal, or an earlier Work. Carry a recorded
choice into later sessions rather than asking it again. The human alone changes
the choice; the AI can suggest exploration when many unknowns appear.
```sh
aie work create "Investigate rendering"
aie work guidance WRK-0001 --mode EXPLORATORY --by owner \
--reason "Human requested an architectural discussion" --human-approved
aie work guidance WRK-0001 --format json
```
`DIRECT` means resolve essential questions, prepare a DEC, then request its
applicable approval. `EXPLORATORY` means challenge the framing and assumptions,
compare viable alternatives, and periodically synthesize established points,
fragile premises, unknowns and recommended next investigations. The AI may suggest
that the discussion is mature. The human closes it and requests the DEC.
```sh
aie work request-decision WRK-0001 --by owner \
--reason "Human ended discussion and requested the next DEC" --human-approved
aie decision draft WRK-0001 --title "Rendering approach" \
--context "Measured problem" --approach "Agreed solution and adaptation limits" \
--rationale "Alternatives and consequences discussed"
aie decision accept WRK-0001 DEC-0001 --by owner \
--reason "Human approved this concrete DEC" --human-approved
aie plan create WRK-0001 --title "Implement rendering" --decision DEC-0001
```
By default the request authorizes the next DEC ID only, including revisions.
Use `--decision DEC-...` to explicitly request an existing draft after changing a
direct discussion to exploratory.
It does not approve its content or end every later discussion. Actor, reason,
time and attestation remain in guidance history. Repeating a request for the same
next ID is idempotent. Choices and requests are never inferred from NOTE or
CONCLUSION text or automatically extracted from survey answers.
## Approval and explicit waiver
DEC approval defaults to human review. Direct conduct does not waive it. A human
can explicitly waive approval for the entire Work, normally for very simple tasks:
```sh
aie work guidance WRK-0001 --approval WAIVED --by owner \
--reason "Human explicitly waived DEC approval for this simple Work" --human-approved
```
Mode and policy may also be supplied at creation with `--mode`, `--approval`,
`--choice-reason` and `--human-approved`; `--author` identifies the recorded actor.
Omitting the mode still leaves it unspecified. No choice is inherited by child
Works, EPICs, future Works or other projects.
Creating a Plan promotes valid drafts only under a recorded waiver in a guided
Work. The existing `SYSTEM_PLAN`, `planId`, `humanApproved: false` provenance remains.
An already human-approved DEC can be planned normally. Unknown mode, unrequested
exploratory drafts, outstanding discussion questions/surveys and unapproved DECs
cannot be bypassed by creating a Plan. A Plan with no formal DEC remains available
for small direct work only under the Work-wide explicit waiver; it cannot bypass the
default human-review policy. Model output cannot set guidance or human authority.
Restoring `--approval REQUIRED` prevents further execution against system-promoted
DECs; revise and obtain human approval, or record a new explicit waiver. Decisions
already approved by the human remain approved. This does not rewrite historical
approvals or claim that system promotion was human review. These flags are audit
attestations, not authentication or permission grants for repository commands.
## Optional OODA experiments
When understanding the Work and when creating or executing its Plan, identify
uncertainties requiring measurement, investigation or simulation. A DEC should,
where useful, specify success conditions and commitments the implementation must
preserve. The agent chooses the next action from observations within those bounds.
Ordinary implementation needs no experiment record or extra OODA ceremony.
Experiments are optional records inside the Plan's existing revision chain. A
relevant experiment records its hypothesis, success criterion and invocation
before external execution:
```sh
aie plan experiment start WRK-0001 PLN-0001 --step TSK-0001 \
--hypothesis "Batching reduces latency" --criterion "p95 below 10 ms" \
--invocation "benchmark --scenario batching" --by agent --reason "Measure first"
# Run the actual simulation/benchmark externally, then attach its evidence.
aie artifact add WRK-0001 --file benchmark.txt --purpose "Measured batching result"
aie plan experiment finish WRK-0001 PLN-0001 EXP-0001 --outcome REFUTED \
--observation "p95 measured 17 ms" --interpretation "Batching is insufficient" \
--next-action "Measure query cost" --evidence ART-0001 --by agent --reason "Recorded result"
aie plan experiment list WRK-0001 PLN-0001 --format json
```
Outcomes are `CONFIRMED`, `REFUTED` and `INCONCLUSIVE`; open experiments cannot
claim results. Finishing requires owned integrity-checked evidence, interpretation
and a next action. Results are immutable; record another experiment to investigate
further. Repeating a failed hypothesis requires `--retry-of EXP-...` and
`--reconsideration TEXT` explaining the revised hypothesis or new evidence. This
records reconsideration; the framework does not semantically prove that a claim or
experiment is sound. Group routine attempts and record meaningful learning.
Open experiments block completion of their affected step and dependents. Without
`--step`, they affect the whole Plan. Independent steps and authorized investigation
can continue. All required experiments must have results before Plan completion.
When evidence questions a commitment in the DEC, finish with
`--questions-decision DEC-0001`. Continue authorized investigation and independent
work, but revise the DEC with the applicable request and approval before executing
affected implementation. Update the Plan to reference the accepted revision.
Dropping the questioned reference or replacing it with an unrelated decision does
not resolve the concern. The AI identifies semantic contradictions; the CLI enforces
the concern once explicitly recorded. It does not infer meaning from arbitrary prose.
## Context, agents and compatibility
Work context exports the selected guidance, human history and applicable instructions.
Plan context includes experiment criteria, results and revision history. `next-actions`
asks for missing mode, encourages exploration, shows required DEC review, reports
experiments/concerns, and recommends execution only under applicable authority.
Local model prompts follow the same conduct. Proposal validation rejects premature
DEC drafts before applying any part of an adapter bundle.
Contract 3 advertises `work-guidance`, `human-decision-request` and `plan-experiments`.
Inspect `aie project compatibility` and refresh entry files with `aie onboard`.
Contracts 1 and 2 and historical records remain readable, retaining old approval and
promotion semantics. Existing Works without `guidance` retain their representation;
adopt explicitly through `work guidance` after updating entry files. Never infer a
mode, rewrite delivered Works, or migrate historical evidence/receipts on a read.
Null guidance and empty experiments are omitted from serialization so legacy content
hashes and completion receipts remain valid.
The CLI records and validates state. It does not run repository commands, simulate,
evaluate prose criteria with a model, or orchestrate an autonomous executor.