90 lines
5.3 KiB
Markdown
90 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.
|
|
|
|
SQLite stores these records and their revisions as typed data. Related publication
|
|
and Work references commit together. Legacy directories/Markdown and `.history`
|
|
remain supported on the explicit file backend; migration preserves original bytes.
|
|
SQLite RUN application rolls back the full proposal on failure, then records a short
|
|
failure diagnostic without reverted references. Legacy failed publication can retain
|
|
partial applied references for deliberate repair.
|
|
|
|
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.
|