Files
bquarkz f5d5db73c2
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
feat: add Work guidance and adaptive Plan experiments
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.
2026-11-16 17:33:24 +00:00

141 lines
7.8 KiB
Markdown

# 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.