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.
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user