opencode-codeops 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.3.0 — 2026-10-29
+
+### Fixes
+
+- discovery: close the browser acceptance findings
+- discovery: guard the locked-group selection rule
+
+### Documentation
+
+- discovery: mark browser acceptance as the remaining gate
+- discovery: document the redesigned plan workspace
+- discovery-ui-redesign: add the preflighted implementation plan
+- discovery: add the agent protocol and skill adoption
+- discovery: record the host spike outcomes
+- discovery: add the plan set with preflight fixes applied
+
+### Features
+
+- discovery: complete the Fluent UI workspace
+- discovery: add guarded editing and the workspace shell
+- discovery: add workspace destinations and theme preference
+- discovery: finish the docs, live evidence, and UI fixes
+- discovery: add the Fluent UI app and packaging
+- discovery: wire the opt-in tools and waking
+- discovery: add the listener and HTTP API
+- discovery: add the store
+- discovery: add the rules and model module
+
+### Tests
+
+- discovery: add navigation and theme specification tests
+- discovery: isolate the fallback-port spec test
+
+### Chores
+
+- codeops: refresh the specialist check
+- project: refresh managed guidance
+
 ## 2.2.1 — 2026-10-10
 
 ### Fixes

package/README.md

@@ -162,6 +162,59 @@ when no run is active, when the host lacks the plugin APIs, or when every call f
 Markdown execution plan remains the single progress source of truth; the live view never gates
 execution.
 
+## Discovery
+
+Discovery is an opt-in local web page where the agent publishes a CodeOps question round
+instead of asking every question in chat. Questions, options, recommendations, and dependency
+rules render in the browser; answers are saved there, and Submit wakes the OpenCode session that
+published them so it can continue.
+
+### Plan workspace
+
+The plan workspace uses a persistent group navigation column and shows one selected group at a
+time. Groups carry ready, pending, and completed cues, and a selected group stays selected while
+you inspect a locked or completed group. The plan URL, group links
+(`#/p/<project>/<plan>/groups/<key>`), and the summary link
+(`#/p/<project>/<plan>/summary`) are stable and work with browser back and forward.
+
+The action bar always shows **Submit group** for the selected group. The **Decision summary**
+lists current answers, their statuses, and links back to each group; **Submit all ready groups**
+sends every ready group from one place. Readiness and completion are labelled separately.
+
+Save state is server-backed. **Saved** appears only after the server acknowledges the write;
+**Unsaved changes** and **Saving…** show pending work, and a failed save keeps the draft with
+**Retry**. Edits survive group changes and live refreshes. A draft that can no longer be saved —
+because the question became read-only, locked, retired, hidden, or its group was removed — stays
+visible under **Unsent drafts** and can be explicitly discarded or left after confirmation.
+
+The shared header carries a real breadcrumb and a **System / Light / Dark** theme control. System
+follows the operating-system setting; an explicit choice is remembered in the browser. If storage
+is unavailable, the choice still applies for the current tab.
+
+Enable it for a project with `analyze-project --with-discovery`, or add the setting to
+`codeops/codeops.json`:
+
+```json
+{
+  "discovery": { "enabled": true, "chatMaxQuestions": 3 }
+}
+```
+
+Rounds with at most `chatMaxQuestions` (default 3) questions stay in chat. The page is served
+from the plugin at `http://localhost:4747/`; set `CODEOPS_DISCOVERY_PORT` to listen on a
+different port. Discovery data lives in `$CODEOPS_DATA_DIR/discovery`, which defaults to
+`~/.local/share/opencode/codeops/discovery`.
+
+The listener binds to `127.0.0.1` only and has no login. It assumes a single-user machine: any
+local user can read the page and the stored answers. Browsers limit concurrent
+connections per host, so keep only a few plan tabs open at once. The agent continues only while
+OpenCode is running in that project; submissions that arrive while it is not are delivered when
+it starts again.
+
+Pass `--no-discovery` to a skill to skip the page for one run and use chat. Building from a
+checkout with `npm run build:discovery` refreshes the page assets without restarting OpenCode.
+Remote and SSH sessions are not supported.
+
 ## Agent model configuration
 
 All CodeOps subagents inherit the model of the primary agent that invoked them. No provider-specific configuration is required out of the box.

package/_shared/discovery.md

