Files
ai-engineering/docs/discussion-import.md
T
Nilton Constantino 8e75bf7516
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
feat: import open Discussion Framework agendas into Works
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.
2026-11-16 14:53:05 +00:00

5.5 KiB

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.

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.