Promote referenced drafts deterministically with system provenance, causal Plan links, supersession history and recovery from publication failures. Preserve direct human approval and historical records. Add JVM and native regression coverage and update the portable protocol. Record the WRK-0007 importer decision and six-step plan, and complete WRK-0008 with verification evidence.
560 lines
33 KiB
Markdown
560 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.
|
||
Importing legacy agendas and Lessons is deferred to a later, separately tested importer.
|
||
|
||
## 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.
|