feat: adopt local SQLite engineering memory and quality gates
This commit is contained in:
+90
-263
@@ -1,287 +1,114 @@
|
||||
# Architecture
|
||||
|
||||
## Technology selection
|
||||
AIE is a local engineering memory with two cycles: investigation/refinement and
|
||||
implementation, connected by DEC and Plan. OODA is adaptive; gates constrain delivery.
|
||||
The CLI records external observations and applies deterministic checks. It does not
|
||||
execute repository commands, operate a server or provide distributed collaboration.
|
||||
|
||||
The project deliberately stays on a compatible maintenance pair: **Spring Boot
|
||||
4.0.9 and Spring Modulith 2.0.9**. The published Modulith 2.0.9 POM declares
|
||||
Boot autoconfigure 4.0.9. Java compilation and bytecode target are both **25**,
|
||||
without preview features. Gradle **9.3.1** supports running on Java 25; its Wrapper
|
||||
distribution is pinned with SHA-256 verification.
|
||||
## Runtime and modules
|
||||
|
||||
The local development JDK is pinned through `.sdkmanrc` to SDKMAN candidate
|
||||
`25.5.5.0+3-graalce` (GraalVM CE 25.5.5.0.3, OpenJDK 25.0.5.0.3). This
|
||||
[GraalVM innovation release](https://www.graalvm.org/release-notes/25.5/) still uses
|
||||
Java 25. It provides both JVM and Native Image tooling without changing compilation
|
||||
target or application dependencies. Use `sdk env` for project-scoped activation;
|
||||
the Gradle Wrapper remains responsible for the Gradle version.
|
||||
|
||||
Primary compatibility references checked during implementation:
|
||||
|
||||
- [Spring Boot 4.0 requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html): Java 25, Gradle 9 and GraalVM 25 are supported; Native Build Tools 0.11.5 is the documented version.
|
||||
- [Published Modulith 2.0.9 dependencies](https://repo.maven.apache.org/maven2/org/springframework/modulith/spring-modulith-core/2.0.9/spring-modulith-core-2.0.9.pom): Boot 4.0.9 dependency.
|
||||
- [Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html): Java 25 support starts at Gradle 9.1.
|
||||
- [Spring AOT Gradle integration](https://docs.spring.io/spring-boot/4.0/gradle-plugin/aot.html).
|
||||
- [Picocli native configuration](https://picocli.info/#_graalvm_native_images): annotation-processor-generated reflection metadata.
|
||||
- [GraalVM 25 release notes](https://www.graalvm.org/release-notes/JDK_25/): macOS x86_64 support was removed.
|
||||
|
||||
Picocli **4.7.7** handles argument validation, help and dispatch. Jackson 3 YAML/JSON
|
||||
comes from Boot's BOM. JUnit is explicitly pinned to **5.13.4** because the requested
|
||||
test baseline is JUnit 5; the Boot BOM otherwise selects a newer major generation.
|
||||
AssertJ and Modulith/ArchUnit verify behavior and dependencies. There is no Spring AI,
|
||||
Embabel, web starter, persistence server or workflow framework.
|
||||
|
||||
## Module boundaries
|
||||
|
||||
All packages below are under `net.intrepid.aiengineering`. A module's base package is
|
||||
its explicit public API; implementation-only Git adapters live in `project.internal`.
|
||||
`package-info.java` declares allowed dependencies. `ArchitectureTest` calls
|
||||
`ApplicationModules.verify()` to enforce cycles, visibility and dependency rules.
|
||||
Java 25, Gradle 9.3.1, Spring Boot 4.0.9, Modulith 2.0.9, Picocli 4.7.7 and Jackson 3
|
||||
remain pinned by the build. JUnit 5.13.4, AssertJ and Modulith/ArchUnit verify behavior.
|
||||
GraalVM CE 25.5.5.0+3 is pinned in .sdkmanrc. Spring supplies process lifecycle and AOT;
|
||||
services are ordinary Java classes with explicit project paths and no retained Work
|
||||
cache. Infrastructure stays outside immutable domain records.
|
||||
|
||||
| Module | Owns | May depend on |
|
||||
|---|---|---|
|
||||
| filesystem | Protocol codecs, safe paths, atomic file writes, locks, errors | none |
|
||||
| project | Configuration, discovery, repository policy, read-only Git adapter | filesystem |
|
||||
| work | Work identity/lifecycle, human guidance/history, repository snapshots, references and EPIC policy/graph | project, filesystem |
|
||||
| discussion | Entries, topics, surveys, answer history and proposal dispositions | work, project, artifact, filesystem |
|
||||
| decision | Draft, approval, revision and supersession records | work, filesystem |
|
||||
| planning | Plans, dependencies, step results, experiments and revision history | work, decision, discussion, artifact, filesystem |
|
||||
| legacyimport | DF preview, original agenda evidence, provenance and prepared Work publication | filesystem, project, work, discussion, artifact |
|
||||
| artifact | Small evidence payloads and integrity metadata | work, filesystem |
|
||||
| agent | Adapter contract, deterministic fixtures, routing and proposal application | project, work, discussion, decision, planning, artifact, filesystem |
|
||||
| verification | Structural conformance, context, reviewed closure and deterministic EPIC coordination | all protocol modules |
|
||||
| cli | Picocli commands, formats, exit codes | all APIs above |
|
||||
| filesystem | Codecs, paths, SQLite sessions/typed storage, atomic external files and locks | none |
|
||||
| project | Bootstrap, discovery, native/entry contracts and repository policy | filesystem |
|
||||
| work | Work identity/guidance/lifecycle, source snapshots and EPIC graph/policy | project, filesystem |
|
||||
| discussion | Entries, topics, surveys, answer history and dispositions | work, project, artifact, filesystem |
|
||||
| decision | Drafts, approvals, revision and supersession | work, filesystem |
|
||||
| planning | Plans, dependencies, results, experiments and scope exclusions | work, decision, discussion, artifact, filesystem |
|
||||
| artifact | Temporary payloads, lifecycle, publication recovery and typed receipts | work, filesystem |
|
||||
| agent | Proposal adapters, bounded local transport, validation and application | project, work, discussion, decision, planning, artifact, filesystem |
|
||||
| legacyimport | Explicit DF preview/import, preserved originals and provenance | filesystem, project, work, discussion, artifact |
|
||||
| verification | Integrity/readiness, gates, snapshots, coordination, migration and context | protocol modules |
|
||||
| cli | Picocli commands and presentation | public module APIs |
|
||||
|
||||
Spring owns the process lifecycle and CLI bean, and supplies AOT processing. Protocol
|
||||
services are ordinary Java classes with explicit path arguments and no retained Work
|
||||
cache. This keeps direct tests and fresh instances simple. Infrastructure dependencies
|
||||
remain inside services, outside immutable domain records. The small `GitAdapter` port
|
||||
is internal to Project and can be replaced without changing Work contracts.
|
||||
ArchitectureTest enforces these boundaries. Work does not import Decision, Artifact
|
||||
or Verification. Verification coordinates across independently owned domains.
|
||||
|
||||
Context assembly, readiness and evidence-mapped closure belong to Verification because they combine independently persisted
|
||||
modules and refuse to export structurally inconsistent state. Work does not depend
|
||||
on Discussion, Decision or Artifact, avoiding cycles. It owns stable references only.
|
||||
## Storage boundary
|
||||
|
||||
The engineering project is independent of repository count: a plain folder can use
|
||||
the protocol with no Git dependency, a single Git repository can register the root
|
||||
using `.`, and a larger workspace can register several child repositories. The same
|
||||
configuration schema and services support each case; no separate project mode or
|
||||
additional repository type is needed.
|
||||
New projects use `.ai-engineering/aie.db`, selected explicitly in the bootstrap.
|
||||
Small configuration and entry files remain outside the database. File existence alone
|
||||
never selects SQLite. Contract 4 and the database application/schema versions are
|
||||
validated before use. Legacy decoding remains explicit and never converts on read.
|
||||
|
||||
Work refinement uses an immutable update value that distinguishes omitted fields from
|
||||
explicitly emptied lists. The domain preserves identity, lifecycle and references;
|
||||
the filesystem service locks the project and replaces front matter while retaining
|
||||
trailing notes. Discussion file input belongs to the CLI adapter: Picocli enforces
|
||||
exclusive text sources and a bounded strict UTF-8 read supplies the existing domain
|
||||
entry. Neither feature changes canonical record schemas or introduces new modules.
|
||||
SQLite JDBC 3.54.1.0 provides the embedded engine. SqliteDatabase owns connection
|
||||
lifecycle, foreign keys, WAL/FULL durability, IMMEDIATE writes, snapshot reads and
|
||||
bounded busy waits. Nested services share a transaction; failed nested mutations
|
||||
cannot be accidentally committed after an exception is caught. File-publication
|
||||
callbacks run after commit or rollback, after the connection closes.
|
||||
|
||||
## Persistence and native execution
|
||||
SqliteRecords maps trusted record components to typed scalar columns and ordered
|
||||
child rows. Composite operational values have a domain codec, not serialized file
|
||||
content. List presence preserves null versus empty, necessary for historical hashes.
|
||||
Identity/current-revision/format/reference tables retain ownership and revisions;
|
||||
EPIC links have a unique child-parent index and foreign keys. Selected Work reads
|
||||
use direct keys. Global integrity checks still inspect the whole project.
|
||||
|
||||
Writers take an OS file lock per project. Nested service calls on the same thread reuse
|
||||
the outer lock; other threads/processes cannot interleave the proposal application.
|
||||
Complete UTF-8 files are written to a sibling
|
||||
temporary file, forced to disk and published atomically. New files use a hard link
|
||||
to avoid overwriting an existing destination. Existing files use atomic replacement;
|
||||
unsupported filesystems fail instead of quietly falling back to partial writes.
|
||||
New Works, projects and artifact payload bundles are staged before directory rename.
|
||||
See the protocol document for crash limits and recovery.
|
||||
A project publication lock fences storage migration/rollback from writers. SQLite
|
||||
commands wait a bounded interval and reject a backend transition observed while
|
||||
waiting. Ordinary related reads need no file lock and use one database snapshot.
|
||||
|
||||
Jackson parses explicit records, rejects unknown fields, duplicate YAML keys and
|
||||
unsupported schema versions. Native hints register those records; Picocli's annotation
|
||||
processor provides command reflection metadata. The Spring AOT tasks are wired by the
|
||||
native build plugin. No application arguments are passed through Spring's property
|
||||
parser. The entry point explicitly chooses non-web mode and closes its context.
|
||||
## Quality and temporary files
|
||||
|
||||
Discussion document version 2 separates typed YAML metadata from an opaque Markdown
|
||||
body. The filesystem codec maps that body to the domain record's existing `text`
|
||||
field; it does not infer structure from prose headings. The reader accepts legacy
|
||||
YAML-only text as well. Explicit discussion migration backs up originals, preserves
|
||||
semantic state and skips converted files. New decision narrative (`text`) and plan
|
||||
description use the same Markdown-body codec; legacy draft DECs remain readable.
|
||||
Work front matter remains canonical, with additive operational fields. Markdown
|
||||
context renders discussion/decision prose without YAML escaping.
|
||||
QualityGates stores required project definitions and cumulative Work additions.
|
||||
Observed results bind procedures, actual invocation, inputs, Work scope/guidance,
|
||||
DEC revisions, outcome and a short summary. Missing, failed or stale gates block
|
||||
manual, Plan and EPIC delivery. Delivery snapshots bind the exact passed results.
|
||||
Human approval remains a different record and responsibility.
|
||||
|
||||
## Operational replacement baseline
|
||||
Artifact bytes remain outside SQLite. Inputs stay available while the Work needs
|
||||
checks. Completion atomically records validated retirement intent; after commit,
|
||||
eligible payloads are unlinked and acknowledged. Pending retirement is repeatable
|
||||
when deletion or acknowledgement was interrupted. New checks refuse retired inputs.
|
||||
Structured Plan/EPIC receipts need no payload file. Legacy originals are preserved.
|
||||
Requested outputs stay in their delivery destinations, outside the cleanup scope.
|
||||
|
||||
The user expanded the original bootstrap scope to replace the existing discussion
|
||||
workflow before introducing intelligent adapters or a legacy importer. Planning is
|
||||
a concrete ninth module, not a custom workflow engine. A plan records editable scope,
|
||||
dependencies and externally executed results. Starting/completing steps checks their
|
||||
dependencies and accepted decisions. No repository command is executed by Planning.
|
||||
ArtifactPublication journals only owned publication intent. Rollback/recovery removes
|
||||
its own orphan payload, never an unrelated file. Unknown residue is reported for
|
||||
inspection. Local provider workspaces are bounded temporary directories; raw transport,
|
||||
credentials, environment and complete logs do not become engineering memory.
|
||||
|
||||
Work owns optional human guidance and its choice/request history. New contract-3
|
||||
Works begin without an inferred discussion mode and require human DEC approval.
|
||||
Decision and Planning enforce that authority; explicit Work-wide waiver retains
|
||||
system promotion provenance. Planning owns optional experiments inside its existing
|
||||
revision chain and depends on Discussion to check unresolved planning commitments.
|
||||
Verification and local CLI adapters expose the applicable conduct and OODA guidance.
|
||||
Legacy absent fields are omitted to preserve historical digests.
|
||||
## Authority, coordination and migration
|
||||
|
||||
Plan creation prepares eligible deterministic draft-decision promotions through Decision,
|
||||
validates every reference before publication and records SYSTEM_PLAN provenance
|
||||
with the causal Plan ID and no fabricated human attestation. Existing accepted
|
||||
decisions are unchanged. Decision exposes prepared promotion/recovery operations;
|
||||
Planning coordinates them under the existing project lock. Ordinary failures roll
|
||||
back the attempted writes; crash interruption remains subject to per-file atomicity
|
||||
and structural validation. Verification checks promotion links against Plan history.
|
||||
No adapter is invoked, and the Decision module has no dependency on Planning.
|
||||
Plans/steps can be reopened and revised when observations change.
|
||||
Guidance preserves explicit human choices, DEC requests and approval policy.
|
||||
Decision/Plan revisions enforce accepted authority, dependency completion, experiment
|
||||
reconsideration and unresolved concerns. SQL promotion/supersession and related
|
||||
references commit together. RUN failure rolls back its proposal and separately
|
||||
records a short diagnostic without references to reverted records. Request replay
|
||||
remains idempotent. No adapter can approve a DEC or answer on behalf of a human.
|
||||
|
||||
DEC approval is an explicit human-attestation command, with actor, reason and time.
|
||||
Accepted records are immutable through the CLI; revision creates a new linked draft.
|
||||
Acceptance supersedes the prior accepted DEC. Decision and plan changes preserve
|
||||
the previous complete file under `.history`, linked by SHA-256. Hashes detect broken
|
||||
chains; they are not signatures or protection against someone rewriting every file.
|
||||
Cross-record supersession uses per-file atomic publication; validation diagnoses
|
||||
incomplete links. There is no distributed transaction or automatic history repair.
|
||||
PlanCoordinator and EpicCoordinator retain SYSTEM_PLANS/SYSTEM_EPIC provenance,
|
||||
RESULTS/DECOMPOSITION policy and explicit scope-bound delegation. Related SQL
|
||||
mutations/propagation are transactional. Historical legacy semantics and hashes
|
||||
remain readable; only the legacy backend retains per-file recovery boundaries.
|
||||
|
||||
Verification separates structural validity, mechanical readiness and human judgment.
|
||||
PlanCoordinator consolidates valid Plan results without invoking an adapter, records
|
||||
SYSTEM_PLANS receipts and invokes existing EPIC propagation. Planning owns content-bound
|
||||
scope reviews of cancellations; Verification coordinates public mutations/reconciliation
|
||||
without a reverse dependency. Reads expose the same pending reasons without writes.
|
||||
Explicit reopening leaves time to change Plans. Legacy optional fields are omitted
|
||||
to preserve historical digests. See [the contract](plan-consolidation.md).
|
||||
StorageMigration previews canonical hashes, retains safety originals, imports typed
|
||||
records in a separate database, compares content/authority/history and validates
|
||||
before activation. Exact legacy bytes stay external for revision-chain verification;
|
||||
readers also compare them with typed rows. Contract 4 and a visible legacy-reader
|
||||
marker prevent incompatible writers. Recovery is repeatable; rollback refuses to
|
||||
lose engineering memory written after activation. Existing tracked originals are
|
||||
not removed. Details: [migration](storage-migration.md).
|
||||
|
||||
For inspection-only Works without Plans, manual
|
||||
readiness requires explicit criteria, resolved questions, reviewed DECs and terminal
|
||||
plans. Completion records criterion-to-artifact mappings, a stable scope digest,
|
||||
human approval, and canonical integration file digests or a reason no update is
|
||||
needed. Canonical-file hashes are historical snapshots; later source evolution does
|
||||
not invalidate an old delivery. Current completed Work records must still match
|
||||
their frozen scope. Archive retains every file. Reopening preserves completion and
|
||||
lifecycle history and permits new discussion/evidence.
|
||||
## Native package
|
||||
|
||||
Project owns provider-neutral entry resources copied into `.ai-engineering` by
|
||||
`init`/`onboard`, including a machine-readable manifest. A managed root `AGENTS.md`
|
||||
block points to those resources while preserving surrounding rules. Changed
|
||||
instructions are backed up; repeated onboarding is idempotent. Context includes the
|
||||
guide. This supports agents that inspect the project; it cannot force discovery by
|
||||
an arbitrary agent. `status` and `next-actions` derive diagnostics from persisted
|
||||
state without executing work or inventing human approval.
|
||||
`nativePackage` builds AIE and the pinned SQLite diagnostic CLI with companion native
|
||||
libraries and a checksum manifest. Native hints cover operational records/resources.
|
||||
The candidate verifier creates a disposable database with native AIE and reads it
|
||||
with packaged sqlite3. Install preparation is distinct from activation: versioned
|
||||
releases, a current symlink and shortcuts are switched only after verification.
|
||||
Installer tests use fake tools and disposable destinations. This Work did not run
|
||||
an actual installer or modify the active distribution or consumer projects.
|
||||
|
||||
## Discussion refinement and adapter boundary
|
||||
|
||||
Discussion still owns refinement; DEC and Plan remain its downstream commitments.
|
||||
Topics and surveys are functional records in Discussion. Legacy threads are derived
|
||||
as implicit topics; reads never migrate files. Answers append explicit supersession
|
||||
links. Archive/restore dispositions retain proposals and require policy/evidence.
|
||||
There is no separate Idea entity. See [record contracts](discussion-slice.md).
|
||||
|
||||
Agent is the tenth module. `AgentAdapter` accepts immutable context/task/executor
|
||||
values and returns a typed `AgentProposal`; it receives no filesystem Path, persistence
|
||||
service or execution tools. Only two deterministic adapters are registered. General
|
||||
selects an activity when omitted and provides fallback for unspecialized activities;
|
||||
an explicit activity selects its configured executor. Classification in fixtures uses
|
||||
task markers, not natural-language model interpretation.
|
||||
|
||||
AgentService validates the entire proposal before applying it through domain APIs.
|
||||
It rechecks the source fingerprint under the project lock to reject concurrent stale
|
||||
application. A RUN preserves source digest, selected executor, requester, task,
|
||||
proposal, applied references and terminal/error state. Completed request IDs provide
|
||||
idempotent replay of identical input. An interrupted APPLYING run blocks new runs
|
||||
pending inspection. Publication is atomic per file, not a rollback transaction;
|
||||
FAILED records and validation expose partial application for deliberate repair.
|
||||
|
||||
Verification reads run provenance and computes staleness from canonical semantic
|
||||
sources, excluding run bookkeeping. State checks never invoke an adapter. A summary
|
||||
is a recorded result; fresh context does not implicitly rerun it. Adapter output
|
||||
cannot provide human survey answers, approve DECs, complete Works or execute commands.
|
||||
Typed records and nested proposal values have Native Image reflection hints.
|
||||
The initial slice did not add provider integration; the local CLI slice below extends it.
|
||||
|
||||
## Local provider CLI transport
|
||||
|
||||
PLN-0003 implements the human-selected Codex/Claude CLI transport for Discussion and
|
||||
synthesis. The agent module retains the same public adapter boundary. Its internal
|
||||
LocalProcess uses fixed ProcessBuilder vectors, bounded streams, virtual threads,
|
||||
timeout/descendant termination and private temporary workspaces. It receives no
|
||||
engineering root. Provider tool/configuration controls constrain proposals, while
|
||||
OS/provider policy remains separate. The full contract and verified CLI references
|
||||
are in [cli-adapters.md](cli-adapters.md).
|
||||
|
||||
Versioned wire schemas normalize provider output into existing AgentProposal values;
|
||||
the framework assigns identity and performs ownership/policy preflight. Classification
|
||||
can request clarify surveys. An explicit activity skips that provider call. Immutable
|
||||
previous RUNs travel in context, but derived run bookkeeping stays out of semantic
|
||||
source fingerprints. Only validated results publish canonical RUNs. Earlier transport
|
||||
failures return safe diagnostics without mutating Work state or storing raw stderr.
|
||||
|
||||
Optional invocation provenance captures observed version, configured role/model,
|
||||
duration and output digest. Absent optional fields are omitted to preserve older
|
||||
fingerprints/digests. Setup collects/validates all answers before initialization and
|
||||
does not invoke providers. No Node SDK, HTTP client framework or external service is
|
||||
required by tests. Deterministic JDK subprocess fixtures use the production transport.
|
||||
|
||||
## EPIC coordination
|
||||
|
||||
PLN-0002 implements DEC-0003 within the existing modules. Work owns the EPIC marker,
|
||||
definition, forest topology, revision history and explicit policy authorization.
|
||||
Verification coordinates lifecycle writes and checks affected ancestors, using
|
||||
Artifact for owned aggregate receipts. No extra module, broker, workflow engine or
|
||||
agent invocation is needed. Low-level storage callers must reconcile explicitly;
|
||||
public CLI/Verification lifecycle entry points propagate within the project lock.
|
||||
|
||||
Policy authority binds parent/important-child scopes and links, excluding execution
|
||||
status. Important child completions and local readiness control RESULTS completion;
|
||||
DECOMPOSITION remains a reviewed human delivery. System completions record their
|
||||
origin, policy delegation and receipt, with humanApproved=false. Historical direct
|
||||
human completions keep their existing digest/approval semantics.
|
||||
|
||||
Frozen EPIC scope digests include current important delivery records; optional
|
||||
execution can continue independently. Deterministic serialization uses ordered maps
|
||||
and canonical records across JVM/native processes. Automatic receipts exclude prior
|
||||
receipts from their input key, allowing reuse after interrupted publication.
|
||||
Reconciliation derives state from files; no mutable in-memory index is authoritative.
|
||||
Details and explicit reopening/reauthorization rules are in [epics.md](epics.md).
|
||||
|
||||
## Compatibility inspection
|
||||
|
||||
The project module owns the protocol contract revision independently of the CLI
|
||||
release and manifest schema. Filesystem owns the supported storage-format catalog;
|
||||
existing typed readers continue interpreting older representations in memory.
|
||||
Verification's compatibility service inspects actual metadata and typed content,
|
||||
including record revisions and system completion receipts. The CLI exposes a full
|
||||
read-only report through `project compatibility` and a summary in `status`.
|
||||
|
||||
This adds no automatic conversion or blanket normalization. Onboarding refreshes
|
||||
entry instructions with backups and refuses to overwrite an unsupported contract.
|
||||
Frozen prior-release fixtures protect historical approvals, completion provenance,
|
||||
scope hashes and bytes. See [compatibility](compatibility.md) for the public contract
|
||||
and requirements before a future incompatible writer or migration is introduced.
|
||||
|
||||
## Earlier framework review and migration
|
||||
|
||||
Both implementations were inspected read-only:
|
||||
|
||||
- The user-identified Python repository at
|
||||
`/Users/niltonconstantino/personal/workspace.personal/intrepid/discussion-framework`:
|
||||
README, model/locking/index persistence and structural validation.
|
||||
- The sibling Java `discussion-framework`: `DiscussionOrchestrator`,
|
||||
`WorkflowValidator`, `WorkPacket`, `ArtifactDocumentParser` and
|
||||
`FilesystemDiscussionRepository` concepts and implementations.
|
||||
|
||||
Reused concepts: deterministic context as the handoff surface, stable IDs, explicit
|
||||
references, file locks, atomic replacement, duplicate/reference checks and separating
|
||||
content from mechanical CLI state management. No Python code or dependency was copied.
|
||||
The old generic Markdown inference was replaced by typed, versioned front matter;
|
||||
semantic sections are explicit and cannot silently disappear from context parsing.
|
||||
|
||||
No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic housekeeping
|
||||
deletion or Lesson model was retained. Work is the project-scoped aggregate; Discussion
|
||||
is refinement within a Work. Source repositories were not changed.
|
||||
|
||||
The deterministic DF importer reads each independent source's NDJSON index and open
|
||||
AGDs. It creates one Work per source+DSC, retaining agenda Markdown as refinement
|
||||
NOTEs and original bytes as evidence. A versioned owned receipt links source IDs,
|
||||
DSCs, AGDs, target descriptions and generated AIE references; existing Work schemas
|
||||
and historical data remain unchanged. Receipt validation is available without the
|
||||
source directory and compatibility inspection recognizes the receipt format.
|
||||
|
||||
Work, Discussion and Artifact expose prepared publication helpers using their normal
|
||||
formats. The importer seeds a complete hidden Work folder before the normal atomic
|
||||
directory publication and monotonic ID reservation. Revalidation under the destination
|
||||
lock binds application to the preview fingerprint; immutable receipts make retry
|
||||
recognize already published Works. A multi-Work batch is deliberately not a global
|
||||
transaction. No legacy decision/Plan/Lesson is imported, source files are untouched
|
||||
and no agent adapter is involved. See [the import contract](discussion-import.md).
|
||||
Legacy Lessons remain candidates for manual integration into canonical docs.
|
||||
Primary references: [SQLite JDBC native support](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support),
|
||||
[SQLite transactions](https://sqlite.org/lang_transaction.html),
|
||||
[foreign keys](https://sqlite.org/foreignkeys.html),
|
||||
[official source releases/checksums](https://sqlite.org/download.html),
|
||||
[Boot requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html),
|
||||
[Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html).
|
||||
|
||||
+25
-13
@@ -1,7 +1,7 @@
|
||||
# Compatibility and protocol evolution
|
||||
|
||||
A project's historical records do not have to be rewritten whenever AIE evolves.
|
||||
Completed Works retain their original files, approvals, evidence and completion
|
||||
Completed Works retain useful memory, approvals, validated evidence results and completion
|
||||
provenance. Continued readability is a reader responsibility, not a reason to reopen
|
||||
delivered work or to add current refinement content to old Works.
|
||||
|
||||
@@ -32,13 +32,24 @@ No repository commands, adapters, locks or writes occur during compatibility rea
|
||||
| `UNSUPPORTED` | A declared version has no supported reader | 4 |
|
||||
| `INVALID` | Malformed metadata, unknown fields, missing records or invalid typed content | 4 |
|
||||
|
||||
The report is an inspection, not a conversion plan. No required migrations are
|
||||
registered, so `migrationRequired` is false, including for unsupported versions:
|
||||
The report is an inspection, not a conversion plan. Legacy reading does not require conversion, so `migrationRequired` is false, including for unsupported versions:
|
||||
an unknown version is not evidence that an older CLI can convert it. Unsupported
|
||||
records require a CLI with the appropriate reader; invalid data needs deliberate
|
||||
repair. Basic command/path errors retain the usual exit codes.
|
||||
|
||||
## Three independent version dimensions
|
||||
Contract 4 adds `sqlite-storage`, `local-memory`, `quality-gates`,
|
||||
`temporary-artifacts` and the explicit storage migration route. New projects select
|
||||
SQLite and ignore state by default. Legacy projects can remain readable on their
|
||||
original backend. SQLite requires contract 4; a database without the matching
|
||||
bootstrap is refused rather than treated as empty memory.
|
||||
|
||||
The SQLite report inspects typed records/revisions in the database. Bootstrap,
|
||||
database schema and original legacy document versions remain separate dimensions.
|
||||
Project validation checks foreign keys, revision chains and evidence/retirement facts.
|
||||
A retired attachment is valid historical evidence only with its persisted validation;
|
||||
new checks still require available inputs.
|
||||
|
||||
## Independent version dimensions
|
||||
|
||||
`protocol.json.schemaVersion` describes the manifest's structure. Its new optional
|
||||
`protocolVersion` identifies the engineering contract. The initial explicit contract
|
||||
@@ -49,7 +60,7 @@ operations and onboarding from overwriting a newer contract. Compatibility inspe
|
||||
remains available to explain the mismatch.
|
||||
|
||||
Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts
|
||||
1, 2 and 3, and existing contract-1 projects remain legacy compatible without any
|
||||
1, 2, 3 and 4, and existing contract-1 projects remain legacy compatible without any
|
||||
Work migration. An import-enabled manifest requires contract 2 and the
|
||||
`discussion-import` capability. This makes old contract-1 CLIs refuse the new
|
||||
manifest before onboarding could overwrite its feature declaration. `onboard`
|
||||
@@ -70,7 +81,8 @@ The format catalog is deliberately small:
|
||||
| Canonical record schema (including configuration and Work) | 1 | 1 |
|
||||
| Narrative document | 2 | 1, 2 |
|
||||
| Metadata-only document (Work) | 1 | 1 |
|
||||
| Work sequence | 2 | 1, 2 |
|
||||
| Work sequence (legacy files) | 2 | 1, 2 |
|
||||
| SQLite schema/application | 1 / AIE1 | 1 / AIE1 |
|
||||
|
||||
`schemaVersion` and `documentVersion` describe different layers of one file. A
|
||||
discussion may have record schema 1 in document version 2. An omitted document
|
||||
@@ -84,7 +96,7 @@ record has been converted. The scanner reads actual versions in current records
|
||||
history; mixed supported versions are normal. Capabilities are discovery labels,
|
||||
not independent migration versions or evidence that a feature has been configured.
|
||||
|
||||
## Updating instructions and future migrations
|
||||
## Updating instructions and storage
|
||||
|
||||
`aie onboard` is idempotent and backs up changed entry files. It refreshes the README,
|
||||
agent instructions and manifest, preserving project rules outside the managed block.
|
||||
@@ -99,12 +111,12 @@ reader/adaptation path and retained fixtures. Unknown schemas and fields must no
|
||||
be silently ignored to simulate compatibility. Increasing a writer version must not
|
||||
remove an existing reader or alter the meaning of historical approval/provenance.
|
||||
|
||||
A future required conversion must declare its source and target versions and expose
|
||||
a public command that previews exact scope before applying changes, backs up original
|
||||
bytes, resumes safely and is idempotent. The report may only claim a required migration
|
||||
when a known route actually exists. Completed historical Works must retain a read path;
|
||||
they must not be selected for blanket normalization. There is no placeholder migration
|
||||
command and no automatic project-wide rewrite in this release.
|
||||
The public SQLite route is `storage migrate` (read-only preview), then
|
||||
`--apply --expect HASH`. `--recover` and `--rollback` require the operation's same
|
||||
fingerprint. It is optional for supported legacy reading and never runs implicitly.
|
||||
Read [the migration procedure](storage-migration.md) before conversion. Unknown
|
||||
schemas still need an appropriate reader; this route converts supported legacy
|
||||
records, not arbitrary unsupported versions.
|
||||
|
||||
## Historical regression fixture
|
||||
|
||||
|
||||
@@ -92,3 +92,8 @@ Exit codes follow AIE: 0 for a valid preview/application, 2 for invalid command
|
||||
arguments, 3 for a missing project/root, 4 for invalid/stale/review-required data,
|
||||
and 1 for unexpected I/O failures. Diagnostics after partial publication retain
|
||||
the normal failure code and identify the Work IDs already published.
|
||||
|
||||
SQLite application commits the batch and its references together. Failure rolls back
|
||||
all Works in that transaction and recovers owned temporary payloads. The explicit
|
||||
legacy backend keeps its per-Work publication/resume boundary. Imported originals
|
||||
and import provenance remain preserved by the current retention policy.
|
||||
|
||||
@@ -12,11 +12,12 @@ Existing free-form discussionId threads remain valid and appear as implicit topi
|
||||
an empty Work presents implicit topic `main`. Formal topics can reference original
|
||||
discussion entries without rewriting those entries.
|
||||
|
||||
Records reside in Work-local `topics/`, `surveys/`, `dispositions/` and `agent-runs/`.
|
||||
Prose uses Markdown bodies with documentVersion 2 and schemaVersion 1 metadata.
|
||||
Topic and survey revisions preserve complete prior files with SHA-256 links under
|
||||
their `.history/` directories, following decision/plan conventions. New files are
|
||||
published before Work references; interrupted cross-file writes are diagnosed.
|
||||
SQLite stores these records and their revisions as typed data. Related publication
|
||||
and Work references commit together. Legacy directories/Markdown and `.history`
|
||||
remain supported on the explicit file backend; migration preserves original bytes.
|
||||
SQLite RUN application rolls back the full proposal on failure, then records a short
|
||||
failure diagnostic without reverted references. Legacy failed publication can retain
|
||||
partial applied references for deliberate repair.
|
||||
|
||||
A survey owns immutable question definitions and append-only answers. QST and ANS
|
||||
IDs are survey-local. Each question identifies a topic and nonempty options numbered
|
||||
|
||||
+6
-4
@@ -1,7 +1,7 @@
|
||||
# EPIC contract
|
||||
|
||||
An EPIC is a Work with `epic: true` and a versioned definition under
|
||||
`epic/<Work ID>.md`. Ordinary schema-1 Works default to `epic: false`; reads never
|
||||
An EPIC is a Work with `epic: true` and a versioned typed SQLite policy.
|
||||
The legacy file backend uses `epic/<Work ID>.md`. Ordinary schema-1 Works default to `epic: false`; reads never
|
||||
rewrite them. Definition revisions retain SHA-256-linked snapshots under
|
||||
`epic/.history/<Work ID>/`. Links point to project-scoped Work IDs, not source repos.
|
||||
|
||||
@@ -50,9 +50,11 @@ editing links/scopes and reviewing authorization again.
|
||||
`epic check` is read-only. `epic reconcile` deterministically repairs missed
|
||||
propagation from canonical child state, including after interruption between child
|
||||
and parent writes. Repeated notifications do not duplicate completion or receipts.
|
||||
No server, message broker, database or agent invocation is used. Invalid histories,
|
||||
SQLite is embedded; no server, message broker or agent invocation is used. Invalid histories,
|
||||
missing links and unsafe paths are diagnosed; arbitrary corrupted files still need
|
||||
deliberate repair. Publication remains atomic per file, not a global transaction.
|
||||
deliberate repair. SQLite commits related propagation transactionally; only legacy
|
||||
files retain per-file publication. Required gates also constrain parent delivery.
|
||||
New aggregate receipts are structured database facts; old receipt files stay readable.
|
||||
|
||||
## CLI
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# WRK-000C measurement handoff
|
||||
|
||||
SQLite adoption does not close the latency ticket. This scenario prepares comparable
|
||||
local datasets; it makes no performance claim and was not run as a benchmark in
|
||||
WRK-000D. Use the same final executable/package, machine and source revision for
|
||||
both backends. Keep companion libraries beside the executable.
|
||||
|
||||
```sh
|
||||
python3 scripts/latency-fixture.py --binary "$PWD/build/native/package/ai-engineering" \
|
||||
--directory /tmp/aie-latency-sqlite --works 100 --entries 10 --storage sqlite
|
||||
python3 scripts/latency-fixture.py --binary "$PWD/build/native/package/ai-engineering" \
|
||||
--directory /tmp/aie-latency-legacy --works 100 --entries 10 --storage legacy
|
||||
```
|
||||
|
||||
Directories must be new. The script creates only synthetic Works/notes, with no
|
||||
approval, installation or migration. `latency-fixture.json` records version, binary
|
||||
SHA-256, backend, environment, volume and selected Work. Creation time is distinct
|
||||
from query latency. Record the source revision/build identifier as well; the release
|
||||
label alone is insufficient to distinguish this checkout from older 0.1.0 builds.
|
||||
|
||||
Measure fresh processes separately from repeated queries. In each dataset, repeat
|
||||
`work show WRK-0064 --format json`, `work context WRK-0064 --format json`,
|
||||
`next-actions WRK-0064 --format json`, `work list --open --format table` and
|
||||
`status --format json`. Capture wall time, exit status and whether the command gives
|
||||
feedback while waiting; avoid including terminal rendering time accidentally.
|
||||
Record each sample, then compare median and tail latency. Vary volume afterward
|
||||
(1/10/100 Works), using identical note counts and commands across both backends.
|
||||
|
||||
Record OS/CPU, package/JVM mode, protocol/database schema and source access settings.
|
||||
Use no registered Git repositories first, then measure their contribution separately.
|
||||
Do not mix migration, integrity repair, network/provider calls or fixture generation
|
||||
into query timing. The current physical native verification used macOS arm64 and
|
||||
GraalVM CE 25.5.5.0+3 with SQLite JDBC 3.54.1.0 / sqlite3 3.54.1; other machines need
|
||||
their own recorded environment. WRK-000C remains OPEN until actual measurements and
|
||||
responsiveness criteria justify its decision and implementation.
|
||||
@@ -0,0 +1,609 @@
|
||||
# Legacy file backend reference
|
||||
|
||||
This reference applies to the explicit legacy backend. New projects use SQLite.
|
||||
For current persistence, gates and retention, read [the protocol](protocol.md).
|
||||
When recreating legacy examples, add `--storage legacy` to init.
|
||||
Legacy source documents retained by migration are not a second writable authority.
|
||||
|
||||
# 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.
|
||||
|
||||
`work list`, `status`, and `next-actions` support `--format table|csv|markdown|json`.
|
||||
Their default Markdown output is a table; `table` aligns columns for terminals,
|
||||
and CSV provides UTF-8 comma-separated records with stable headers and RFC 4180
|
||||
quoting/CRLF record endings. CSV emits no project preamble and keeps original
|
||||
multiline field values. Empty results still have headers. JSON retains its full
|
||||
existing records (`Work[]`, `ProjectStatus`, and `Action[]`, respectively).
|
||||
|
||||
Work table/CSV/Markdown columns are `id`, `title`, `status`, `archived`, `steps`,
|
||||
`pending_actions`, `validation`, and `next_action` (human formats use display
|
||||
labels). Progress counts COMPLETED steps over all registered steps across Plans,
|
||||
including cancelled steps in the denominator. No steps means `0/0`; unreadable
|
||||
Plan data means `unavailable`, with invalid validation and a repair suggestion.
|
||||
Pending actions count deterministic suggestions, including execution and
|
||||
maintenance; they are not solely blockers or semantic progress. The next command
|
||||
is the first existing suggestion, without a new prioritization algorithm.
|
||||
Action columns are `work_id`, `code`, `message`, and `command`. A project-level
|
||||
action has an empty `work_id`. Markdown escapes cell text; terminal tables flatten
|
||||
line breaks/control characters without truncating field values.
|
||||
|
||||
`work list --open` filters every format to nonterminal, unarchived Works: OPEN,
|
||||
ACTIVE, and BLOCKED. Unfiltered Work lists continue to include archived Works.
|
||||
Tabular formats apply to these three read commands only; other commands retain
|
||||
their existing format choices. No storage or protocol revision is required.
|
||||
|
||||
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 eligible DRAFT decisions without an adapter
|
||||
or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC
|
||||
needs human approval before Plan creation. Legacy Works retain prior promotion
|
||||
semantics until explicit guidance adoption. 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.
|
||||
|
||||
## Work guidance and OODA
|
||||
|
||||
Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask
|
||||
for human discussion mode and require human DEC approval by default; explicit
|
||||
Work-wide waivers and requests retain human provenance. Guided operations enforce
|
||||
the selected authority. See [Work conduct and adaptive implementation](work-guidance.md)
|
||||
for commands, experiment criteria/results, affected execution and legacy behavior.
|
||||
This preserves the existing loops and does not add a repository executor.
|
||||
|
||||
## 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.
|
||||
@@ -34,8 +34,11 @@ Receipts use origin `ai-engineering:plans:<receipt-sha256>`. Their input hash om
|
||||
framework receipts so a published receipt can be reused after interruption. Final
|
||||
completion freezes the full scope including the receipt. Recovery validates
|
||||
integrity/history, consolidates Plans, publishes/reuses a receipt, records completion
|
||||
and invokes existing EPIC reconciliation. Publication is atomic per file; malformed
|
||||
or orphan records require explicit repair rather than silent deletion.
|
||||
and invokes existing EPIC reconciliation. SQLite commits these related changes
|
||||
together; legacy publication remains per-file. New receipts are structured facts in
|
||||
SQLite. Required project/Work gates must pass for the current evaluated state;
|
||||
temporary step inputs retire only after all Work checks and completion commit.
|
||||
Malformed or orphan records require explicit repair.
|
||||
|
||||
Existing completed Works and legacy serialized hashes remain unchanged. New
|
||||
optional fields are omitted when absent. Manual completion remains available for
|
||||
|
||||
+138
-592
@@ -1,602 +1,148 @@
|
||||
# Portable engineering protocol — schema 1
|
||||
# Local engineering memory protocol
|
||||
|
||||
## Project root and configuration
|
||||
AIE is a local framework per project. `.ai-engineering/aie.db` owns operational
|
||||
memory: Works, investigation, decisions, Plans, execution facts and gate results.
|
||||
Small YAML/JSON and README/AGENTS files bootstrap discovery and configuration.
|
||||
There is no database server or background process. Git and source repositories are
|
||||
optional; synchronization, distributed IDs, Git LFS and Work/DEC export are outside
|
||||
this version.
|
||||
|
||||
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).
|
||||
## Starting and continuing
|
||||
|
||||
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.
|
||||
Run `aie status`, `aie next-actions`, then `aie work context WRK-0001`.
|
||||
The closest enclosing `.ai-engineering` owns the project. `--project PATH` selects
|
||||
one explicitly. A SQLite workspace requires a compatible CLI; unavailable or
|
||||
unreadable memory must be reported, never treated as an empty project.
|
||||
|
||||
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.
|
||||
`init --name TEXT` defaults to SQLite and adds `/.ai-engineering/` to .gitignore.
|
||||
`--version-state` leaves ignore policy to the developer without removing existing
|
||||
rules. Existing tracked files are not untracked. `--storage legacy` is an explicit
|
||||
compatibility option. Neither reads, `onboard`, nor installation migrate storage.
|
||||
|
||||
```yaml
|
||||
schemaVersion: 1
|
||||
project:
|
||||
id: prometeu
|
||||
name: Prometeu
|
||||
repositories:
|
||||
- id: runtime
|
||||
path: runtime
|
||||
type: linked-git
|
||||
language: rust
|
||||
access:
|
||||
read: true
|
||||
edit: false
|
||||
validationCommands: []
|
||||
Work IDs are uppercase hexadecimal (`WRK-000A`); child IDs are decimal and local to
|
||||
their Work (`DEC-0001`, `PLN-0001`, `TSK-0001`). The database transaction reserves
|
||||
new identities and owned references together. Migration preserves reserved gaps.
|
||||
|
||||
## Investigation and implementation
|
||||
|
||||
Discussion/investigation and implementation remain separate cycles connected by
|
||||
DEC and Plan. Work stores scope, criteria and useful refinement; topics, surveys,
|
||||
answer supersession and explicit conclusions preserve continuity. OODA is adaptive:
|
||||
observe results, reconsider assumptions, decide and act. It is not a four-step
|
||||
ritual imposed on every edit.
|
||||
|
||||
Ask for DIRECT or EXPLORATORY when unspecified. Only the human chooses/changes the
|
||||
mode or ends exploration. Record choices with `work guidance --human-approved`;
|
||||
exploratory DEC emission needs `work request-decision`. Human DEC approval is the
|
||||
default. Direct mode does not waive it. An explicit Work-wide waiver is recorded
|
||||
separately. Never infer approval from an adapter proposal or status label.
|
||||
|
||||
Accepted DECs are immutable; revisions/supersession retain their authority and
|
||||
history. Plans require applicable accepted decisions and resolved discussion.
|
||||
Steps have dependencies, criteria and results. Relevant experiments record their
|
||||
hypothesis/criterion before execution and observations/interpretation afterward.
|
||||
Failed hypotheses require reconsideration before retry; DEC concerns block affected
|
||||
execution until the accepted replacement is referenced.
|
||||
|
||||
See [Work guidance/OODA](work-guidance.md), [refinement](discussion-slice.md) and
|
||||
[Plan consolidation](plan-consolidation.md) for command details.
|
||||
|
||||
## Quality gates
|
||||
|
||||
Required project gates and additional Work gates are cumulative. A Work cannot
|
||||
replace a project gate by reusing its local name. Define the procedure and relevant
|
||||
input files/directories before evaluating it:
|
||||
|
||||
```sh
|
||||
aie gate configure tests --title "Project tests" --procedure "./gradlew check" \
|
||||
--input src --input build.gradle.kts --require-evidence --by owner
|
||||
aie gate configure review --work WRK-0001 --title "Work review" \
|
||||
--procedure "Review the DEC criteria" --input src --by owner
|
||||
aie gate status WRK-0001 --format json
|
||||
```
|
||||
|
||||
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.
|
||||
Obtain `evaluatedHash` before running the procedure externally. Attach required
|
||||
small evidence with `artifact add`. Then record the actual result:
|
||||
|
||||
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
|
||||
```sh
|
||||
aie gate record WRK-0001 project/tests --expect <evaluatedHash> \
|
||||
--invocation "./gradlew check" --outcome PASS --summary "Observed checks passed" \
|
||||
--evidence ART-0001 --by observer --observed
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
`work list`, `status`, and `next-actions` support `--format table|csv|markdown|json`.
|
||||
Their default Markdown output is a table; `table` aligns columns for terminals,
|
||||
and CSV provides UTF-8 comma-separated records with stable headers and RFC 4180
|
||||
quoting/CRLF record endings. CSV emits no project preamble and keeps original
|
||||
multiline field values. Empty results still have headers. JSON retains its full
|
||||
existing records (`Work[]`, `ProjectStatus`, and `Action[]`, respectively).
|
||||
|
||||
Work table/CSV/Markdown columns are `id`, `title`, `status`, `archived`, `steps`,
|
||||
`pending_actions`, `validation`, and `next_action` (human formats use display
|
||||
labels). Progress counts COMPLETED steps over all registered steps across Plans,
|
||||
including cancelled steps in the denominator. No steps means `0/0`; unreadable
|
||||
Plan data means `unavailable`, with invalid validation and a repair suggestion.
|
||||
Pending actions count deterministic suggestions, including execution and
|
||||
maintenance; they are not solely blockers or semantic progress. The next command
|
||||
is the first existing suggestion, without a new prioritization algorithm.
|
||||
Action columns are `work_id`, `code`, `message`, and `command`. A project-level
|
||||
action has an empty `work_id`. Markdown escapes cell text; terminal tables flatten
|
||||
line breaks/control characters without truncating field values.
|
||||
|
||||
`work list --open` filters every format to nonterminal, unarchived Works: OPEN,
|
||||
ACTIVE, and BLOCKED. Unfiltered Work lists continue to include archived Works.
|
||||
Tabular formats apply to these three read commands only; other commands retain
|
||||
their existing format choices. No storage or protocol revision is required.
|
||||
|
||||
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 eligible DRAFT decisions without an adapter
|
||||
or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC
|
||||
needs human approval before Plan creation. Legacy Works retain prior promotion
|
||||
semantics until explicit guidance adoption. 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.
|
||||
|
||||
## Work guidance and OODA
|
||||
|
||||
Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask
|
||||
for human discussion mode and require human DEC approval by default; explicit
|
||||
Work-wide waivers and requests retain human provenance. Guided operations enforce
|
||||
the selected authority. See [Work conduct and adaptive implementation](work-guidance.md)
|
||||
for commands, experiment criteria/results, affected execution and legacy behavior.
|
||||
This preserves the existing loops and does not add a repository executor.
|
||||
|
||||
## 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.
|
||||
`--observed` attests an actual external check; it is not human DEC approval.
|
||||
AIE does not execute the procedure or establish the semantic truth of a claim.
|
||||
Results retain definition, invocation, scope/input fingerprint, moment, observer,
|
||||
outcome and short summary. `gate history` exposes prior observations. Changed
|
||||
inputs, Work scope/guidance, DEC revisions or gate definitions require evaluation
|
||||
again. Plan/status bookkeeping does not invalidate the check.
|
||||
|
||||
Pending, failed or stale gates prevent manual, Plan and EPIC delivery. Completion
|
||||
freezes references/hashes of the actual gate results in the same transaction.
|
||||
Later source/policy changes do not invent checks on old deliveries; reopened work
|
||||
requires applicable current results. Imported deliveries keep their historical
|
||||
contract, without fabricated retroactive gates.
|
||||
|
||||
## Temporary inputs and outputs
|
||||
|
||||
`artifact add WRK --file PATH --purpose TEXT` copies a small input to the filesystem
|
||||
with owned integrity metadata; bytes never become BLOB, base64 or file-shaped TEXT
|
||||
in SQLite. Inputs remain available during dependent checks. Finishing a partial
|
||||
step or gate alone does not mean all future Work checks have consumed an input.
|
||||
|
||||
At Work completion, integrity and completion facts commit before eligible payloads
|
||||
are removed. AVAILABLE, DISCARD_PENDING and DISCARDED distinguish usable input,
|
||||
interrupted cleanup and legitimate retirement. Current evaluations require available
|
||||
inputs; a retired artifact cannot be reused after reopening. Historical queries
|
||||
use the validated result, and missing input before evaluation remains an error.
|
||||
|
||||
`artifact recover WRK` finishes interrupted publication/retirement. Reads only expose
|
||||
recovery actions. Publication journals identify owned residue; unknown files require
|
||||
inspection. Adapter process workspaces are temporary and cleaned at execution end.
|
||||
New Plan/EPIC receipts are structured facts, without an extra JSON file. Imported
|
||||
originals and migration safety copies remain preserved until explicit disposition.
|
||||
|
||||
Requested documents/images/other deliverables belong at their output destination,
|
||||
outside `.ai-engineering`; code stays in the source repository. AIE does not require
|
||||
a permanent duplicate solely for auditing. Cleanup targets owned temporary copies,
|
||||
never the source/deliverable.
|
||||
|
||||
## Persistence, consistency and recovery
|
||||
|
||||
SQLite uses foreign keys, WAL, FULL durability, IMMEDIATE writes and bounded writer
|
||||
waits. Nested domain mutations share the transaction; related reads use a snapshot.
|
||||
An OS publication lock coordinates writers with storage activation/rollback, with
|
||||
bounded waits for SQLite commands. Backend changes during a wait require a retry.
|
||||
|
||||
Typed columns and ordered child rows retain domain data. Nullable historical lists
|
||||
remain distinct from empty lists. Revision hashes reconstruct the relevant typed
|
||||
representation or verify retained original bytes. Migration also compares original
|
||||
representations to typed records, detecting changed historical rows.
|
||||
|
||||
RUN application is transactional on SQLite. Failure rolls back the whole proposal;
|
||||
a separate failure record has a short diagnostic and no rolled-back applied refs.
|
||||
Request IDs retain idempotence. Adapters cannot answer for humans, approve DECs,
|
||||
complete Works or execute repository commands through this framework.
|
||||
|
||||
Legacy storage retains its per-file publication/recovery behavior. Supported legacy
|
||||
records remain readable; [the legacy reference](legacy-file-storage.md) documents
|
||||
those file formats. [Storage migration](storage-migration.md) is explicit, staged,
|
||||
verified and recoverable. No consumer or installed executable is automatically
|
||||
converted by a new build.
|
||||
|
||||
## Verification and closure
|
||||
|
||||
`project validate` checks the project, identities, graph, references, history and
|
||||
integrity. `work validate` scopes checks to selected memory and its dependencies.
|
||||
`work check` reports mechanical readiness, not semantic proof of prose criteria.
|
||||
`status`, `next-actions` and context are read-only projections.
|
||||
|
||||
Required completed Plans consolidate through SYSTEM_PLANS receipts; RESULTS EPICs
|
||||
still need explicit current authorization, and DECOMPOSITION remains reviewed.
|
||||
Empty sets, open questions/experiments, unresolved DEC concerns and unfinished scope
|
||||
remain pending. Cancelled content needs explicit scope review. Reopening preserves
|
||||
history and does not immediately reconclude unchanged old Plans. Archive preserves
|
||||
memory, not an obligation to retain every temporary file.
|
||||
|
||||
Exit codes: 0 success, 1 I/O/runtime, 2 invalid input, 3 missing resource, 4 validation
|
||||
or readiness failure. Use command `--help` for exact options.
|
||||
|
||||
+12
-2
@@ -28,7 +28,7 @@ and long proposals can be authored as ordinary Markdown files before persistence
|
||||
Acceptance demonstration: initialize a project with two independent Git repositories,
|
||||
create a Work referencing both, append discussion, persist a draft decision and
|
||||
evidence, export context, then reconstruct the same context in independent processes
|
||||
using only files. No framework state or model history may be required.
|
||||
using persisted local memory and a compatible CLI. No process-local model history may be required.
|
||||
|
||||
Platform release targets: Linux x86_64, macOS ARM64, macOS x86_64 and Windows x86_64.
|
||||
The workflow builds the three available GraalVM 25 platforms. **macOS x86_64 is blocked
|
||||
@@ -89,7 +89,7 @@ completion requires explicit policy delegation, local readiness and valid import
|
||||
deliveries; receipts distinguish system results from human delivery approvals.
|
||||
|
||||
Lifecycle commands propagate outcomes/reopenings and return a deterministic report.
|
||||
Reconciliation recovers missed propagation from files without an LLM. Acceptance
|
||||
Reconciliation recovers missed propagation from persisted state without an LLM. Acceptance
|
||||
covers independent processes, repeated notification, policy/scope changes, history,
|
||||
important/optional/cancelled children and native standalone execution. Actual observed
|
||||
results are recorded in [experiments](experiments.md).
|
||||
@@ -150,3 +150,13 @@ checks against evidence; identify impacted canonical specs, tests,
|
||||
code and documentation; expose conformance checks to agents and CI. Acceptance: a Work
|
||||
can demonstrate its outcome and preserve actionable knowledge without a mandatory
|
||||
Lesson model or redundant documentation trail.
|
||||
|
||||
## Local SQLite memory
|
||||
|
||||
Implemented in WRK-000D: typed per-project SQLite memory, transactional domain
|
||||
mutations, cumulative project/Work gates, temporary attachments and structured
|
||||
receipts, snapshot reads, explicit recoverable legacy migration and default Git
|
||||
ignore policy. Native AIE/JDBC/sqlite3 packaging is prepared and verified; actual
|
||||
installation and consumer migration remain deferred. The latency ticket WRK-000C
|
||||
remains open for separate measurement. Work/DEC sharing, distributed sync,
|
||||
Git LFS and backup/export are future discussions.
|
||||
|
||||
@@ -0,0 +1,421 @@
|
||||
# SQLite persistence: legacy mapping and migration cases
|
||||
|
||||
This is the implementation map for WRK-000D / DEC-0001 / PLN-0001, starting with
|
||||
TSK-0001. It describes the inspected file backend and the invariants the SQLite
|
||||
implementation must preserve. The implementation sections below record the completed SQLite integration; the
|
||||
source inventory also documents the supported legacy backend.
|
||||
|
||||
The active CLI and this repository's canonical `.ai-engineering` remain on the file
|
||||
backend. Native installation, replacement of active binaries/libraries/shortcuts,
|
||||
and migration of consumer projects are deferred by explicit human instruction.
|
||||
Implementation and verification use fixtures, disposable copies and build outputs.
|
||||
|
||||
## Persistence boundary
|
||||
|
||||
One SQLite database, `.ai-engineering/aie.db`, will own a local project's Work
|
||||
memory. Keep discovery/configuration/agent entry files small and explicit where
|
||||
bootstrap needs them. A file named `aie.db` alone does not establish that migration
|
||||
completed or that the installed CLI can read its schema.
|
||||
|
||||
Store domain fields and relationships, not files encoded as BLOB, base64 or a large
|
||||
TEXT document. Ordered child data belongs to typed dependent rows; constrained
|
||||
operational structures may use an explicit codec when they are not independently
|
||||
queried. Do not put every aggregate into a serialized `work.md` column.
|
||||
|
||||
Generated contexts, readiness/evaluation reports, suggested actions and freshness
|
||||
flags are projections, not additional authorities. Rebuild them from the applicable
|
||||
records in a consistent read transaction. File payloads remain outside SQLite.
|
||||
|
||||
## Source-to-target inventory
|
||||
|
||||
Table names below identify logical groups for the schema step, not a final SQL
|
||||
migration. Preserve ordered lists and nullable/omitted historical values where they
|
||||
affect interpretation or digests. Do not change externally visible identities.
|
||||
|
||||
| Source and owner | Domain data to preserve | Target groups and invariants |
|
||||
|---|---|---|
|
||||
| `ai-engineering.yaml`; `ProjectService`, `ProjectConfig` | Project identity/name; repositories, paths/type/language/access/validation commands; general/activity adapters, profile/model/timeout and archive policy | Bootstrap configuration and typed configuration records; one authority per field. Empty repositories are valid. Repository access defaults to read-only. A source repository is optional. |
|
||||
| `protocol.json`, entry README/AGENTS; `ProtocolGuide`, `ProtocolContract` | Contract/schema versions, capabilities, startup and managed instruction boundaries | Explicit storage/schema discovery and compatibility. Preserve external project rules. Unsupported contracts fail before writes. `onboard` is not data migration. |
|
||||
| `works/.sequence.yaml`; `WorkService.Sequence` | Highest reserved Work number, including gaps | Transactional project-local allocation. Preserve legacy high-water interpretation; never recompute solely from surviving Works or rename decimal-looking historical IDs. |
|
||||
| `work.md`; `Work` | ID, title, description, goal, motivation, ordered constraints/acceptance criteria, status, timestamps, author, repository revisions and all child references | `works`, ordered scope/revision rows and owned references. A Work ID is project-wide; `(work_id, child_id)` identifies a Work-local child. Preserve terminal/editability/archive/reopen semantics. |
|
||||
| Work guidance; `WorkGuidance` | Mode, approval policy, explicit choice history and decision requests, with actor/reason/time/human attestation | Guidance/choice/request rows. Absence in a historical Work differs from newly UNSPECIFIED guidance. Only recorded human instructions change authority. |
|
||||
| Work completion/events; `Work.Completion` | Criterion texts and evidence references; scope hash, integrations, summary, origin, delegation/aggregation, actor/time and lifecycle events | Completion/criterion/integration/event rows. Preserve HUMAN, SYSTEM_EPIC and SYSTEM_PLANS provenance, not just COMPLETED status. Do not invent approval during migration. |
|
||||
| `discussions/DSC-*.md`; `DiscussionEntry` | Work/thread/topic, kind, author/time, exact narrative, optional earlier response target | Discussion entries and response edges in source order. QUESTION/ISSUE remains pending until an explicit linked RESPONSE/CONCLUSION. Preserve UTF-8, Markdown and whitespace. |
|
||||
| `topics/TOP-*.md`, `.history`; `TopicService` | Title/description, ordered source discussion IDs, revision/hash/editor/reason/time | Topic/current revision/source rows. Legacy threads remain implicit topic views, without fabricated formal topic history. |
|
||||
| `surveys/SVY-*.md`, `.history`; `SurveyService` | Questions/options/recommendation/multiple flag/topic/sources; every answer, selected choices, author/time and supersedes link | Survey/question/option/answer/choice rows and revision provenance. Recommendations are not answers. Superseded answers remain available; latest answer determines pending state. |
|
||||
| `dispositions/DSP-*.md`; `DispositionService` | Target entry, ARCHIVE/RESTORE, reason/evidence, author/time | Owned disposition/evidence references. Archive remains subject to the configured policy; restore does not delete the original proposal. |
|
||||
| `decisions/DEC-*.md`, `.history`; `DecisionService` | Narrative/context/approach/rationale, alternatives/risks/criteria/evidence, approval status/history, revisions and revises/supersededBy | Decision/revision/approval/list/reference rows. DIRECT and SYSTEM_PLAN approval provenance stay distinct; preserve causal Plan IDs and no-human-attestation semantics of permitted system promotion. |
|
||||
| `plans/PLN-*.md`, `.history`; `PlanService` | Narrative, decisions, steps and ordered criteria/dependencies/results/evidence; status/revisions; scope exclusions; experiments | Plan/revision/step/dependency/exclusion/experiment rows. Excluding cancelled scope does not satisfy a dependency; completed steps still require results and applicable checks. |
|
||||
| Plan experiments; `Experiment` | Hypothesis, criterion, invocation, step, author/time; observed outcome, interpretation/next action/evidence, retry/reconsideration, questioned DEC | Experiment/result/reference rows. Criteria precede results; failed retries require reconsideration. Open experiments and unresolved DEC concerns continue to block affected execution. |
|
||||
| `epic/WRK-*.md`, `.history`; `EpicService` | RESULTS/DECOMPOSITION, ordered children/importance, revision/hash, explicit scope-bound authorization | EPIC policy/revision/link/authorization rows. Enforce existing forest topology, one parent, no cycles and no authorization inferred from status. |
|
||||
| `agent-runs/RUN-*.md`; `AgentService`, `AgentRun` | Request identity/task/activity/requester/executor/source hash; APPLYING/COMPLETED/FAILED, typed proposal, applied references, diagnostic and invocation provenance | Run/proposal/applied-reference/invocation rows. Preserve idempotency and interrupted publication diagnostics; do not retain raw transport, environment or credentials. |
|
||||
| `artifacts/evidence/ART-*/artifact.yaml`; `ArtifactService` | Work-local identity, origin/purpose/path, SHA-256, size, author/time | Artifact metadata and references. New temporary evidence needs explicit lifecycle state. Payload bytes are external; their absence is not success unless legitimate post-check disposal is recorded. |
|
||||
| Plan/EPIC completion and DF-import receipt payloads | Typed receipt identity, inputs, referenced source revisions/hashes and producer provenance | Typed internal receipt/source rows. These are protocol state; parse only recognized owned receipts, not arbitrary user payloads. Preserve legacy payload/representation provenance when required. |
|
||||
| `runs/`, `artifacts/outputs`, references and experiment files | Temporary execution files, requested deliverables and external references | Filesystem lifecycle/paths only when needed. A RUN record differs from the ignored `runs/` folder. Do not promote every generated file into permanent evidence. |
|
||||
|
||||
### Current gate boundary
|
||||
|
||||
`ProjectConfig.Repository.validationCommands` describes repository validation
|
||||
commands. The legacy baseline did not expose a complete project-level and
|
||||
per-Work gate-result catalog; QualityGates now supplies that contract in SQLite. Completion enforces mechanical protocol checks,
|
||||
recorded results and owned evidence; it does not itself execute those commands.
|
||||
|
||||
TSK-0007 adds the project gate baseline and Work additions while preserving this
|
||||
execution boundary. A historical COMPLETED label or an ART reference is not proof
|
||||
that a newly introduced gate was executed. Imported approvals retain their original
|
||||
meaning; new gate results must record actual observations of the applicable state.
|
||||
|
||||
## Hashes and historical representations
|
||||
|
||||
There are several distinct digests, with different source material:
|
||||
|
||||
1. **Revision chain:** `Revisions.chain` hashes the preceding file's exact UTF-8
|
||||
content. Parsing and reserializing YAML can change bytes without changing the
|
||||
domain object. Keep the original source representation/provenance available
|
||||
for legacy chain checks; never replace a historical hash with a new one merely
|
||||
to make import pass. Retained migration originals stay outside database TEXT.
|
||||
2. **Work completion scope:** `VerificationService.scopeHash` hashes deterministic
|
||||
JSON of selected domain fields and ordered child records. Optional legacy
|
||||
fields are conditionally omitted. Do not normalize missing guidance to a new
|
||||
choice, add optional empty collections to old digest inputs, or reorder lists.
|
||||
3. **Plan/EPIC receipt sources:** source Plan revisions and child completions bind
|
||||
to their semantic digests and producer/authority metadata. Importing a receipt
|
||||
does not authorize re-completion, reevaluation or a new human approval.
|
||||
4. **Artifact integrity:** SHA-256 is over exact payload bytes; retain size/path
|
||||
ownership checks and the distinction between a user file and a protocol receipt.
|
||||
5. **Adapter and import fingerprints:** preserve source fingerprints, request IDs
|
||||
and import source identities. An identical retry is not a new Work or RUN;
|
||||
changed input with the same identity requires existing rejection/review rules.
|
||||
|
||||
Storage schema, manifest schema, protocol contract and Markdown document versions
|
||||
are separate. Existing record schema is 1, Work sequence reads versions 1/2,
|
||||
narrative Markdown reads document versions 1/2 and protocol contracts read 1/2/3.
|
||||
A new SQLite schema does not mean historical documents were rewritten.
|
||||
|
||||
## Unit-of-work and file lifecycle map
|
||||
|
||||
| Operation | Records that must publish coherently | External boundary |
|
||||
|---|---|---|
|
||||
| Create Work | Reserved high-water and initial identity/guidance | Bootstrap and legacy source discovery; no ID reuse on retry |
|
||||
| Add discussion/answer | Entry or revised survey, source links and Work references/timestamp | No implicit evidence attachment or human answer |
|
||||
| Accept/revise/supersede DEC | Approval and revision, replacement links and affected references | Preserve immutable accepted content and causal authority |
|
||||
| Create/update Plan or finish step | Eligible decision promotion, Plan revision, step/result/evidence references | Evidence must be available and valid during dependent checks |
|
||||
| Apply agent proposal | RUN state, typed proposals/applied references and resulting records | Provider call stays outside a write lock; recheck source state before application; preserve idempotent retry |
|
||||
| Complete Plan/Work or coordinate EPIC | Source revisions, internal receipt, completion and applicable propagation | No automatic completion from an empty set; retain reopen/authorization rules |
|
||||
| Retire temporary evidence | Completed dependent checks, minimal result and legitimate disposal state | File deletion follows committed result/disposal intent; interruption is recoverable; requested outputs are protected |
|
||||
| Migrate file backend | Imported rows, mapping/provenance and activation state | Stable source snapshot, migration safety copy and staged database; never switch before verification |
|
||||
|
||||
Keep local write transactions short; provider calls and external quality commands
|
||||
must not hold the database write lock. A read of related context uses one coherent
|
||||
view. Waits have a duration limit and an actionable diagnostic.
|
||||
|
||||
File publication and removal are not SQLite transactions. Define interruption
|
||||
cases explicitly: unreferenced staged file; committed reference with missing input;
|
||||
committed checked result pending cleanup; process interrupted before completion.
|
||||
Only the third case is eligible for post-check disposal. Removing one evidence
|
||||
file must consider every dependent check, including other Plans or Work completion.
|
||||
|
||||
## Representative corpus and expected outcomes
|
||||
|
||||
Use the existing resource bytes and workflow builders. All mutations below are
|
||||
against temporary copies/projects. Do not regenerate frozen resources with the new
|
||||
writer to obtain expected values.
|
||||
|
||||
| Corpus/case | Existing source | Required result of future migration/SQLite checks |
|
||||
|---|---|---|
|
||||
| Frozen pre-contract delivered Work | `src/test/resources/compatibility/baseline-v1/.ai-engineering`; `CompatibilityTest` | Keep 9 original files unchanged, implicit contract 1 and sequence schema 1 readable, accepted DEC plus draft history, legacy defaults and exact frozen scope hash. SQLite import yields equivalent meaning without rewriting or reopening the source. |
|
||||
| Missing optional refinement/guidance | `CompatibilityTest`, `RefinementSafetyTest`, `WorkGuidanceTest` | Interpret defaults in memory; no invented mode, waiver, answer or approval. New guided Works still require human choices. |
|
||||
| Current refinement/history | `DiscussionRefinementTest`, `RefinementSafetyTest`, `DiscussionMarkdownTest` | Preserve UTF-8/body text, response links, implicit/formal topics, all survey answers and latest-answer semantics, reversible dispositions. |
|
||||
| DEC and Plan authority | `WorkGuidanceTest`, `PlanDecisionPromotionTest`, `OperationalSafetyTest` | Preserve direct versus system approvals, exact causal links, accepted-content immutability, revised decision blocking and Plan authority. |
|
||||
| Plan consolidation/recovery | `PlanConsolidationTest`, `PlanConsolidationSafetyTest` | Preserve actual completed Plan sources, exclusions, incomplete scopes, existing receipt reuse, reopen semantics and pending questions. Tampered evidence fails before the step write. |
|
||||
| EPIC delegation/history | `EpicWorkflowTest`, `EpicSafetyTest` | Keep important/optional children, authorization invalidation, nested forest and historical hashes; reproduce recovery without duplicating completions. |
|
||||
| Import receipts and colliding source-local IDs | `src/test/resources/discussion-import/alpha`, `beta`; `DiscussionImportTest`, `legacyimport/DiscussionImportRecoveryTest` | Preserve stable source identity and original evidence; distinguish sources that reused DSC IDs; identical reimport/recovery does not duplicate Works or overwrite changed inputs. |
|
||||
| Fresh processes without Git | `ProcessContinuityTest`, `scripts/native-smoke.sh` | Reconstruct the same memory in a new process without Git installed; preserve source files and avoid a server dependency. |
|
||||
| Evidence missing/tampered before check | `IntegrityTest`, `PlanConsolidationSafetyTest` | Reject size/hash/path/ownership failures and do not publish successful checks. |
|
||||
| Explicitly retired temporary evidence | New scenario in TSK-0008/0009 | Check while present, persist minimal result, retire only after all consumers finish; historical queries remain valid; pending consumers prevent deletion. This behavior is not implemented in the current backend. |
|
||||
| Unsupported versions/unknown fields | `CompatibilityTest`, `OperationalSafetyTest` | Reject malformed, future or inconsistent records before activation; a current manifest cannot hide unsupported history; preview does not modify source. |
|
||||
| Traversal, symlink, foreign ownership | `IntegrityTest`, `RefinementSafetyTest`, `EpicSafetyTest` | Refuse unsafe paths/identities without reading a symlink target, leaking its contents or publishing partial records. Apply the same boundary to database and sidecar paths. |
|
||||
| Interrupted conversion/retry | New scenario in TSK-0010; existing import recovery pattern | Fail before activation, retain usable legacy state, expose recovery state and retry without duplicate IDs/approvals/completions. Two usable writers must not become independent authorities. |
|
||||
| Local concurrent writers/rollback | New scenario in TSK-0003 | Enforce ownership/foreign keys and whole-operation rollback; no duplicate allocated identity; bounded lock contention. Multi-machine reconciliation is out of scope. |
|
||||
|
||||
### Frozen anchors
|
||||
|
||||
The frozen baseline's expected completed Work scope hash is
|
||||
`72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02`.
|
||||
Its accepted DEC is revision 2; `previousHash` and the original draft's byte digest
|
||||
are `545dc8e36da222fdeaf9458f77880bf2d1842738b82bac5296cddf62452a7e01`.
|
||||
The ART-0001 payload digest is
|
||||
`98545564d0747210b91b933bf8554c4b7e36ba878e6662cb48156b08ff74e1ee`.
|
||||
These anchors were inspected from existing resources, not generated by SQLite.
|
||||
|
||||
## Mapping to implementation steps
|
||||
|
||||
- TSK-0002/0003 establish the driver, native loading, schema and unit of work.
|
||||
- TSK-0004/0005 map investigation and implementation records while retaining authority.
|
||||
- TSK-0006 maps RUNs, source fingerprints and deterministic coordination/receipts.
|
||||
- TSK-0007/0008 add gate records and temporary evidence lifecycle.
|
||||
- TSK-0009 builds projections without repeated unrelated reads.
|
||||
- TSK-0010 exercises the corpus before any activation and implements public migration.
|
||||
- TSK-0011 declares storage compatibility and initializes local ignored state.
|
||||
- TSK-0012 prepares the distribution with disposable installer fixtures only.
|
||||
- TSK-0013 updates public operational documentation once the commands exist.
|
||||
- TSK-0014 verifies the integrated result and hands a reproducible workload to WRK-000C.
|
||||
|
||||
This mapping does not change DEC authority, weaken a gate or authorize installation.
|
||||
Successful legacy tests characterize the source backend; they do not yet prove
|
||||
equivalence of a SQLite importer. Future steps must exercise these same expectations
|
||||
through the implemented database path.
|
||||
|
||||
## Driver and Native Image proof (TSK-0002)
|
||||
|
||||
The selected candidate is `org.xerial:sqlite-jdbc:3.54.1.0` (SQLite 3.54.1).
|
||||
`src/sqliteProbe` is a build-only entry point, separate from the installed CLI and
|
||||
project discovery. `sqliteProbe` exercises create/read/write/rollback/reopen in a
|
||||
JVM; `nativeSqliteProbeCompile` builds the same entry point with its JNI library
|
||||
exported beside the executable. The native binary explicitly selects a GraalVM
|
||||
Java 25 toolchain; selecting the Gradle JVM alone did not select the correct
|
||||
Native Image launcher in the first local build attempt.
|
||||
|
||||
Example disposable verification, using the repository's pinned GraalVM:
|
||||
|
||||
```sh
|
||||
mkdir -p build/sqlite-probe/disposable
|
||||
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
|
||||
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
|
||||
./gradlew nativeSqliteProbeCompile
|
||||
bash scripts/sqlite-probe.sh /absolute/path/to/build/native/nativeSqliteProbeCompile/aie-sqlite-probe
|
||||
```
|
||||
|
||||
The shell proof creates its own temporary database and starts separate native
|
||||
processes, checks a UTF-8 value and rollback, disables temporary-library extraction
|
||||
and verifies that an isolated executable fails when its companion library is absent.
|
||||
These are build/driver checks; they do not install the native application, activate
|
||||
the database backend or establish the end-to-end latency of the AIE CLI.
|
||||
|
||||
## Transaction foundation (TSK-0003)
|
||||
|
||||
`SqliteDatabase` now provides explicit initialization and command-scoped read/write
|
||||
transactions. Opening a missing database does not create files. Its application ID,
|
||||
`user_version` and schema metadata must agree before domain operations proceed.
|
||||
Initialization uses WAL with FULL synchronization; connection foreign keys are
|
||||
enabled explicitly, and writer transactions begin IMMEDIATE with a bounded busy
|
||||
timeout (2 seconds by default).
|
||||
|
||||
Nested operations share their connection. A nested failure makes the enclosing
|
||||
write rollback-only even if its caller catches the exception. Read transactions
|
||||
use a read-only SQLite connection and cannot be upgraded implicitly to writes.
|
||||
Related reads retain a stable snapshot while another local writer commits.
|
||||
|
||||
`sqlite/schema-v1.sql` establishes the ownership/revision/reference keys and local
|
||||
identity high-water marks. Domain field tables will be integrated in TSK-0004
|
||||
through TSK-0007; the foundation does not yet route the CLI's Works to SQLite.
|
||||
References are deferred until commit so related revisions can publish together.
|
||||
Missing target ownership aborts the transaction. Database and sidecar symlinks,
|
||||
nonregular paths and orphan sidecars during initialization require inspection.
|
||||
|
||||
`SqliteDatabaseTest` covers initialization, path encoding, rollback, foreign keys,
|
||||
nested failures, read-only access, snapshot consistency, writer contention,
|
||||
unsupported schemas and filesystem boundaries. The build-only native probe also
|
||||
creates and reopens the foundation schema, verifying its resource loading and
|
||||
transaction entry points in Native Image without installing the application.
|
||||
|
||||
## Investigation record integration (TSK-0004)
|
||||
|
||||
`ProjectService.initializeSqlite` is the explicit backend entry point used by
|
||||
disposable integration projects. The public `init` default is still the legacy
|
||||
backend until the storage-contract/initialization step. Existing projects are not
|
||||
converted by the presence of an arbitrary database file: the bootstrap configuration
|
||||
must explicitly select SQLite.
|
||||
|
||||
`SqliteRecords` maps record scalar fields to typed columns in domain-specific
|
||||
tables. Ordered fields use dependent tables and ordinals; structured operational
|
||||
items (such as an answer or completion) have an explicit JSON representation per
|
||||
item, not a serialized source document or entire Work. Work-owned references also
|
||||
bind to the shared revision identity keys. Tables/columns come from trusted domain
|
||||
record definitions, while identities and values use bound SQL parameters.
|
||||
|
||||
`RecordStorage` adapts the existing record codec and revision operations without
|
||||
placing canonical Markdown files in SQLite projects. New revision hashes bind to
|
||||
deterministic materializations of the typed record; migration can retain original
|
||||
source paths/digests for legacy representations. `WorkService` loads a selected
|
||||
Work by identity, allocates IDs transactionally and preserves its folder location
|
||||
when the title changes. Discussions, topic revisions, survey/answer history and
|
||||
dispositions use the same transaction as their Work references.
|
||||
|
||||
Integration checks cover rejected publication rollback, missing owned references,
|
||||
concurrent local allocation, selecting one Work without parsing an unrelated broken
|
||||
record, UTF-8 and explicit guidance/decision requests. A fresh JVM reconstructs
|
||||
discussion/survey context, and the native probe creates and reopens a Work and its
|
||||
discussion in separate processes using the application's AOT metadata. These checks
|
||||
do not yet migrate DECs, Plans or the active workspace to the new backend.
|
||||
|
||||
## Decision and Plan integration (TSK-0005)
|
||||
|
||||
Decisions, approvals, supersession and Plan/experiment revisions now use the typed
|
||||
record adapter. SQLite Plan creation publishes permitted draft promotions, the
|
||||
Plan and its Work reference in one transaction. The legacy backend retains its
|
||||
file-publication recovery path; SQL publication does not compensate by writing
|
||||
Markdown files. A requested rollback of a prepared SQL promotion marks the whole
|
||||
unit of work rollback-only.
|
||||
|
||||
The existing domain checks still enforce pending discussion, approval policy,
|
||||
accepted decision references, step dependencies, experiment outcomes and required
|
||||
owned evidence. Artifact metadata is mapped into SQLite as foundational support
|
||||
for these checks; payloads remain files and are still retained at this step. The
|
||||
temporary-artifact lifecycle and disposal policy belong to TSK-0008.
|
||||
|
||||
`SqliteImplementationTest` covers human acceptance and immutability, atomic system
|
||||
promotion rollback/retry under an explicit fixture waiver, supersession and Plan
|
||||
reconsideration, dependencies, owned evidence and the OODA experiment/retry loop.
|
||||
Existing file-backend authority, promotion and experiment tests remain applicable.
|
||||
### TSK-0006 — RUNs e coordenação
|
||||
|
||||
RUNs e políticas de EPIC usam registros tipados no SQLite. Idempotência e
|
||||
fingerprints continuam derivados do contexto; a aplicação de propostas é uma
|
||||
transação. Uma falha reverte todo o bundle e publica, em transação posterior,
|
||||
somente o RUN falho com diagnóstico e referências aplicadas vazias. Não há
|
||||
transporte bruto ou logs no banco. A coordenação conserva os recibos existentes
|
||||
até a integração de seu ciclo de vida no TSK-0008.
|
||||
|
||||
Verificação: 30 cenários distintos de SqliteCoordinationTest, EpicWorkflowTest,
|
||||
EpicSafetyTest, RefinementSafetyTest e ArchitectureTest passaram, incluindo
|
||||
idempotência, falha intermediária via trigger SQL, RESULTS/DECOMPOSITION,
|
||||
aprovação explícita, revisão de política, propagação e reabertura.
|
||||
|
||||
### TSK-0007 — gates obrigatórios
|
||||
|
||||
Definições de gates do projeto e adicionais por Work são cumulativas. Cada gate
|
||||
declara procedimento e caminhos avaliados; não executa comandos. O registro exige
|
||||
atestado de observação, fingerprint prévio, resultado, invocação e resumo curto.
|
||||
Arquivos, escopo/guidance do Work e revisões das DECs compõem o fingerprint;
|
||||
mudanças relevantes ou na definição exigem nova avaliação. Bookkeeping do Plan
|
||||
não invalida um resultado. Anexos obrigatórios passam pela integridade existente.
|
||||
|
||||
Conclusões humanas, por Plans e por EPICs verificam os gates e congelam referências
|
||||
e hashes dos resultados entregues na mesma transação. A consulta histórica não
|
||||
reaplica regras configuradas depois da entrega. Testes focados de gates,
|
||||
coordenação, infraestrutura e arquitetura: 23 cenários passaram. Instalação e
|
||||
workspace canônico permanecem no formato legado.
|
||||
|
||||
### TSK-0008 — anexos temporários e recuperação
|
||||
|
||||
O Work aberto conserva seus anexos porque outros checks ainda podem precisar
|
||||
deles. A conclusão valida os anexos e registra DISCARD_PENDING na transação;
|
||||
somente após commit remove os payloads e reconhece DISCARDED. Interrupções entre
|
||||
essas fases são repetíveis por `artifact recover WRK`. Ausência sem validação
|
||||
prévia continua inválida. Novas avaliações exigem entradas disponíveis, inclusive
|
||||
após reabrir um Work; o histórico usa o resultado mínimo persistido.
|
||||
|
||||
Recibos de Plans/EPICs novos são fatos tipados, sem arquivos JSON. As origens
|
||||
legadas de importação permanecem preservadas, assim como futuras cópias de
|
||||
migração. Publicações temporárias usam um pequeno journal operacional, removido
|
||||
após commit/rollback; recuperação distingue órfão próprio de payload já publicado.
|
||||
Rollback de preparação remove diretórios vazios próprios e preserva resíduos
|
||||
desconhecidos. Outputs solicitados fora do estado AIE não são alvos da limpeza.
|
||||
|
||||
EXP-0002: 32 cenários distintos focados passaram em duas rodadas. Cobertura inclui
|
||||
arquivo perdido antes de check, recusa de reuso após descarte, rollback da
|
||||
conclusão, interrupção após commit e após unlink, publicação interrompida,
|
||||
repetição, preservação de output e originais legados, recibos e coordenação.
|
||||
|
||||
### TSK-0009 — consultas e diagnóstico
|
||||
|
||||
Contexto, status, next-actions e validação usam snapshots SQLite para leituras
|
||||
relacionadas. Parent/links de EPIC têm índice relacional com unicidade de pai e
|
||||
FKs. Consultar um Work selecionado não carrega outros Works por conveniência:
|
||||
um registro alheio inválido não bloqueia seu contexto. Validação global continua
|
||||
inspecionando o projeto, contador, grafo, FK e integridade SQLite.
|
||||
|
||||
Compatibilidade inspeciona registros tipados e revisões no banco, sem procurar
|
||||
Markdown inexistente nem converter arquivos. Contexto expõe gates e disponibilidade
|
||||
dos anexos. Next-actions sinaliza descarte interrompido sem fazê-lo durante leitura.
|
||||
15 testes focados passaram, incluindo contexto em JVM separado, snapshot com outro
|
||||
escritor, isolamento de Work inválido, histórico com formato não suportado e leitura
|
||||
sem limpeza. A regressão legada de compatibilidade também passou na rodada anterior.
|
||||
|
||||
### TSK-0010 — migração explícita
|
||||
|
||||
`storage migrate` apresenta prévia sem escrita; `--apply --expect HASH` prepara
|
||||
uma base separada, importa registros tipados e compara DTOs, revisões, autoridade
|
||||
e integridade antes de selecionar SQLite. `--recover` e `--rollback` usam o
|
||||
fingerprint da operação. A cópia de segurança conserva originais e fontes exatas
|
||||
dos hashes; o staging é removido após êxito. Os arquivos legados existentes
|
||||
permanecem em seus destinos, sem alteração ou remoção de arquivos rastreados.
|
||||
|
||||
Contrato 4 e um marcador visível em `works/` impedem escrita por CLI antiga,
|
||||
inclusive comandos que já aguardavam o lock. Escritores modernos compartilham
|
||||
uma fronteira de publicação com espera limitada e recusam mudança de backend
|
||||
durante a espera. Leituras não precisam desse lock. A recuperação recusa ativação
|
||||
se o legado mudou; rollback preserva essas alterações e exige nova prévia. Depois
|
||||
de novas gravações SQLite, rollback é recusado para não perder memória.
|
||||
|
||||
A prova encontrou e corrigiu a distinção entre lista nula e vazia (especialmente
|
||||
exclusions de Plan). Essa presença é tipada no esquema e os hashes originais
|
||||
continuam ancorados em bytes externos, com comparação contra o registro tipado.
|
||||
EXP-0003: 34 testes na rodada final passaram, incluindo cinco pontos de falha,
|
||||
corpus congelado, Plan/survey ativo, EPIC/RUN, IDs reservados e compatibilidade.
|
||||
Nenhum consumidor nem este workspace foi migrado.
|
||||
|
||||
### TSK-0011 — inicialização local
|
||||
|
||||
`init` prepara SQLite e bootstrap antes de publicar o workspace. Acrescenta
|
||||
`/.ai-engineering/` ao .gitignore sem exigir Git, preservando instruções externas
|
||||
e regras anteriores. `--version-state` deixa essa política ao desenvolvedor;
|
||||
`--storage legacy` é explícito para compatibilidade. Nenhum comando remove arquivos
|
||||
rastreados ou converte projetos existentes durante onboard/leitura.
|
||||
|
||||
Bootstrap SQLite exige contrato 4 antes de acessar a base; esquemas/contratos
|
||||
incompatíveis são diagnosticados. As instruções distribuídas exigem CLI compatível
|
||||
para ler SQLite e proíbem interpretar memória ilegível como projeto vazio. Testes
|
||||
de continuidade passaram em seis cenários JVM separados, inclusive sem Git no PATH.
|
||||
A rodada consolidada de init, migração, compatibilidade, protocolo e arquitetura
|
||||
também passou após explicitar o backend das fixtures legadas.
|
||||
|
||||
### TSK-0012 — pacote preparado, instalação adiada
|
||||
|
||||
`nativePackage` reúne AIE nativo, bibliotecas companheiras e CLI sqlite3 em
|
||||
`build/native/package`; distribuições usam esse diretório completo. SQLite 3.54.1
|
||||
é compilado de fonte oficial com SHA3-256 fixado em scripts/sqlite-version.json.
|
||||
O verificador confere componentes/hashes/versões, inicializa um projeto descartável
|
||||
com AIE nativo e lê sua base com o sqlite3 do pacote.
|
||||
|
||||
O instalador preparado aceita bin-dir/lib-dir, verifica uma release completa antes
|
||||
de alternar current e publicar atalhos aie/ai-engineering/aie-sqlite3. Uma falha na
|
||||
troca dos atalhos restaura a release e os atalhos anteriores. 17 testes com
|
||||
ferramentas simuladas passaram, inclusive falha parcial de ativação. O pacote real
|
||||
de build foi verificado em macOS arm64; Linux está coberto pelas fixtures de
|
||||
instalação, sem prova nativa física nesta máquina.
|
||||
|
||||
Nenhuma instalação real foi executada: binários/bibliotecas/atalhos ativos e
|
||||
projetos consumidores permanecem intactos.
|
||||
|
||||
### TSK-0013 — contrato documentado
|
||||
|
||||
README, arquitetura, protocolo, compatibilidade e recursos de entrada agora
|
||||
descrevem memória local SQLite, gates e anexos temporários. O procedimento público
|
||||
está em docs/storage-migration.md. A referência detalhada do backend de arquivos
|
||||
foi mantida separadamente como legado explícito. Os dois ciclos, OODA e autoridade
|
||||
humana permanecem; instalação/migração reais continuam adiadas. Links locais foram
|
||||
verificados e os testes de init, compatibilidade e Work guidance passaram.
|
||||
|
||||
### TSK-0014 — regressão integrada e handoff
|
||||
|
||||
`./gradlew check` passou com 230 testes JVM, zero falhas/erros/skips, além dos 11
|
||||
cenários do fixture Jenkins. O ajuste final do importador SQLite passou em rodada
|
||||
focada de 17 testes (importação/recuperação e arquitetura). As 17 fixtures finais do
|
||||
instalador passaram com ferramentas simuladas; nenhuma instalação real ocorreu.
|
||||
|
||||
O pacote final e arquivos ZIP/TAR foram gerados com GraalVM e tiveram componentes,
|
||||
hashes, versões e permissões verificados. O smoke nativo completo passou, incluindo
|
||||
legado, continuidade, guidance/OODA e os novos cenários SQLite de gate pendente,
|
||||
conclusão, descarte, recusa de reuso e migração do corpus congelado. O diagnóstico de
|
||||
processos do macOS exigiu execução fora do sandbox; a repetição autorizada passou.
|
||||
Uma cópia isolada do pacote abriu SQLite com extração temporária sem escrita; uma
|
||||
cópia sem a biblioteca JDBC foi corretamente recusada.
|
||||
|
||||
O gerador de latência foi verificado com um Work/uma nota sintéticos, sem medição.
|
||||
docs/latency-scenario.md e scripts/latency-fixture.py foram encaminhados por Discussion
|
||||
ao WRK-000C, que permanece OPEN. Adoção do banco não foi declarada prova de melhora.
|
||||
A verificação física foi macOS arm64; Linux/Windows permanecem dependentes da matriz
|
||||
CI para confirmação nativa. Instalação ativa, workspace canônico e consumidores
|
||||
continuam no estado anterior, sem migração real.
|
||||
@@ -0,0 +1,72 @@
|
||||
# SQLite migration and recovery
|
||||
|
||||
Installation and migration are separate operations. Building/installing a CLI does
|
||||
not convert a project. Keep the installed version used by ongoing projects until
|
||||
choosing to activate a compatible release. This implementation was tested on
|
||||
fixtures only; its canonical workspace and consumers were not migrated.
|
||||
|
||||
## Preview and apply
|
||||
|
||||
Use a CLI that advertises protocol contract 4. In the chosen legacy project:
|
||||
|
||||
```sh
|
||||
aie project compatibility --format json
|
||||
aie project validate --format json
|
||||
aie storage migrate --format json
|
||||
```
|
||||
|
||||
Preview reads supported canonical records, histories, evidence and bootstrap. It
|
||||
returns validity, Work count and a fingerprint. It writes no lock, backup or database.
|
||||
Repair invalid input first. Preserve original scope/authority; do not reopen completed
|
||||
Works to normalize them. This route does not accept unknown future schemas.
|
||||
|
||||
After reviewing the preview:
|
||||
|
||||
```sh
|
||||
aie storage migrate --apply --expect <fingerprint> --format json
|
||||
```
|
||||
|
||||
Application takes the publication lock, verifies the current fingerprint, makes a
|
||||
safety copy under `.ai-engineering/.local/sqlite-migration/<operation>/original`,
|
||||
and imports into a separate staging database. It compares typed values/revisions,
|
||||
references, approvals, reserved IDs, hashes and completion provenance. Original
|
||||
file bytes remain external for historical chain verification; they are not BLOBs
|
||||
or file-shaped TEXT in SQLite.
|
||||
|
||||
Only after validation does activation publish the protected contract, database and
|
||||
storage selection. A visible `works/SQLITE-STORAGE` marker also stops legacy readers
|
||||
that had already passed an old contract check. Existing Work documents stay
|
||||
byte-identical as retained non-authoritative originals; future writes use SQLite.
|
||||
No tracked file is automatically untracked or removed, and existing Git ignore policy
|
||||
is preserved. New projects use `init` with state ignored by default.
|
||||
|
||||
Success reports APPLIED and the safety-copy path. Staging is removed. Repeating the
|
||||
same application is idempotent. Keep the safety originals: historical revision hashes
|
||||
may depend on them. They are not a general backup/export feature.
|
||||
|
||||
## Interrupted operation
|
||||
|
||||
Ordinary CLI access reports the pending migration rather than reading mixed storage.
|
||||
Inspect its public preview/report, then choose:
|
||||
|
||||
```sh
|
||||
aie storage migrate --recover --expect <operation-fingerprint>
|
||||
# Or explicitly return to the recoverable legacy source:
|
||||
aie storage migrate --rollback --expect <operation-fingerprint>
|
||||
```
|
||||
|
||||
Recovery verifies source/safety/prepared data and resumes without duplicate records.
|
||||
If a legacy writer changed input before activation, recovery refuses stale data;
|
||||
rollback preserves those legacy edits, then a new preview captures them.
|
||||
|
||||
Rollback restores only bootstrap files changed by this operation and removes its
|
||||
unchanged published database/guard. It retains the safety copy. Unrelated bootstrap
|
||||
edits require deliberate review. Once SQLite has received new engineering writes,
|
||||
rollback refuses to discard that memory; keep SQLite and inspect the diagnostic.
|
||||
Never delete the database or journal to force a fresh-looking project.
|
||||
|
||||
A migration does not retroactively discard legacy evidence, add approvals or claim
|
||||
new quality gates passed. New temporary inputs and gate results follow the current
|
||||
[retention contract](protocol.md#temporary-inputs-and-outputs). Work/DEC sharing,
|
||||
import/export, distributed reconciliation and backup as a product feature remain
|
||||
outside this version.
|
||||
Reference in New Issue
Block a user