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.
5.3 KiB
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 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 answeringdiscussion 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.