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