feat: import open Discussion Framework agendas into Works
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s

Add deterministic preview and fingerprint-bound application for independent
DF sources under an AIE umbrella. Preserve complete agendas and original
evidence with source-scoped identities, validated receipts and safe retries.

Publish prepared Works atomically, require review for changed imports and
retain existing refinement without source edits or model calls.

Advertise protocol contract 2 while continuing to read contract-1 projects. Add JVM,
concurrency, recovery and native coverage; document usage and complete
WRK-0007 with verification evidence.
This commit is contained in:
Nilton Constantino
2026-11-16 14:53:05 +00:00
parent 3d2abb487f
commit 8e75bf7516
74 changed files with 3663 additions and 78 deletions
+16 -5
View File
@@ -45,6 +45,7 @@ its explicit public API; implementation-only Git adapters live in `project.inter
| discussion | Entries, topics, surveys, answer history and proposal dispositions | work, project, artifact, filesystem |
| decision | Draft, approval, revision and supersession records | work, filesystem |
| planning | Lightweight plans, dependencies, step results and revision history | work, decision, 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 |
@@ -261,8 +262,18 @@ No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic hou
deletion or Lesson model was retained. Work is the project-scoped aggregate; Discussion
is refinement within a Work. Source repositories were not changed.
There is no automated legacy importer. Migration is deferred until the operational
replacement is established. A future importer should create
one Work per coherent agenda, retain original discussion/decision text with origin
references, and verify identifiers and links before publication. Legacy Lessons should
be reviewed for integration into canonical docs, not recreated as a required entity.
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.
+7
View File
@@ -48,6 +48,13 @@ for either. Unsupported declared manifest/contract versions prevent ordinary CLI
operations and onboarding from overwriting a newer contract. Compatibility inspection
remains available to explain the mismatch.
Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts
1 and 2, 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`
refreshes the entry files with backups; completed Works and history are unchanged.
The format catalog is deliberately small:
| Format | Current writer | Supported readers |
+94
View File
@@ -0,0 +1,94 @@
# Discussion Framework import
Import DSC discussions with open AGD agendas into the current AIE project. Each
source is an independent DF tree; the destination may be a plain project or an
umbrella containing several such projects. No model, source mutation, repository
registration, imported decision or imported execution plan is involved.
## Commands
This capability is advertised by protocol contract 2. The updated CLI also reads
contract 1 projects and historical Work formats; no Work conversion is required.
`onboard` refreshes entry instructions with backups after compatibility inspection.
Older contract-1 CLIs refuse a contract-2 manifest instead of overwriting it.
```sh
aie import discussion --source runtime=../runtime --source studio=../studio \
--target runtime=runtime --target runtime=docs --target studio=studio --format json
aie import discussion --source runtime=../runtime --source studio=../studio \
--target runtime=runtime --target runtime=docs --target studio=studio \
--apply --expect <preview-fingerprint> --author owner --format json
```
`--source ID=PATH` is repeatable and required. IDs follow AIE project identifier
rules and must remain stable across imports; paths resolve relative to the caller,
including when `--project` selects a different destination. A path may name the
source project or its existing `discussion/` directory. Duplicate IDs or roots in
one request are rejected. Source locations may move while keeping their identity.
`--target SOURCE=TEXT` is repeatable. Targets are authored descriptions recorded
in the imported Work; they do not register or authorize repository edits. Without
an explicit target, the caller-supplied source ID identifies the project target.
Without `--apply`, the command is read-only, including no destination locks or
backups. It reports each DSC, selected/ignored agendas, source paths and hashes,
existing Work, and an action: CREATE, UNCHANGED, REVIEW or SKIP. Invalid inputs
are diagnosed in the report. REVIEW and errors block the selected batch.
`--apply` requires `--expect` from a valid preview. The sources and destination
import identities are read again under the destination lock; a changed preview
fingerprint is refused before allocation or publication. Publication rechecks the
captured source bytes before writing any Works. There is no automatic override
of REVIEW items; refine the inputs or review the existing Work explicitly.
## Selection and preservation
Read `discussion/index.ndjson`: first record `type=meta`, subsequent records
`type=discussion`. Select each DSC with at least one indexed AGD whose exact
status is `open`. Other nonblank states are ignored with a reason. The DSC's
aggregate status is not a substitute for the agenda status. An absent DEC is
normal. Historical closed agendas need not have files when they are not selected.
Selected agenda files must have front matter whose ID and status agree with the
index. Missing/ambiguous references, duplicate DSC/AGD identities in one source,
invalid UTF-8, escaping paths, symlinked descendants or inconsistent selected data
block application. Unknown source metadata is retained in the original DSC record,
not inferred into new AIE semantics. The DF validator alone is not sufficient.
One OPEN Work is created per source ID + DSC ID. Each selected AGD becomes a NOTE
in refinement with its complete original Markdown text, not a summary or parsed
set of human answers. Original agenda bytes and the original DSC index record
are owned ART evidence. A versioned import receipt, also owned evidence, links
source identity, DSC and AGD IDs, source hashes, targets, discussion IDs and ART IDs.
The source directory is an audit location, not the sole import identity.
Limits: an index is at most 8 MiB, individual selected agendas and evidence are at
most 1 MiB, and captured source data per request is at most 32 MiB. Oversized data
is reported before publication. These are explicit limits, never truncation.
## Reimport and failure recovery
The same source ID + DSC with identical content and targets is UNCHANGED. It does
not add or rewrite Works, notes or evidence, including when the Work has since
been refined, completed or archived. New or changed source content for an existing
identity is REVIEW. No destination content is overwritten or deleted; a changed
agenda state never removes previously imported context.
A Work and all its initial records are built in the existing hidden Work staging
area and published by one directory move using the normal Work ID sequence.
Readers do not see a half-seeded Work. A batch is not a global transaction:
an I/O failure or process interruption after one Work is published may leave that
Work imported. The error identifies published Works; a fresh preview recognizes
them as UNCHANGED and can continue the remaining items without duplication.
Unpublished hidden staging folders and reserved ID gaps may remain for deliberate
inspection; neither is interpreted as an imported discussion.
Preview, apply and validation verify owned receipt integrity and references.
Refinement prose may evolve in the destination while the original evidence remains
intact. Conflicting import identities or corrupted receipts must be repaired
explicitly; no receipt, original evidence or historical Work is silently rewritten.
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.
+9 -1
View File
@@ -436,7 +436,15 @@ Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is req
`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work
archived. It retains all files and prior approvals/results. `work reopen` clears
archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion.
Importing legacy agendas and Lessons is deferred to a later, separately tested importer.
`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
+7 -4
View File
@@ -56,9 +56,11 @@ The test suite verifies mechanics, not an arbitrary external AI's compliance.
Continue piloting the installed entry files and CLI in an existing real project,
with an external agent continuing a Work through human-reviewed closure. The first
Discussion refinement slice is described below. A separate future importer must
preserve origins/history for open agendas and valuable legacy Lessons, integrating
knowledge into canonical docs instead of requiring Lesson artifacts.
Discussion refinement slice is described below. The separate DF importer now
previews and imports DSCs with open agendas, preserving originals, source identity
and targets across independent projects under an umbrella. Reimport is deterministic
and does not overwrite refinement. See [the import contract](discussion-import.md).
Legacy Lessons still require deliberate integration into canonical docs.
## Milestone 2 — Discussion refinement (first contract slice)
@@ -93,7 +95,8 @@ important/optional/cancelled children and native standalone execution. Actual ob
results are recorded in [experiments](experiments.md).
The EPIC slice itself does not choose providers or execute child repository changes.
Agent-generated decomposition and the agenda/Lesson importer remain separate work.
Agent-generated decomposition and Lesson integration remain separate work. The
open-agenda importer is delivered independently of EPIC coordination.
## Local Codex/Claude adapters — third approved slice