@@ -0,0 +1,92 @@
+# Discovery (optional answer surface)
+
+> **CodeOps Artifact Schema**: 1
+
+Discovery moves large question rounds out of the chat scroll and into a local
+browser page. It is opt-in per project and never replaces the Ambiguity
+Register. Use it only when this file's conditions hold; otherwise ask in chat
+exactly as before.
+
+## When it applies
+
+All three must hold:
+
+1. `codeops/codeops.json` sets `discovery.enabled: true`.
+2. The `codeops_discovery_publish`, `codeops_discovery_answers`, and
+   `codeops_discovery_resolve` tools are available.
+3. The run does not carry the `--no-discovery` token.
+
+If any condition fails, ask in chat. Never mention a page the user cannot use.
+
+## Round size
+
+A round with at most `discovery.chatMaxQuestions` questions (default 3) stays
+in chat. Larger rounds are published. The user can always ask to answer in
+chat instead; honor that for the rest of the run.
+
+## What never goes to the page
+
+The **Complexity Escalation Gate** always stays in chat: its visible STOP
+packet, the challenger verdict, and the approval decision. The page has no
+"accept all" control, so a question that would waive a gate must not be
+published.
+
+## Publishing
+
+- One Discovery plan per artifact: the `kind` (`plan`, `requirements`, or
+  `preflight`) plus the repository-relative `artifact` path. Republishing the
+  same pair creates the next revision.
+- Groups follow dependency order; a foundational group is listed in `dependsOn`
+  of the groups it unlocks.
+- Every question carries `why`, `evidence` (`file:line` where possible),
+  options with their trade-offs, and a `recommendation`. The recommendation is
+  shown and never pre-selected.
+- Use `showIf` and `implies` when one answer settles another question in the
+  same plan. No chains: an implied answer never implies a third.
+- Keys are stable: `DQ-<n>` for discovery, `PF-NNN` for preflight findings.
+  Never reuse a key for a different decision.
+- A question whose answer is already recorded may be republished unchanged.
+  Omitting an **open** question retires it; recorded, submitted, and
+  already-retired questions are kept (with a warning when the content changed).
+  Retire a submitted question through `codeops_discovery_resolve`. A follow-up
+  publish therefore resends every earlier question plus the new ones.
+
+## After publishing
+
+Send one chat line with the link (and the fallback-port notice when present).
+Then **end the turn** and **do not poll**. The user answers in the browser; the
+wake message continues the work. Under the no-waker fallback, call
+`codeops_discovery_answers` with `wait: true` after publishing.
+
+## Ownership
+
+On an `owned` result, ask the user in chat whether to take over. Publish with
+`takeover: true` only after an explicit yes. Never take over silently.
+
+## Reading and recording
+
+On the wake message, or when the user says they answered, call
+`codeops_discovery_answers`. Then:
+
+- Record each answer as exact text with its question key and its source.
+- Record an implied answer as "**implied by** <key>, shown and submitted".
+  Note when the user overrode an implication.
+- Record a Defer as a named deferral: decision · owner · revisit.
+- Leave "needs discussion" questions open; they are not decisions.
+- Call `codeops_discovery_resolve` with the register ids for the recorded
+  answers. The **Ambiguity Register stays the authoritative record**; the page
+  is only the collection surface.
+- Answers the user gives in chat for published questions are recorded and
+  resolved exactly the same way.
+
+## Follow-ups
+
+Republish the same artifact with **every earlier question plus the new ones**.
+A publish is the plan's full question set: omitting an open question retires
+it, while submitted and recorded questions are kept until they are recorded. Use `proposal` for
+settlements the agent infers; the user confirms or reopens them on the page.
+
+## Unavailable
+
+On `disabled` or `unavailable`, say so in one line and ask in chat. **Never
+skip or weaken a gate** because the page is unavailable.

package/_shared/zero-ambiguity-gate.md

@@ -221,6 +221,10 @@ named larger machinery.
 save the register with header `✅ GATE PASSED — 0 ambiguities identified (systematic review
 completed)`. This proves the gate was executed.
 
