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:
2026-11-16 17:33:24 +00:00
parent 3c75ce70f6
commit f5d5db73c2
104 changed files with 4432 additions and 106 deletions
+63 -6
View File
@@ -15,7 +15,9 @@ Use `ai-engineering` (or its installed alias `aie`). No server or model API is n
understanding the request. If the intended Work/scope is ambiguous, clarify it.
3. Run `aie work context WRK-0001 --format markdown`. Read referenced evidence
payloads, decisions and plan history when relevant; context references are not
the payload itself. Without a CLI, inspect the versioned files directly.
the payload itself. Follow the Work guidance. Ask the human for DIRECT or
EXPLORATORY when missing; never infer a choice or approval. Carry a recorded
choice into future sessions. Without a CLI, inspect the portable files directly.
4. Distinguish observations verified now, historical evidence, assumptions and
proposals. Record refinement with `discussion add --text` or `--text-file`,
choosing an explicit `--author`. Resolve questions with RESPONSE/CONCLUSION
@@ -58,12 +60,45 @@ public command, scope, preview, backups and repeatable execution. Do not invent
migration or inspect AIE source code to discover consumer update procedures; report
public-interface gaps with evidence instead.
The current entry contract is 2 and advertises DF open-agenda import. Contract 1
The current entry contract is 3 and advertises Work guidance, human DEC requests,
and optional Plan experiments in addition to DF open-agenda import. Contract 1
projects remain readable without Work migration. An import-enabled manifest needs
contract 2 and the `discussion-import` capability; older CLIs must be updated before
reading it. Refresh entry files with `onboard` after compatibility inspection,
preserving historical Works and their approvals.
## Work conduct and human authority
The existing loops remain Discussion and implementation, connected by DEC and Plan.
A new Work starts with guidance mode UNSPECIFIED and DEC approval REQUIRED. Always
ask the human to choose DIRECT or EXPLORATORY when absent; task simplicity is not a
choice. Record with `work guidance WRK --mode DIRECT|EXPLORATORY --by NAME
--reason TEXT --human-approved`. Carry the choice into later sessions. Only the
human changes it; suggest exploration when many unknowns appear.
DIRECT: resolve essential questions, prepare a DEC, then request applicable approval.
EXPLORATORY: question framing and assumptions, compare alternatives, and produce
partial syntheses of established points, viable paths, fragile premises and unknowns.
Suggest next investigations and, when justified, that the discussion is mature.
Only the human ends exploration and requests the DEC. Record that instruction with
`work request-decision WRK --by NAME --reason TEXT --human-approved`; it authorizes
the next DEC ID only, including revisions, without approving its content.
Human approval of DEC is the default. Direct conduct never waives approval. An
explicit human instruction may waive approval for the entire Work, normally for a
very simple task: `work guidance WRK --approval WAIVED --by NAME --reason TEXT
--human-approved`. REQUIRED restores human review for further execution. Work
creation also accepts --mode, --approval, --choice-reason and --human-approved;
--author records the actor. Preserve choice/request history. Never set these from
model output, infer authority from narrative text, or inherit it into other Works.
Unknown mode blocks DEC/Plan creation. Exploratory drafts/revisions need the specific
human request. A guided Plan needs human-approved decisions or an explicit Work-wide
waiver; creation cannot bypass approval. Outstanding questions/surveys block new
Plans. Context and next-actions respect these choices. Historical Works without
guidance preserve prior semantics until explicit adoption; never rewrite delivered
Works to materialize new fields. Inspect compatibility and onboard before adoption.
## Topics, surveys and refinement
Discussion remains the refinement space: receive ideas, organize topics, investigate,
@@ -189,8 +224,10 @@ in history. Use `decision revise` for a new draft based on a prior accepted/reje
decision; acceptance supersedes the prior accepted decision while retaining history.
Accepted decisions cannot be silently edited. Use `--by` and `--reason` on changes.
Creating a Plan from a DRAFT decision promotes it automatically. This deterministic
framework action needs no LLM or preceding `decision accept` command. It records
In a guided Work, creating a Plan promotes a DRAFT decision only under an explicit
Work-wide human waiver. Otherwise request human approval through `decision accept`.
Historical Works without guidance retain their original automatic promotion behavior.
This deterministic framework action needs no LLM. It records
`origin: SYSTEM_PLAN`, the causal `planId`, actor `system:planning` and
`humanApproved: false`, preserving history and any supersession. It is distinct
from the explicit human-attestation route above. Drafts still need nonblank context,
@@ -204,8 +241,8 @@ records OPEN, ACTIVE, BLOCKED, COMPLETED or CANCELLED. Dependencies must be comp
before starting dependent steps. Completed steps require a result (`--reason`) and
owned `--evidence ART`. Plan decisions must be accepted for execution.
`plan create --decision DEC` promotes its referenced drafts before returning the
new Plan. Already accepted decisions are unchanged. Inputs are validated together
`plan create --decision DEC` promotes eligible drafts under the applicable authority
before returning the new Plan. Already accepted decisions are unchanged. Inputs are validated together
under the project lock; ordinary publication failures roll back promotions.
Crash-interrupted publication may still need deliberate repair; use `work validate`
to inspect causal Plan links and revision history. `plan update` does not promote
@@ -217,6 +254,26 @@ reconsider hypotheses and replan explicitly when evidence changes. OODA is adapt
not a mandatory four-stage pipeline. No autonomous repository executor, orchestrator,
Git push/merge, worktree manager or custom workflow engine is implied.
For a relevant uncertainty, record hypothesis, success criterion and invocation
before running an experiment: `plan experiment start WRK PLN --step TSK
--hypothesis TEXT --criterion TEXT --invocation TEXT --by NAME --reason TEXT`.
Run the actual command/simulation externally and attach its evidence. Then use
`plan experiment finish WRK PLN EXP --outcome CONFIRMED|REFUTED|INCONCLUSIVE
--observation TEXT --interpretation TEXT --next-action TEXT --evidence ART
--by NAME --reason TEXT`. These optional records live in Plan revision history;
ordinary steps need no experiment or four-phase ritual. Group routine attempts.
A failed hypothesis needs --retry-of and --reconsideration before repetition.
Choose the next action from results. DEC should specify useful success conditions
and commitments to preserve; adapt autonomously inside those limits. If evidence
questions a DEC, record --questions-decision DEC on the experiment result. Continue
authorized investigations and independent steps, but revise that DEC with applicable
approval and update the Plan to the accepted replacement before affected execution.
Dropping the reference does not resolve a concern. Open experiments and unresolved
concerns block affected steps/dependents and Plan completion. Without --step the
experiment affects the whole Plan. Criteria precede results; results need owned,
integrity-checked evidence. The CLI checks these records, not their semantic truth.
`plan status` records the plan's state; `plan history` exposes previous snapshots.
Record test/build/source revisions and commands in evidence rather than claiming
success from a status label. Respect read-only repository policy and the OS sandbox.