Files
ai-engineering/docs/discussion-import.md
T
bquarkz 8f6cfa5d86 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

95 lines
5.5 KiB
Markdown

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