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
Add deterministic preview and fingerprint-bound application for independent DF sources under an AIE umbrella. Preserve complete agendas and original evidence with source-scoped identities, validated receipts and safe retries. Publish prepared Works atomically, require review for changed imports and retain existing refinement without source edits or model calls. Advertise protocol contract 2 while continuing to read contract-1 projects. Add JVM, concurrency, recovery and native coverage; document usage and complete WRK-0007 with verification evidence.
568 lines
33 KiB
Markdown
568 lines
33 KiB
Markdown
# Portable engineering protocol — schema 1
|
||
|
||
## Project root and configuration
|
||
|
||
The engineering root is the parent of `.ai-engineering`. Repository paths resolve
|
||
against that root, independently of the CLI's current directory. Discovery searches
|
||
upward or accepts an explicit `--project` root (or `.ai-engineering` directory).
|
||
|
||
An engineering project may be a simple source folder without Git, one Git repository,
|
||
or a workspace containing several repositories. All three use the same Work protocol.
|
||
Initialize directly in the folder that represents the desired project scope. An empty
|
||
`repositories: []` is valid; Works need no repository references to persist discussions,
|
||
decisions, artifacts and context. Git is invoked only when inspecting registered
|
||
repositories. Without repository references, a Work has no Git revision snapshots.
|
||
|
||
For a single Git repository at the engineering root, register it with `path: "."`
|
||
and `type: linked-git`. Registration remains explicit; initialization does not create
|
||
or register a Git repository. For multiple repositories, register their relative
|
||
subdirectory paths as in the example below.
|
||
|
||
```yaml
|
||
schemaVersion: 1
|
||
project:
|
||
id: prometeu
|
||
name: Prometeu
|
||
repositories:
|
||
- id: runtime
|
||
path: runtime
|
||
type: linked-git
|
||
language: rust
|
||
access:
|
||
read: true
|
||
edit: false
|
||
validationCommands: []
|
||
```
|
||
|
||
IDs use lowercase ASCII letters, digits and hyphens, beginning with a letter.
|
||
Repository types are `linked-git` and `git-submodule`. Omitted `access` defaults to
|
||
`read: true, edit: false`. If `access` is supplied its booleans are explicit; edit
|
||
requires read. Language is optional. `validationCommands` is optional metadata,
|
||
never executable through this release. Unknown fields and schema versions fail validation.
|
||
|
||
Absolute repository paths, `..` components, backslashes and symlinks beneath the root
|
||
are rejected, including links that point inside the root. This stricter initial rule
|
||
avoids ambiguous link policies. A linked Git repository may be the engineering root;
|
||
repositories cannot live inside `.ai-engineering`. Git inspection verifies the registered
|
||
path is a repository top-level;
|
||
submodule registration additionally verifies its superproject. Paths must exist.
|
||
No submodules are automatically created, moved or updated.
|
||
|
||
Policy controls protocol intent, not OS security. Concurrent malicious filesystem
|
||
replacement is outside this CLI's sandbox guarantee; use OS isolation for untrusted
|
||
processes. The adapter clears inherited `GIT_*` variables and disables optional Git locks.
|
||
|
||
## Work and files
|
||
|
||
```text
|
||
.ai-engineering/
|
||
ai-engineering.yaml
|
||
README.md # portable agent entry point
|
||
AGENTS.md # provider-neutral instructions
|
||
protocol.json # discovery manifest and capabilities
|
||
.gitignore
|
||
.local/write.lock # ignored, no semantic state
|
||
contracts/ # reserved for project contracts
|
||
works/
|
||
.sequence.yaml # canonical high-water mark; commit this
|
||
WRK-0001-improve-scene-editor/
|
||
work.md
|
||
epic/WRK-0001.md # present when epic: true
|
||
epic/.history/WRK-0001/r0001.md
|
||
discussions/DSC-0001.md
|
||
topics/TOP-0001.md
|
||
topics/.history/TOP-0001/r0001.md
|
||
surveys/SVY-0001.md
|
||
surveys/.history/SVY-0001/r0001.md
|
||
dispositions/DSP-0001.md
|
||
agent-runs/RUN-0001.md # canonical provenance; version this
|
||
decisions/DEC-0001.md
|
||
decisions/.history/DEC-0001/r0001.md
|
||
plans/PLN-0001.md
|
||
plans/.history/PLN-0001/r0001.md
|
||
artifacts/
|
||
references/
|
||
experiments/
|
||
evidence/ART-0001/
|
||
artifact.yaml
|
||
payload
|
||
outputs/
|
||
runs/ # ignored temporary execution outputs
|
||
```
|
||
|
||
`work.md`, discussion and decision files contain YAML front matter, delimited by
|
||
`---`. Work fields remain in front matter; trailing Work notes are noncanonical.
|
||
New discussion/decision narrative and plan descriptions use version 2 Markdown
|
||
bodies, with typed metadata in front matter. Legacy YAML-only discussions and draft
|
||
DECs remain readable without rewriting. There is no Java object serialization and no
|
||
dependency on conversation state.
|
||
|
||
Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`,
|
||
`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`,
|
||
`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`, `plans[]`,
|
||
`completions[]`, `events[]`, `archived`, `topics[]`, `surveys[]`, `dispositions[]`,
|
||
`agentRuns[]`, `epic`. Operational, refinement and EPIC fields default to empty/false
|
||
when absent in older schema 1 Works. Updated CLI versions write them explicitly;
|
||
older CLI binaries that reject unknown fields cannot read these extended records.
|
||
Each repository snapshot
|
||
records `repositoryId`, relative `path`, exact `head` commit and `dirty`. An empty
|
||
repository records `UNBORN`, not an invented commit. Snapshots are taken at Work
|
||
creation and remain stable; they are not claims about later experiments.
|
||
|
||
Work IDs are project-wide, monotonic `WRK-` identifiers with an uppercase hexadecimal
|
||
suffix of four to nine digits: `WRK-0001` through `WRK-FFFFFFFFF`. The sequence passes
|
||
from `WRK-0009` to `WRK-000A`, then `WRK-000F` to `WRK-0010`. Zero is not a Work ID;
|
||
lowercase, `0x` prefixes and non-hexadecimal characters are rejected. Listing uses
|
||
numeric hexadecimal order, including when the width grows beyond four digits.
|
||
|
||
A persisted sequence reserves identity before publishing a Work; crashes may leave
|
||
gaps. New `.sequence.yaml` files use their own schema version 2:
|
||
|
||
```yaml
|
||
schemaVersion: 2
|
||
lastWork: "000A"
|
||
```
|
||
|
||
`lastWork` is the highest reserved hexadecimal suffix, written as a quoted uppercase
|
||
string. `"0000"` represents no reservation. Work records and project configuration
|
||
continue to use protocol schema version 1; the sequence file has an independent format.
|
||
|
||
Legacy schema version 1 counters with a decimal numeric `lastWork` remain readable.
|
||
Existing Work IDs, directory names and references are not renamed. Their suffixes
|
||
are interpreted as hexadecimal from this version onward. To protect prior reservations,
|
||
the legacy high-water mark is converted by identifier spelling: decimal counter 16
|
||
reserved `WRK-0016`, so it becomes hexadecimal `"0016"` (0x16), even if that Work was
|
||
removed. The next identifier is `WRK-0017`. This deliberately leaves any gaps below
|
||
that reservation unused. Read/validation commands do not rewrite legacy counters;
|
||
the next creation atomically writes version 2 under the project lock. Use the updated
|
||
CLI for hexadecimal IDs and version 2 sequence files.
|
||
|
||
Do not remove or rewind the sequence. Discussion/decision/artifact/plan IDs remain decimal and are **Work-local**;
|
||
their full identity is `(project, Work ID, child ID)`. Work reference arrays determine
|
||
history order. Directory names are a convenience; ID stability does not depend on title.
|
||
Duplicate Work IDs and directory/record mismatches fail validation.
|
||
|
||
Statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` changes an open
|
||
Work's state but cannot set COMPLETED. `work complete` records the evidence mapping
|
||
and explicit approval described below. Terminal or archived Works reject mutation
|
||
until `work reopen --by NAME --reason TEXT` returns them to ACTIVE. Reopening preserves
|
||
all prior completion records and lifecycle events. Nothing is irreversibly closed.
|
||
Legacy COMPLETED Works without completion evidence remain readable, but validation
|
||
diagnoses the missing record; reopen and record reviewed evidence before archiving.
|
||
|
||
`work update <ID>` explicitly refines `title`, `description`, `goal`, `motivation`,
|
||
`constraints[]` and `acceptanceCriteria[]`. Omitted fields retain their current values.
|
||
Repeated `--constraint` and `--acceptance` values replace the entire respective list;
|
||
`--clear-constraints` and `--clear-acceptance` explicitly empty them. Supplying values
|
||
and the corresponding clear option is invalid. A command with no fields is invalid.
|
||
Title, goal and individual list entries must be nonblank; description and motivation
|
||
can be cleared with an empty string.
|
||
|
||
Updates hold the project lock and atomically replace only Work metadata. ID, folder,
|
||
status, creator, creation time, repository revision snapshots and all child references
|
||
are preserved. `updatedAt` changes only when field values actually change; repeated
|
||
identical updates retain the original bytes and timestamp. Trailing noncanonical Work
|
||
notes are retained during metadata, status and child-reference updates. Updating a
|
||
Work neither approves a DEC nor changes its lifecycle status. Existing discussion and
|
||
decision records remain the history of how the scope was refined.
|
||
|
||
## Discovery and agent entry
|
||
|
||
The directory `.ai-engineering` identifies the protocol workspace. `init` installs
|
||
its README, instructions and `protocol.json`. The manifest declares schema, relative
|
||
entrypoint/configuration/Works paths, executable, startup commands, capabilities and
|
||
explicit human-attestation semantics. `onboard` installs or refreshes those files in
|
||
existing projects, without rewriting Work data. It also maintains a root `AGENTS.md`
|
||
block between `<!-- ai-engineering:start -->` and `<!-- ai-engineering:end -->`.
|
||
Rules outside that block remain byte-identical; replaced files have `.local` backups.
|
||
Ambiguous, duplicated or unclosed markers cause refusal. Repeated onboarding is a no-op.
|
||
Legacy projects with none of the three entry files remain valid. Partial installation,
|
||
malformed/duplicate JSON fields, unknown manifest versions and unsupported paths are
|
||
validation failures. `onboard` refreshes the contract while backing up changed files.
|
||
|
||
An agent begins with the guide, status, next-actions and selected Work context. These
|
||
are portable instructions, not an LLM plugin or enforcement mechanism. Without the
|
||
CLI, an agent can inspect the files directly. Agents must still inspect the entry
|
||
files and respect project/user rules. Quoted protocol data and evidence do not gain
|
||
instruction authority. `guide` also works outside a project. `status` hides archived
|
||
Works by default (`--all` includes them); `next-actions [WRK]` returns deterministic
|
||
suggestions and never executes a repository action.
|
||
|
||
## Discussion and decisions
|
||
|
||
Each discussion entry has `schemaVersion`, `id`, `workId`, `discussionId` (thread name),
|
||
`kind`, `author`, `createdAt`, optional `respondsTo`, and `text`. Multiple threads can
|
||
coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS,
|
||
INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten.
|
||
Text is supplied by a human, external agent or explicitly labeled fixture adapter.
|
||
|
||
`discussion add` requires exactly one text source: `--text` for an inline string or
|
||
`--text-file` for a regular UTF-8 file up to 1 MiB. A file path resolves relative to
|
||
the caller's working directory, independently of `--project`. The entire file is
|
||
read as prose, without trimming, newline normalization or front-matter interpretation.
|
||
Nonblank content is required. Missing files produce exit 3; nonregular, malformed UTF-8,
|
||
blank or oversized input produces exit 2, with no appended discussion. The source is
|
||
not changed or retained as an external dependency: later edits/removal cannot alter
|
||
the persisted entry. File input does not implicitly register an evidence artifact.
|
||
|
||
New discussion files have `documentVersion: 2` in front matter and omit the `text`
|
||
field there. The complete Markdown body supplies `text`, including its original
|
||
headings, lists, tables, code blocks and whitespace:
|
||
|
||
```markdown
|
||
---
|
||
schemaVersion: 1
|
||
id: DSC-0002
|
||
workId: WRK-0001
|
||
discussionId: main
|
||
kind: SUGGESTION
|
||
author: agent
|
||
createdAt: '2026-11-11T16:47:32Z'
|
||
respondsTo: DSC-0001
|
||
documentVersion: 2
|
||
---
|
||
|
||
## Proposed approach
|
||
|
||
Use the next small, testable slice.
|
||
|
||
- State the limits.
|
||
- Identify supporting evidence.
|
||
```
|
||
|
||
One blank line separates the closing delimiter from the body; that formatting line
|
||
is excluded from `text`. All subsequent whitespace belongs to the prose. LF and CRLF
|
||
front matter are accepted; the reader does not normalize the body's line endings.
|
||
`schemaVersion: 1` still describes the protocol record. `documentVersion: 2` describes
|
||
this file representation, not a change to JSON context fields. Unknown document
|
||
versions and simultaneous YAML `text` plus a version 2 body fail validation.
|
||
|
||
Legacy discussions omit `documentVersion` (or declare 1) and keep canonical `text`
|
||
in YAML; their trailing body remains noncanonical notes. The new reader accepts both
|
||
representations without automatic writes. The old CLI cannot read document version 2.
|
||
|
||
`discussion migrate <Work>` explicitly converts legacy entries. Every discussion is
|
||
preflighted before any file is replaced. Nonblank legacy trailing notes cause refusal;
|
||
incorporate those notes into canonical text first. Original UTF-8 files are backed up
|
||
under `.local/backups/discussions/<Work>/<operation-id>/` before atomic replacement.
|
||
Migration preserves all semantic fields, Work timestamps and context JSON/Markdown,
|
||
and skips already converted entries. It changes formatting, not discussion history.
|
||
Interrupted migrations can be resumed; completed files are skipped and existing backups
|
||
are retained. This is per-file publication, not an all-or-nothing multi-file transaction.
|
||
|
||
A response must refer to an earlier entry in the same Work. Outstanding questions
|
||
include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing
|
||
to them. This mechanical definition does not infer agreement or approval from prose.
|
||
|
||
DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`,
|
||
`alternatives[]`, `rationale`, `risks[]`, `acceptanceCriteria[]`, `approvalStatus`,
|
||
`author`, `createdAt`, `evidence[]`, narrative `text`, `revision`, `previousHash`,
|
||
`updatedAt`, `updatedBy`, `changeReason`, `approvals[]`, optional `revises` and
|
||
`supersededBy`. Legacy draft fields default to revision 1, no approvals/links and
|
||
empty narrative. Narrative uses document version 2; the JSON `text` field remains explicit.
|
||
|
||
Statuses: DRAFT, ACCEPTED, REJECTED, SUPERSEDED. `decision update` changes only drafts,
|
||
recording actor/reason and a snapshot. Lists replace entire lists; explicit `--clear-*`
|
||
options clear them. `--text`/`--text-file` supplies narrative. Direct acceptance requires
|
||
nonblank context/approach/rationale, actor/reason and `--human-approved`. This flag is
|
||
an attestation that approval occurred, not authenticated identity or OS permission.
|
||
An agent cannot infer approval from a proposal or a prior status. Rejection retains
|
||
the proposal. `decision revise` creates a new draft linked to an accepted/rejected
|
||
DEC. Accepting that draft supersedes the prior accepted DEC, preserving both records.
|
||
Operational choices during execution remain distinct from these formal commitments.
|
||
|
||
Creating a Plan from a draft DEC is a separate deterministic acceptance route.
|
||
The framework records `origin: SYSTEM_PLAN`, the causal `planId`, actor
|
||
`system:planning` and `humanApproved: false`; it does not invent a direct human
|
||
attestation. Context, approach and rationale must still be nonblank. Referenced
|
||
drafts are promoted and their accepted predecessors are superseded with the same
|
||
Plan provenance. Already accepted DECs stay byte-identical; rejected/superseded
|
||
DECs and conflicting replacements cannot be used to create the Plan. Optional
|
||
approval `origin`/`planId` fields are absent on historical direct approvals, whose
|
||
meaning and serialization remain unchanged. Readers predating this capability
|
||
cannot read new system-promotion records; use the updated CLI, without rewriting
|
||
historical approvals.
|
||
|
||
## Topics, surveys and adapter runs
|
||
|
||
[Discussion refinement contracts](discussion-slice.md) specify TOP/SVY/DSP/RUN records,
|
||
questions, answers, sources and commands. These IDs are decimal and Work-local;
|
||
QST/ANS IDs are survey-local. Topic and survey revisions use the same SHA-256 history
|
||
convention as decisions/plans. Existing discussionId threads are implicit topic views,
|
||
including `main` for an empty Work, without canonical file changes.
|
||
|
||
Questions have a topic, suggestions, optional recommendation, single/multiple selection
|
||
and discussion sources. Free-text answers are always available. A revised answer
|
||
supersedes the prior one without deletion; only the latest determines pending status.
|
||
Revision signals a review and does not change accepted decisions/plans. Guided console
|
||
answering and noninteractive commands use the same persisted contract.
|
||
|
||
Project configuration can optionally include:
|
||
|
||
```yaml
|
||
agents:
|
||
general:
|
||
adapter: fixture-general
|
||
profile: fixture
|
||
model: deterministic
|
||
activities:
|
||
analyze:
|
||
adapter: fixture-reviewer
|
||
profile: fixture
|
||
model: deterministic
|
||
archivePolicy: review-only
|
||
```
|
||
|
||
Without agents configuration ordinary commands still work. Agent execution requires
|
||
an explicitly configured general. Unknown activities fall back to general; configured
|
||
specializations win. Fixture adapters and local codex-cli/claude-cli are available. An explicit
|
||
`reversible` policy permits archive with owned ART evidence and a reason; restore
|
||
preserves the source and disposition history. Questions/responses cannot be hidden
|
||
through proposal archive. Policies are metadata, not OS enforcement.
|
||
|
||
RUN records preserve request ID, raw task, requested/chosen activity, requester,
|
||
executor, sourceHash, fixture proposal bundle, applied references, status, error and
|
||
timestamps. Proposals have typed source links; `@request` in a proposal resolves to a
|
||
persisted raw Discussion NOTE. Framework checks validate output before application.
|
||
Adapters cannot generate survey answers or human approvals. Fixture analyses are
|
||
synthetic observations, never claims about a real experiment or investigation.
|
||
|
||
Source fingerprints include semantic project/Work/discussion/survey/evidence/decision/
|
||
plan state, excluding run bookkeeping and Work modification time. Context derives
|
||
staleness without invoking an adapter. A proposal-changing run can already be stale
|
||
against its own resulting state; sourceHash identifies the input it actually saw.
|
||
Identical completed request IDs replay the recorded result even if context later
|
||
changes; use a new ID for a new computation. Changed request input with the same ID
|
||
is invalid. Interrupted APPLYING records block further runs pending inspection;
|
||
FAILED records retain applied references. This is diagnostic publication, not rollback.
|
||
|
||
## Local provider executors
|
||
|
||
Executor adds optional timeoutSeconds, bounded 1–600; omission means 120 seconds.
|
||
Old records remain readable without writing. Null timeout/provenance fields are
|
||
omitted from serialized values so legacy fixture digests remain stable. Local CLI
|
||
profile/model names are constrained tokens, not arbitrary flags; default model omits
|
||
the provider flag. Profile is an AIE role instruction. Provider configuration profiles,
|
||
private session state and credentials do not become portable AIE configuration.
|
||
|
||
The [CLI adapter contract](cli-adapters.md) defines bounded process invocation,
|
||
required controls, versioned schemas, failure semantics and setup. Wire output cannot
|
||
set adapter/fixture identity or human authority. The normal complete proposal bundle
|
||
must validate before publication. RUN adds optional provenance with classification
|
||
and/or proposal invocation: transport, observed CLI version, configured role/model,
|
||
durationMillis, timeoutSeconds, outputSha256 and outputBytes. No raw environment or
|
||
stderr is canonical. A pre-publication transport failure leaves the Work unchanged.
|
||
|
||
General can classify a request into configured/common activities. Explicit activity
|
||
skips classification. Clarify requires a survey with suggestions and leaves human
|
||
answers pending. Prior RUN outputs are supplied as derived interpretations; source
|
||
fingerprints still follow canonical semantic sources. State/conformance/EPIC checks
|
||
never invoke a provider. Setup/doctor similarly never sends a model request.
|
||
|
||
## Plans and execution records
|
||
|
||
Plans are optional, proportional Work-local records (`PLN-0001`). A plan contains
|
||
title, Markdown description, referenced decisions, steps, lifecycle status, creator,
|
||
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
|
||
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
|
||
with `work validate`. Validation checks the causal Plan's first revision, so later
|
||
Plan reference edits retain the original promotion provenance and cannot invent it.
|
||
Creating another Plan from an already accepted DEC does not add an approval.
|
||
`plan update` does not promote drafts; review its references before changing them.
|
||
|
||
Step dependencies must exist in that plan and be acyclic. Starting or completing a
|
||
step requires completed dependencies and accepted referenced decisions. Completion
|
||
requires result text (`--reason`) and owned evidence. `plan status COMPLETED` requires
|
||
at least one completed step and all required steps completed; cancelled steps need
|
||
explicit scope review with `plan exclude --step`. Exclusions retain the cancelled
|
||
record and bind its content hash, actor and reason. Legacy Plans remain readable
|
||
without rewriting. Reopen a terminal plan with
|
||
`plan status ACTIVE` before editing; reopen terminal steps before changing scope.
|
||
Reopening a prerequisite first requires reopening/cancelling its dependent steps.
|
||
If a DEC is superseded, reconsider the plan and update its references before execution.
|
||
|
||
Plan/step changes retain previous plan snapshots. `decision history` and `plan history`
|
||
walk `.history/<ID>/rNNNN.md`; `previousHash` links each revision to the complete prior
|
||
UTF-8 file. Validation checks identity, numbering and hashes. Hashes are integrity
|
||
links, not signatures: manual rewriting of an entire chain is not prevented. New
|
||
records start at revision 1. A snapshot published before an interrupted current-file
|
||
replacement can be reused only when identical; conflicting history is never overwritten.
|
||
|
||
The CLI does not execute steps, tests or validation-command metadata. Humans/agents
|
||
run real commands externally and record observations, commands, source revisions and
|
||
results in evidence. Plans support explicit adaptation; no autonomous OODA engine or
|
||
fixed four-phase pipeline is implemented.
|
||
|
||
## Completion, integration and archive
|
||
|
||
Works with executable Plans derive completion from those Plans. Mutation commands
|
||
and `work reconcile WRK` consolidate the last completed step into its Plan and
|
||
recheck all associated Plans. Completed required Plans and no pending questions,
|
||
surveys, draft DECs or explicit blocking states produce SYSTEM_PLANS completion,
|
||
without a model call, repeated human delivery approval or manual Work-level criterion
|
||
mapping. Empty sets never auto-complete; reviewed cancellations retain history.
|
||
New Plans after delivery require reopening. Unchanged old Plans do not immediately
|
||
close an explicitly reopened Work/Plan. See [Plan consolidation](plan-consolidation.md)
|
||
for records, provenance and recovery. `work check` reports consolidation pending
|
||
reasons; status/context/next-actions remain read-only. Existing EPIC authority and
|
||
policy continue to govern EPIC completion.
|
||
|
||
For inspection-only Works without Plans, `work check` checks mechanical readiness: explicit acceptance criteria,
|
||
no unresolved questions/issues or draft DECs, and terminal plans. Noncancelled plans
|
||
must reference currently accepted decisions. Small Works can close without a DEC/plan.
|
||
The check cannot determine whether arbitrary prose/evidence proves the desired outcome.
|
||
|
||
`work complete` requires human attestation, actor, summary and one unique
|
||
`--criterion N=ART-0001[,ART-0002]` mapping per criterion (1-based). Artifacts must
|
||
belong to the Work and pass integrity checks. Completion captures criterion text,
|
||
evidence IDs, approval metadata and a deterministic SHA-256 digest of scope, source
|
||
snapshots, discussion, decisions, plans and artifact metadata. Current COMPLETED Work
|
||
data must still match that digest. Reopened Works retain earlier snapshots as history.
|
||
|
||
Supply updated canonical project files via `--integration PATH` or explicitly state
|
||
`--no-integration-needed REASON`. Integration paths are safe project-relative regular
|
||
files outside `.ai-engineering`; their hashes identify contents at closure. Those
|
||
files can evolve later without invalidating a historical completion. The CLI records
|
||
the attestation/snapshot; it does not prove that the file changed or infer its meaning.
|
||
Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is required.
|
||
|
||
`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work
|
||
archived. It retains all files and prior approvals/results. `work reopen` clears
|
||
archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion.
|
||
`import discussion` imports DF DSCs with open AGDs using a read-only preview and
|
||
an explicit `--apply --expect` fingerprint. Independent `--source ID=PATH` origins
|
||
share one AIE destination; targets are described in their Works. Only open agendas
|
||
are imported as complete refinement notes and original evidence. Owned versioned
|
||
receipts preserve source+DSC identity, source hashes and references without changing
|
||
the Work schema. Identical reimports are no-ops; changes are reported for review.
|
||
Work publication is atomic per prepared directory, while a batch may be resumed
|
||
after partial publication. Closed agendas, DECs, Plans and Lessons are not imported.
|
||
See [the import contract](discussion-import.md) for limits, diagnostics and recovery.
|
||
|
||
## EPIC policy and system completion
|
||
|
||
[The EPIC contract](epics.md) defines topology, authority and recovery. An EPIC remains
|
||
a project Work, marked `epic: true`, with one versioned definition in its `epic/`
|
||
directory. Links use Work IDs, with important=true by default. Definitions preserve
|
||
mode, links, explicit authorization, editor/reason, revision and previousHash.
|
||
History follows the DEC/Plan snapshot convention. Initial topology is a forest.
|
||
|
||
RESULTS tracks verified important deliveries; optional children are reported without
|
||
blocking. Important CANCELLED remains pending. DECOMPOSITION uses ordinary reviewed
|
||
closure for the parent's own output and does not wait for execution. Empty important
|
||
sets never auto-close. Policy edits require an open parent and invalidate automatic
|
||
authority; `epic authorize --human-approved` binds the parent/important-child scopes
|
||
and current policy. Authorization is delegation for the structured aggregate condition,
|
||
not an inferred human approval of a future delivery.
|
||
|
||
Completion records add optional `origin` and `delegation`. Old records default to
|
||
HUMAN with no delegation and retain their digest semantics. HUMAN requires direct
|
||
humanApproved=true. SYSTEM_EPIC requires humanApproved=false, actor system:epic,
|
||
an actual policy authorization/history hash and request correlation. Its criteria map
|
||
to a framework-owned aggregate ART receipt containing policy/input and important-child
|
||
completion digests. The human's policy delegation attests that this condition suffices
|
||
for the parent criteria; the framework performs no semantic inference about prose.
|
||
|
||
Frozen RESULTS scope includes important completion records; optional execution can
|
||
continue independently. Important reopening reopens ancestors and clears their archive,
|
||
retaining prior completions. Explicit reopening of an EPIC suspends its authority for
|
||
replanning. Child-caused reopening preserves unchanged-scope authority. BLOCKED and
|
||
CANCELLED parents require explicit resumption. Nested propagation runs from descendants
|
||
to ancestors under the project lock, without calling any AgentAdapter.
|
||
|
||
Public CLI/Verification lifecycle APIs return the changed Work plus affected EPIC
|
||
reports when linked; plain Work output remains compatible. `--requester` and
|
||
`--request-id` correlate results. IDs correlate notifications rather than acting as a
|
||
global transaction log. `epic reconcile [WRK]` derives missed updates from canonical
|
||
files and does not duplicate a satisfied completion. A matching published receipt is
|
||
reused after interrupted completion. Invalid histories, missing children and orphan
|
||
publication are diagnosed; arbitrary corruption still needs deliberate repair.
|
||
Low-level storage callers must explicitly reconcile after lifecycle writes.
|
||
|
||
## Evidence and integrity
|
||
|
||
`artifact add` copies one regular file up to 1 MiB. Its manifest records schema, ID,
|
||
Work ID, origin, purpose, Work-relative payload path, SHA-256, byte size, author and UTC
|
||
creation time. The origin defaults to the source basename; use `--origin` for a useful
|
||
portable provenance reference. Payload bytes are exact. The fixed `payload` filename
|
||
avoids filename ambiguity; origin preserves the supplied source identity.
|
||
|
||
Validation checks required directories, IDs, schemas, repository references, child
|
||
ownership, missing records, orphan records and payload integrity. Evidence paths stay
|
||
inside the Work. Large resources should remain in their canonical location and be
|
||
described in discussion/reference files, rather than copied into this workspace.
|
||
`artifacts/outputs` is versionable for deliberately retained outputs; use ignored `runs/`
|
||
for large temporary results. No command creates large output files by default.
|
||
|
||
## Compatibility and evolution
|
||
|
||
`project compatibility` inspects actual stored formats and revisions without writes.
|
||
`protocol.json.schemaVersion` versions the manifest, while optional `protocolVersion`
|
||
versions the engineering contract (absent means the supported legacy baseline 1).
|
||
The diagnostic exposes the supported read/write format catalog separately from the
|
||
executable release. Old compatible records remain valid and readable without
|
||
normalization, including COMPLETED Works. `onboard` updates only entry instructions
|
||
and the manifest; a newer unsupported contract is never silently overwritten.
|
||
See [compatibility and evolution](compatibility.md) for public states, update guidance
|
||
and requirements for future explicit conversions. No required migration exists today.
|
||
|
||
## Context and continuity
|
||
|
||
`work context --format markdown|json` loads only canonical project/Work files. It
|
||
includes all Work fields (metadata separately in Markdown), stored source revisions,
|
||
ordered discussion history/conclusions, explicit decisions and approvals, plans/results, unresolved questions
|
||
and complete artifact references with integrity metadata. JSON has top-level
|
||
`schemaVersion`, `work`, `discussionHistory`, `decisions`, `outstandingQuestions`,
|
||
`artifacts`, `plans`, `protocolGuide`, `topics`, `surveys`, `dispositions`, `agentRuns`,
|
||
`agents`, `epic`, `parentEpic`. Completion and lifecycle history are included
|
||
in `work`. It does not embed arbitrary evidence payloads or all revision snapshots;
|
||
use history commands when prior versions are relevant.
|
||
|
||
No export timestamp, current absolute path or live Git state is injected. Unchanged
|
||
files yield byte-identical output across new instances and processes. Export rejects
|
||
broken references or integrity failures. It requires neither a model nor live Git
|
||
inspection; `project validate` separately verifies live repositories.
|
||
|
||
Markdown context renders discussion and decision prose directly, with IDs, authors,
|
||
timestamps and reply/approval metadata. Empty sections use `None recorded.`. JSON
|
||
keeps the complete typed records, including discussion `text`, regardless of their
|
||
on-disk document version. Evidence remains referenced rather than embedded.
|
||
|
||
## Write guarantees and recovery
|
||
|
||
Protocol mutations hold `.local/write.lock`, an OS lock released automatically at
|
||
process exit. Individual files publish atomically; create operations reject overwrites.
|
||
New project/Work/artifact directories are staged and renamed. Work sequence reservation
|
||
precedes directory publication to avoid identity reuse after interruption.
|
||
|
||
A child file/bundle is published before its reference is atomically added to `work.md`.
|
||
The filesystem is not a multi-file transactional database: interruption in that window
|
||
can leave an orphan, which validation reports. Inspect its metadata and either add its
|
||
ID to the Work reference array or remove it after review. Hidden `.tmp` directories are
|
||
incomplete staging outputs, ignored by readers; inspect and clean them manually after
|
||
an interrupted write. Concurrent manual editors do not honor the CLI lock. Directory
|
||
entry durability under sudden power loss depends on the host filesystem.
|
||
|
||
## Future contracts (design only)
|
||
|
||
- Additional AgentAdapter transports and execution permissions: local proposal-only
|
||
Codex/Claude CLIs are implemented; direct provider APIs, repository execution and
|
||
vendor-native configuration profiles need separate contracts and authorization.
|
||
- OODA iteration: identify Work and prior observations, orientation, operational
|
||
choices and attempts. Phases can repeat or be skipped; no four-stage workflow gate.
|
||
- Attempt: stable identity, hypothesis, input references, exact repository revisions,
|
||
granted permissions, invocation/environment, observations, outputs, result and
|
||
evidence references. Evidence and interpretation remain distinguishable.
|
||
- Coordinated execution: independent per-repository worktrees and commit records,
|
||
integrated validation, explicit authority for destructive actions, pushes and merges.
|
||
No claim of atomic commits across repositories.
|
||
- Conformance: evaluate explicit criteria against evidence and canonical code/spec/test
|
||
updates. No required Lesson artifact. Later schema changes require explicit migration.
|