Files
ai-engineering/docs/protocol.md
T
Nilton Constantino f0e0dd061a feat: bootstrap portable engineering protocol CLI
Implement milestones 0 and 1 with project and repository configuration, Work persistence, discussions, draft decisions, evidence integrity, and deterministic context exports.

Add Java 25, Spring Boot and Modulith, native distributions, CI workflows, protocol documentation, and the pinned SDKMAN GraalVM CE toolchain.

Validated with 20 passing tests and the macOS ARM64 native multi-repository continuity smoke.
2026-11-11 16:14:22 +00:00

8.8 KiB

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

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. Repositories cannot be the engineering root or live inside .ai-engineering. Git inspection verifies an independent 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

.ai-engineering/
  ai-engineering.yaml
  .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
      discussions/DSC-0001.md
      decisions/DEC-0001.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 ---. All semantic content lives in the front matter in this version; trailing Markdown is reserved for noncanonical notes and is not exported. YAML multiline strings remain human-readable. Edit the typed fields to update canonical content. 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[]. 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- numbers with at least four digits. A persisted sequence reserves identity before publishing a Work; crashes may leave gaps. Do not remove or rewind the sequence. Discussion/decision/artifact IDs 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.

Initial statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. work status permits reorientation without irreversible lifecycle gates. Completion currently records intent; it does not prove acceptance criteria. Conformance automation belongs to Milestone 5.

Discussion and draft 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 or external agent; the CLI never fabricates conclusions.

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.

Draft DEC fields: schemaVersion, id, workId, title, context, approach, alternatives[], rationale, risks[], acceptanceCriteria[], approvalStatus, author, createdAt, evidence[]. Only DRAFT is accepted in this release. Empty refinement fields are legal in drafts. The CLI initially supplies context, approach, rationale and evidence; remaining fields can be refined in the canonical YAML. No approval, supersession or autonomous operational decision is implemented.

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.

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 draft decisions, unresolved questions and complete artifact references with integrity metadata. JSON has top-level schemaVersion, work, discussionHistory, decisions, outstandingQuestions, artifacts. It does not embed arbitrary evidence payloads.

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.

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)

  • AgentAdapter: accept versioned context and return proposed questions, suggestions, assumptions or draft content with provenance. The caller decides what to persist; no provider or orchestration dependency is part of schema 1.
  • 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.