Files
ai-engineering/docs/discussion-slice.md
bquarkz a8a8faf5d8 feat: add agent coordination and automatic work completion
Add portable topics and surveys, decision approval history, execution plans, local Codex and Claude adapters, and general agent routing. Consolidate Plan and EPIC results through deterministic completion receipts, reviewed cancellation scope and recoverable reconciliation.

Track the completed WRK-0001 and WRK-0002 records, protocol documentation, source manifests and delivery evidence.

Validation: 117 tests including Modulith; GraalVM 25 native compilation, standalone smoke and ZIP/TAR verification on macOS ARM64; identical persisted context across JVM and native executions.
2026-11-14 01:12:21 +00:00

89 lines
5.3 KiB
Markdown

# Discussion refinement contract
Discussion remains the refinement space inside Work; DEC and Plan retain their
existing roles. There is no separate Idea entity or mandatory extra workflow stage.
## Records and compatibility
Topics (`TOP`), surveys (`SVY`), dispositions (`DSP`) and agent runs (`RUN`) have
Work-local decimal IDs. Work IDs remain hexadecimal. Work reference lists for these
records default to empty when absent. Reading legacy records never rewrites them.
Existing free-form discussionId threads remain valid and appear as implicit topics;
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.
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
from 1, optional recommended option, single/multiple selection and discussion sources.
An answer selects valid options and/or supplies nonblank free text. Recommendation
alone is never an answer. Revised answers explicitly supersede the preceding answer
to that question, keeping all versions; only the latest determines pending questions.
Revised answers are exposed for review and never rewrite accepted decisions/plans.
Dispositions archive/restore a proposal in Discussion, with actor, reason and source
entry. Archive requires owned, integrity-checked ART evidence and project policy
`reversible`; the default is `review-only`. It preserves the source and can be undone.
Questions/responses are resolved through their own contracts, not hidden by archive.
## Adapter contract
Project configuration optionally contains `agents`: general executor, per-activity
executors and archivePolicy. Executor fields identify adapter, profile and model.
The first general configuration is explicit; absent configuration leaves ordinary
CLI usage available and agent execution reports a missing configuration.
The first slice provides `fixture-general` and `fixture-reviewer`. They are deterministic
test adapters, not real semantic intelligence or provider integrations. Refinement
fixtures accept one idea per line, optionally prefixed `Topic: idea`. Activities are
refine, analyze and summarize; fixture classification uses explicit task markers.
The later [local CLI slice](cli-adapters.md) adds actual Codex/Claude proposals using
the same domain contract and optional invocation provenance.
Input includes immutable Work/project/context records, task, optional activity and
requester. Output is a typed proposal bundle: topics, surveys/questions, entries,
dispositions, optional DEC draft and summary. Output identifies fixture provenance
and sources. The adapter receives no persistence service, project Path or execution
tools. Framework validation checks ownership and all proposed references before
application. An invalid bundle has no side effects. Agent proposals cannot supply
survey answers, approve DECs, complete Works or execute source commands.
General is selected when an activity has no configured specialization. Explicit
activity overrides fixture classification. Canonical RUN records preserve requester,
selected executor, task, source fingerprint, proposals, applied references and result.
An optional request ID makes identical completed requests idempotent; reuse with a
different request is invalid. Interrupted/failed application remains diagnosable.
Fingerprints exclude run bookkeeping; summaries expose whether semantic sources
changed. State checks use framework code, never an adapter invocation.
## CLI surface
- `topic create/list/show/update WRK ...`
- `survey create/list/show/history WRK ...`
- `survey question WRK SVY --text ... --option ... [--topic ...]`
- `survey answer WRK SVY QST [--choice 1] [--text ...|--text-file ...]`
- `survey ask WRK SVY [--input-file ...]` for guided answering
- `discussion archive/restore WRK DSC --reason ... [--evidence ART]`
- `agent list`, `agent configure --adapter ... [--activity ...]`
- `agent run WRK --task ... [--activity ...] [--request-id ...]`
- `agent history/show WRK ...`
Inspection supports JSON. Context includes topics, surveys, dispositions and run
provenance, references actual evidence and remains deterministic. Structural
validation covers new references/history; mechanical readiness includes unanswered
survey questions and empty surveys. Interactive answering requires an actual console
or explicit input file; noninteractive commands never wait indefinitely for input.
## Acceptance experiment
In a temporary project, persist raw ideas and two topics, obtain a survey from the
first fake, answer/revise it, attach explicit fixture evidence, analyze and archive
a proposal reversibly, prepare a DEC draft, and resume from another process using
the second fake. Verify ownership, evidence, history, pending questions, stable
context, old-format reads, invalid bundles, paths and native execution without JVM.