+## Discovery (optional answer surface)
+
+When a workflow runs with Discovery enabled, the Ambiguity Register stays the **authoritative record** ([discovery.md](discovery.md)). Answers transcribed from the page are exact text with their question key; an implied answer counts as a user decision only when the page showed it and the user submitted it. Deferrals still need decision, owner, and revisit. Complexity escalations stay in **chat**: the STOP packet, the challenger verdict, and the approval are never published to the page.
+
 ## Deferral rules (named deferral only)
 
 A decision may be **explicitly deferred** — the status the whole pipeline shares (grill-me

package/bin/lib/discovery-rules.d.mts

@@ -0,0 +1,228 @@
+/**
+ * Type declarations for the CodeOps Discovery rules and model helper.
+ *
+ * The helper is plain JavaScript so the browser bundle and `node --test` can
+ * import the same file. These declarations give the TypeScript plugin entry
+ * point and the UI build typed access to it.
+ */
+
+/** Schema version written into every Discovery data file. */
+export declare const DISCOVERY_SCHEMA_VERSION: 1
+
+/** A question type. */
+export type QuestionType = "single" | "multiple" | "text" | "single-other"
+
+/** Every supported question type. */
+export declare const QUESTION_TYPES: readonly QuestionType[]
+
+/** Question types that carry options. */
+export declare const CHOICE_TYPES: readonly QuestionType[]
+
+/** A plan kind. */
+export type PlanKind = "plan" | "requirements" | "preflight"
+
+/** Every supported plan kind. */
+export declare const PLAN_KINDS: readonly PlanKind[]
+
+/** Pattern for question keys, group keys, and option ids. */
+export declare const KEY_PATTERN: RegExp
+
+/** Pattern for URL and file-name slugs. */
+export declare const SLUG_PATTERN: RegExp
+
+/** Maximum length of a title, group title, or option label. */
+export declare const TITLE_MAX: 200
+
+/** Maximum length of every other free-text value. */
+export declare const TEXT_MAX: 4000
+
+/** Maximum length of an artifact path. */
+export declare const ARTIFACT_MAX: 300
+
+/** Structural caps for one publish. */
+export declare const LIMITS: {
+  readonly groups: 50
+  readonly questions: 200
+  readonly optionsMin: 2
+  readonly optionsMax: 20
+  readonly evidence: 20
+}
+
+/** Question fields covered by the fingerprint. */
+export declare const FINGERPRINT_FIELDS: readonly string[]
+
+/** A stored answer; exactly one field is set. */
+export interface Answer {
+  choice?: string
+  choices?: string[]
+  text?: string
+  other?: string
+}
+
+/** A deferral recorded by the user. */
+export interface Defer {
+  decision: string
+  owner: string
+  revisit: string
+}
+
+/** A compact answer: an option id, option ids, or text. */
+export type CompactAnswer = string | string[]
+
+/** An implication attached to one option. */
+export interface Implication {
+  question: string
+  answer: CompactAnswer
+  reason: string
+}
+
+/** One question option. */
+export interface QuestionOption {
+  id: string
+  label: string
+  description?: string
+  implies?: Implication[]
+}
+
+/** One visibility condition. */
+export interface ShowIfCondition {
+  question: string
+  anyOf: string[]
+}
+
+/** An agent-proposed settlement. */
+export interface Proposal {
+  answer: CompactAnswer
+  reason: string
+}
+
+/** One normalized published question. */
+export interface Question {
+  key: string
+  group: string
+  type: QuestionType
+  title: string
+  why?: string
+  evidence?: string[]
+  options?: QuestionOption[]
+  recommendation?: string | string[]
+  showIf?: ShowIfCondition[]
+  proposal?: Proposal
+}
+
+/** One normalized published group. */
+export interface Group {
+  key: string
+  title: string
+  description?: string
+  dependsOn: string[]
+}
+
+/** A normalized published plan. */
+export interface PublishedPlan {
+  artifact: string
+  kind: PlanKind
+  title: string
+  groups: Group[]
+  questions: Question[]
+}
+
+/** The stored lifecycle of one question. */
+export type QuestionStatus = "open" | "submitted" | "recorded" | "retired"
+
+/** The mutable state of one question. */
+export interface QuestionState {
+  answer: Answer | null
+  notes: string
+  defer: Defer | null
+  needsDiscussion: boolean
+  proposalDismissed: boolean
+  status: QuestionStatus
+  changed: boolean
+  revisedAt: number
+  recordedAs: string | null
+}
+
+/** The mutable state of one plan. */
+export interface PlanState {
+  questions: Record<string, QuestionState>
+  submittedGroups: string[]
+}
+
+/** One evaluated question. */
+export interface EvaluationEntry {
+  visible: boolean
+  effective: Answer | null
+  source: "user" | "implied" | null
+  impliedBy: string[]
+  impliedReasons: string[]
+  overridesImplied: boolean
+  conflict: { from: string; answer: Answer }[]
+}
+
+/** The result of evaluating a plan. */
+export interface Evaluation {
+  questions: Map<string, EvaluationEntry>
+  lockedGroups: Set<string>
+}
+
+/** One reason a group is not ready. */
+export interface Missing {
+  key: string
+  reason: "unanswered" | "changed" | "conflict" | "proposal" | "nothing-to-submit"
+}
+
+/** Per-bucket question counts for list views. */
+export interface PlanCounts {
+  open: number
+  answered: number
+  deferred: number
+  discussion: number
+  submitted: number
+  recorded: number
+}
+
+/** The JSON Schema of the publish tool input. */
+export declare const DiscoveryPublishSchema: Record<string, unknown>
+
+/** Validate and normalize a publish payload; never throws. */
+export declare function validatePublish(
+  input: unknown
+):
+  | { ok: true; plan: PublishedPlan }
+  | { ok: false; errors: string[] }
+
+/** Validate one stored answer for its question type. */
+export declare function validateAnswer(
+  question: Question,
+  answer: unknown
+): { ok: true } | { ok: false; error: string }
+
+/** Validate a deferral. */
+export declare function validateDefer(
+  defer: unknown
+): { ok: true } | { ok: false; error: string }
+
+/** Convert a compact answer into the stored shape. */
+export declare function toAnswer(question: Question, compact: CompactAnswer): Answer
+
+/** Canonical content string used to detect a changed question. */
+export declare function questionFingerprint(question: Question): string
+
+/** Evaluate visibility, implications, conflicts, and group locks. */
+export declare function evaluatePlan(plan: PublishedPlan, state: PlanState): Evaluation
+
+/** Whether a group can be submitted, and what is missing when it cannot. */
+export declare function groupReadiness(
+  plan: PublishedPlan,
+  state: PlanState,
+  evaluation: Evaluation,
+  groupKey: string
+): { ready: boolean; locked: boolean; missing: Missing[] }
+
+/** Counts used by list views. */
+export declare function planCounts(
+  plan: PublishedPlan,
+  state: PlanState,
+  evaluation: Evaluation
+): PlanCounts