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
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:
+11
-3
@@ -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;
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
@@ -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
@@ -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)
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user