Files
ai-engineering/docs/work-guidance.md
T
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

7.8 KiB

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.

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.

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:

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:

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.