opencode-codeops 2.1.1 → 2.2.0

package/bin/lib/codeops-rpc.d.mts

@@ -0,0 +1,160 @@
+/**
+ * Type declarations for the CodeOps RPC helper.
+ *
+ * The helper is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entries typed access. The
+ * definition carries the status method, the progress method, and the
+ * updated/cleared events.
+ */
+
+import type {
+  CodeOpsProgressRuntime,
+  CodeOpsRunClearedSchema,
+  CodeOpsRunState,
+  CodeOpsRunStateSchema,
+} from "./codeops-progress.mjs"
+
+/** JSON-Schema shape of the empty input accepted by the `status` method. */
+export type CodeOpsRpcStatusInput = {
+  readonly type: "object"
+  readonly additionalProperties: false
+}
+
+/** JSON-Schema shape of the payload the `status` method returns. */
+export type CodeOpsRpcStatusOutput = {
+  readonly type: "object"
+  readonly additionalProperties: false
+  readonly required: readonly ["pluginVersion", "openCodeVersion", "directory"]
+  readonly properties: {
+    readonly pluginVersion: { readonly type: "string" }
+    readonly openCodeVersion: { readonly type: "string" }
+    readonly directory: { readonly type: "string" }
+  }
+}
+
+/** The status payload after runtime validation. */
+export interface CodeOpsStatus {
+  readonly pluginVersion: string
+  readonly openCodeVersion: string
+  readonly directory: string
+}
+
+/** JSON-Schema shape of the empty input accepted by the `progress` method. */
+export type CodeOpsRpcProgressInput = {
+  readonly type: "object"
+  readonly additionalProperties: false
+}
+
+/** JSON-Schema shape of the `progress` method's payload: a snapshot or null. */
+export type CodeOpsRpcProgressOutput = {
+  readonly anyOf: readonly [CodeOpsRunStateSchema, { readonly type: "null" }]
+}
+
+/** The `updated` event of the codeops RPC: the full run snapshot. */
+export interface CodeOpsRpcUpdatedEvent {
+  readonly schema: CodeOpsRunStateSchema
+}
+
+/** The `cleared` event of the codeops RPC: the cleared run's identity. */
+export interface CodeOpsRpcClearedEvent {
+  readonly schema: CodeOpsRunClearedSchema
+}
+
+/** The portable RPC definition shared by the server plugin and the TUI entry. */
+export interface CodeOpsRpcDefinition {
+  readonly id: "codeops"
+  readonly methods: {
+    readonly status: {
+      readonly input: CodeOpsRpcStatusInput
+      readonly output: CodeOpsRpcStatusOutput
+    }
+    readonly progress: {
+      readonly input: CodeOpsRpcProgressInput
+      readonly output: CodeOpsRpcProgressOutput
+    }
+  }
+  readonly events: {
+    readonly updated: CodeOpsRpcUpdatedEvent
+    readonly cleared: CodeOpsRpcClearedEvent
+  }
+}
+
+/** The shared definition object; plain data with no runtime imports. */
+export declare const CodeOpsRpc: CodeOpsRpcDefinition
+
+/** Options accepted by {@link registerCodeOpsRpc}. */
+export interface RegisterCodeOpsRpcOptions {
+  /** Version of the installed package, reported by the status method. */
+  pluginVersion?: string
+  /** The run-state runtime the progress method serves and binds emission from. */
+  runtime?: CodeOpsProgressRuntime
+}
+
+/**
+ * Feature-detect `ctx.rpc.register`, register the codeops RPC when present,
+ * and report success. Never throws.
+ */
+export declare function registerCodeOpsRpc(
+  ctx: unknown,
+  options?: RegisterCodeOpsRpcOptions
+): Promise<boolean>
+
+/** Validate an unknown RPC payload as a complete CodeOps status record. */
+export declare function isCodeOpsStatus(value: unknown): value is CodeOpsStatus
+
+/** The location a status call is scoped to. */
+export interface CodeOpsLocation {
+  readonly directory: string
+  readonly workspaceID?: string
+}
+
+/** Call options forwarded to the status call. */
+export interface CodeOpsCallOptions {
+  readonly location?: CodeOpsLocation
+}
+
+/** Structural client shape {@link requestStatus} consumes. */
+export interface CodeOpsStatusClient {
+  readonly rpc: (definition: CodeOpsRpcDefinition) => {
+    readonly status: (
+      input: Record<string, never>,
+      options?: CodeOpsCallOptions
+    ) => Promise<unknown>
+  }
+}
+
+/**
+ * Request the raw status payload from a host client, converting every
+ * transport failure into `undefined`.
+ *
+ * Pass the calling session's location in `options`: the host resolves RPC
+ * calls against it, and a call without one can miss the plugin's registration
+ * when the session's project differs from the host's default location.
+ */
+export declare function requestStatus(
+  client: CodeOpsStatusClient,
+  options?: CodeOpsCallOptions
+): Promise<unknown>
+
+/** Structural client shape {@link requestProgress} consumes. */
+export interface CodeOpsProgressClient {
+  readonly rpc: (definition: CodeOpsRpcDefinition) => {
+    readonly progress: (
+      input: Record<string, never>,
+      options?: CodeOpsCallOptions
+    ) => Promise<unknown>
+  }
+}
+
+/**
+ * Request the current run snapshot from a host client, converting every
+ * transport failure into `null`.
+ *
+ * Pass the calling session's location in `options`: the host resolves RPC
+ * calls against it, and a call without one can miss the plugin's registration
+ * when the session's project differs from the host's default location.
+ */
+export declare function requestProgress(
+  client: CodeOpsProgressClient,
+  options?: CodeOpsCallOptions
+): Promise<CodeOpsRunState | null>

package/bin/lib/codeops-rpc.mjs

@@ -0,0 +1,177 @@
+/**
+ * The CodeOps RPC: definition, registration guard, payload guard, and the
+ * progress snapshot helper.
+ *
+ * The definition is plain data — the SDK's `Rpc.define` performs identity and
+ * reserved-name validation only — so this module needs no runtime import of
+ * the SDK and `node --test` can exercise it directly. The definition carries
+ * the `status` method, the `progress` method that answers with the current run
+ * snapshot, and the `updated`/`cleared` events the sidebar follows. The
+ * registration guard keeps the surface safe on builds that do not implement
+ * custom RPCs: it never throws and reports success with a boolean. When the
+ * host returns a registration exposing `events.emit`, the guard binds the
+ * runtime's emission through it, so accepted reports push live updates.
+ *
+ * @module codeops-rpc
+ */
+
+import { RunClearedSchema, RunStateSchema, isCodeOpsRunState } from "./codeops-progress.mjs"
+
+/**
+ * The portable `codeops` RPC definition shared by the server plugin and the
+ * TUI entry: a `status` method with an empty-object input and a three-string
+ * payload, a `progress` method answering with the current run snapshot (or
+ * `null`), and the `updated`/`cleared` events that push every accepted change.
+ */
+export const CodeOpsRpc = {
+  id: "codeops",
+  methods: {
+    status: {
+      input: { type: "object", additionalProperties: false },
+      output: {
+        type: "object",
+        additionalProperties: false,
+        required: ["pluginVersion", "openCodeVersion", "directory"],
+        properties: {
+          pluginVersion: { type: "string" },
+          openCodeVersion: { type: "string" },
+          directory: { type: "string" },
+        },
+      },
+    },
+    progress: {
+      input: { type: "object", additionalProperties: false },
+      output: { anyOf: [RunStateSchema, { type: "null" }] },
+    },
+  },
+  events: {
+    updated: { schema: RunStateSchema },
+    cleared: { schema: RunClearedSchema },
+  },
+}
+
+/**
+ * Coerce an optional host value to the string form the payload requires.
+ *
+ * @param value - Value reported by the host context.
+ * @returns The value as a string, or an empty string when it is absent.
+ */
+function asText(value) {
+  return value === undefined || value === null ? "" : String(value)
+}
+
+/**
+ * Register the codeops RPC on a plugin context, feature-detected and
+ * never-throwing.
+ *
+ * When a runtime is supplied, the `progress` method answers with its current
+ * snapshot and — if the returned registration exposes `events.emit` — the
+ * runtime binds its emission through that function, so every accepted report
+ * or clear pushes a live event.
+ *
+ * @param ctx - Server plugin context; only `rpc.register`, `app.version`, and
+ *   `location.directory` are read.
+ * @param {{ pluginVersion?: string, runtime?: object }} [options] -
+ *   Registration options.
+ * @returns `true` when the registration call completed, `false` when the host
+ *   lacks the RPC API or the registration failed. Never throws.
+ */
+export async function registerCodeOpsRpc(ctx, { pluginVersion, runtime } = {}) {
+  if (typeof ctx?.rpc?.register !== "function") return false
+  try {
+    const registration = await ctx.rpc.register(CodeOpsRpc, {
+      async status() {
+        return {
+          pluginVersion: asText(pluginVersion),
+          openCodeVersion: asText(ctx?.app?.version),
+          directory: asText(ctx?.location?.directory),
+        }
+      },
+      // The host adapter requires handlers to return promises; a synchronous
+      // return fails the call. async even though nothing is awaited.
+      async progress() {
+        return runtime?.snapshot() ?? null
+      },
+    })
+    if (
+      runtime &&
+      typeof runtime.bindEmit === "function" &&
+      typeof registration?.events?.emit === "function"
+    ) {
+      runtime.bindEmit(registration.events.emit)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Validate an unknown RPC payload as a complete CodeOps status record.
+ *
+ * @param value - Value received from the RPC.
+ * @returns `true` only for a plain object carrying exactly the three string
+ *   fields of the contract.
+ */
+export function isCodeOpsStatus(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  if (Object.keys(value).length !== 3) return false
+  return (
+    typeof value.pluginVersion === "string" &&
+    typeof value.openCodeVersion === "string" &&
+    typeof value.directory === "string"
+  )
+}
+
+/**
+ * Request the codeops status payload from a host client, converting every
+ * transport failure into `undefined`.
+ *
+ * A caller can therefore render from the result without a `catch`: a host
+ * without the RPC, a server plugin that failed to register, and a failed call
+ * all collapse into the same "no status" outcome. The payload is returned as
+ * received; narrow it with {@link isCodeOpsStatus} before use.
+ *
+ * Pass the calling session's location in `options`. The host resolves RPC
+ * calls against a location, and a call without one can miss the plugin's
+ * registration — the default location does not necessarily match a project
+ * opened through a path argument.
+ *
+ * @param client - Host client exposing `rpc(definition).status({}, options)`.
+ * @param {{ location?: { directory?: string, workspaceID?: string } }} [options]
+ *   - Call options forwarded to the status call.
+ * @returns The raw status payload, or `undefined` when the call fails.
+ */
+export async function requestStatus(client, options) {
+  try {
+    return await client.rpc(CodeOpsRpc).status({}, options)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Request the current run snapshot from a host client, converting every
+ * failure into `null`.
+ *
+ * Pass the calling session's location in `options`, for the same reason as
+ * {@link requestStatus}: the host resolves RPC calls against a location, and
+ * a call without one can miss the plugin's registration. The payload is
+ * validated before it is returned, so an invalid payload, a "no run" answer,
+ * and any transport failure all collapse into `null` and the caller can
+ * render without a `catch`.
+ *
+ * @param client - Host client exposing `rpc(definition).progress({}, options)`.
+ * @param {{ location?: { directory?: string, workspaceID?: string } }} [options]
+ *   - Call options forwarded to the progress call.
+ * @returns The validated snapshot, or `null` when no run is active or the
+ *   call failed. Never throws.
+ */
+export async function requestProgress(client, options) {
+  try {
+    const payload = await client.rpc(CodeOpsRpc).progress({}, options)
+    return isCodeOpsRunState(payload) ? payload : null
+  } catch {
+    return null
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {
@@ -10,7 +10,8 @@
   "main": "./plugin/index.ts",
   "exports": {
     ".": "./plugin/index.ts",
-    "./server": "./plugin/index.ts"
+    "./server": "./plugin/index.ts",
+    "./tui": "./plugin/tui.tsx"
   },
   "bin": {
     "opencode-codeops": "bin/index.mjs"
@@ -24,6 +25,8 @@
   },
   "files": [
     "plugin/",
+    "!plugin/*.test.mjs",
+    "!plugin/*.spec.test.mjs",
     "skills/",
     "_shared/",
     "standards/",
@@ -68,7 +71,26 @@
     "@opencode/plugin": "^2.0.24"
   },
   "devDependencies": {
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
     "@types/node": "^22.20.2",
+    "solid-js": "1.9.12",
     "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.14",
+    "@opentui/solid": ">=0.5.14",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
   }
 }

package/plugin/index.ts

@@ -9,6 +9,11 @@ import {
   cleanStaleTmpDirs,
   ensureSessionTmpDir,
 } from "../bin/lib/tmp-hygiene.mjs"
+import {
+  createCodeOpsProgress,
+  registerCodeOpsProgressTool,
+} from "../bin/lib/codeops-progress.mjs"
+import { registerCodeOpsRpc } from "../bin/lib/codeops-rpc.mjs"
 import {
   appendEffortTrace,
   applyEffort,
@@ -223,6 +228,11 @@ export default Plugin.define({
     const warnedEffortLevels = new Set<string>()
     const effortTraceEnabled = isEffortTraceEnabled(process.env.CODEOPS_EFFORT_TRACE)
 
+    // The live run state is memory-only, for the lifetime of this plugin
+    // instance: it is never persisted and clears when the reporting session
+    // ends, so it can never outlive the run it describes.
+    const progress = createCodeOpsProgress()
+
     // Sweep scratch directories abandoned by earlier interrupted runs, once.
     // Cleanup is best effort: a failure must never block a session.
     try {
@@ -234,8 +244,9 @@ export default Plugin.define({
     warnOnVersionSkew(directory)
 
     // ---------------------------------------------------------------------
-    // Session lifecycle: drop captured markers when a session is deleted, so
-    // a long-lived runtime does not remember ended sessions.
+    // Session lifecycle: drop captured markers and the session's live run
+    // when a session is deleted, so a long-lived runtime does not remember
+    // ended sessions.
     // ---------------------------------------------------------------------
     const controller = new AbortController()
     void (async () => {
@@ -243,6 +254,7 @@ export default Plugin.define({
         for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
           if (event.type === "session.deleted") {
             effortMarkers.delete(event.data.sessionID)
+            progress.clearSession(event.data.sessionID)
           }
         }
       } catch {
@@ -384,6 +396,47 @@ export default Plugin.define({
       }
     })
 
+    // ---------------------------------------------------------------------
+    // CodeOps RPC: expose the plugin identity and the live run snapshot for
+    // the sidebar. Registration is feature-detected and never blocks the
+    // plugin: builds without custom RPCs keep working unchanged, and the
+    // sidebar simply stays hidden. When the host hands back an event emitter,
+    // the registration binds it into the runtime, so accepted reports and
+    // clears push live events to connected clients.
+    // ---------------------------------------------------------------------
+    try {
+      const registered = await registerCodeOpsRpc(ctx, {
+        pluginVersion: packageVersion,
+        runtime: progress,
+      })
+      if (!registered) {
+        warnContentFree(
+          "The codeops status RPC is unavailable in this OpenCode build; " +
+            "the sidebar status stays hidden."
+        )
+      }
+    } catch {
+      warnContentFree("Could not register the codeops status RPC.")
+    }
+
+    // ---------------------------------------------------------------------
+    // Progress tool: let the agent report live task progress for the sidebar.
+    // The tool registers behind feature-detection; on every failure the
+    // plugin, the agent loop, and the Markdown execution plan keep working
+    // exactly as before.
+    // ---------------------------------------------------------------------
+    try {
+      const registered = await registerCodeOpsProgressTool(ctx, progress)
+      if (!registered) {
+        warnContentFree(
+          "The codeops progress tool is unavailable in this OpenCode build; " +
+            "the sidebar stays hidden."
+        )
+      }
+    } catch {
+      warnContentFree("Could not register the codeops progress tool.")
+    }
+
     // ---------------------------------------------------------------------
     // Plugin cleanup: stop listening for events. The runtime's scratch
     // directory is deliberately left in place — other sessions may still be

package/plugin/tui.tsx

@@ -0,0 +1,112 @@
+/**
+ * The CodeOps TUI entry: the live run-progress view in the session sidebar.
+ *
+ * The view is deliberately honest: it shows only reported values from the
+ * server's run state, always with an as-of time, and it renders nothing when
+ * there is no run, when the host lacks the events API, or when every call
+ * fails. There are no timers — the text recomputes whenever the component
+ * re-renders — and no file access; all display and merge logic lives in the
+ * shared helper module so it can be tested under plain Node.
+ *
+ * @module tui
+ */
+
+import { Plugin, usePlugin } from "@opencode/plugin/tui"
+import { createEffect, createResource, createSignal, onCleanup, Show } from "solid-js"
+
+import {
+  acceptRunCleared,
+  acceptRunUpdate,
+  describeRun,
+  mergeRunState,
+} from "../bin/lib/codeops-progress.mjs"
+import type { CodeOpsRunState } from "../bin/lib/codeops-progress.mjs"
+import { CodeOpsRpc, requestProgress } from "../bin/lib/codeops-rpc.mjs"
+
+/**
+ * The live run-progress view.
+ *
+ * Resolves the session's location once, subscribes to the `updated` and
+ * `cleared` events before requesting an initial snapshot, and merges both
+ * delivery paths monotonically. A clear records its server-stamped
+ * `clearedAt`; both merge paths ignore deliveries at or before it, so a late
+ * snapshot or update can never resurrect a cleared run. Every failure path is
+ * silent: a host without the events API still renders from the snapshot, and
+ * an invalid or missing snapshot renders nothing.
+ *
+ * @returns The three display lines, or nothing when no run is known.
+ */
+function CodeOpsProgress() {
+  const context = usePlugin()
+  const location = context.location ?? context.data.location.default()
+  const directory = location?.directory ?? ""
+  const [run, setRun] = createSignal<CodeOpsRunState | null>(null)
+  const [clearedAt, setClearedAt] = createSignal(0)
+
+  // Subscribe BEFORE the snapshot: events are live-only, so a snapshot
+  // fetched first could miss an update arriving in between. Guarded: a host
+  // without the events API still renders from the snapshot below.
+  const stops: (() => void)[] = []
+  try {
+    const events = context.client.rpc(CodeOpsRpc).events
+    const stopUpdated = events.on("updated", (event) => {
+      const snapshot = acceptRunUpdate(event, directory)
+      if (snapshot && snapshot.updatedAt > clearedAt()) {
+        setRun((current) => mergeRunState(current, snapshot))
+      }
+    })
+    stops.push(stopUpdated)
+    const stopCleared = events.on("cleared", (event) => {
+      const cleared = acceptRunCleared(event, directory)
+      if (!cleared) return
+      // Record the clear time for every accepted clear, before the identity
+      // gate: a clear that arrives before the initial snapshot must still
+      // suppress that snapshot, or a cleared run could reappear.
+      setClearedAt(cleared.clearedAt)
+      const current = run()
+      if (current && cleared.plan === current.plan && cleared.sessionID === current.sessionID) {
+        setRun(null)
+      }
+    })
+    stops.push(stopCleared)
+  } catch {
+    // Events unavailable: the snapshot-only view below still renders.
+  }
+  onCleanup(() => stops.forEach((stop) => stop()))
+
+  // Initial snapshot; null or a failure means "nothing known". The clear
+  // guard applies here too: a snapshot at or before the last clear is ignored.
+  const [initial] = createResource(async () => requestProgress(context.client, { location }))
+  createEffect(() => {
+    const snapshot = initial()
+    if (snapshot && snapshot.updatedAt > clearedAt()) {
+      setRun((current) => mergeRunState(current, snapshot))
+    }
+  })
+
+  return (
+    <Show when={run()}>
+      {(snapshot) => {
+        const view = () => describeRun(snapshot(), Date.now())
+        return (
+          <>
+            {view().lines.map((line) => (
+              <text>{line}</text>
+            ))}
+          </>
+        )
+      }}
+    </Show>
+  )
+}
+
+/**
+ * The opencode-codeops TUI plugin: claims the sidebar content slot with the
+ * live run view. The host disposes the claim when the plugin unloads.
+ */
+export default Plugin.define({
+  id: "opencode-codeops-tui",
+  setup(context) {
+    return context.ui.slot({ append: "sidebar.content", render: () => <CodeOpsProgress /> })
+  },
+})

package/scripts/codeops_plan.py

@@ -13,6 +13,7 @@ import re
 import sys
 from dataclasses import asdict, dataclass
 from pathlib import Path
+from typing import Iterator
 
 
 IMPLEMENTS_RE = re.compile(r"^>[ \t]*\*\*Implements\*\*:[ \t]*(.+?)[ \t]*$", re.MULTILINE)
@@ -21,7 +22,9 @@ TARGET_RE = re.compile(
     r"(?:RD-(?:[A-Za-z0-9]+-)*\d+|T-\d+|REQ-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)"
     r"(?![A-Za-z0-9_-])"
 )
-TASK_RE = re.compile(r"^-\s*\[([ xX~!])\]\s+(.+?)\s*$", re.MULTILINE)
+TASK_RE = re.compile(r"^-\s*\[([ xX~!])\]\s+(.+?)\s*$")
+FENCE_OPEN_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+TASK_ID_RE = re.compile(r"^\s*(?:\*\*)?([0-9]+\.[0-9]+\.[0-9]+|T-[0-9]+\.[0-9]+)(?=[\s*—–-]|$)")
 BLOCKED_REASON_RE = re.compile(r"(?:blocked|reason)\s*:\s*\S", re.IGNORECASE)
 _PROGRESS_WIDTH = 10
 _PROGRESS_FILLED = "█"
@@ -67,9 +70,70 @@ def parse_implements(index_text: str) -> tuple[str, ...]:
     return tuple(dict.fromkeys(TARGET_RE.findall(match.group(1))))
 
 
+def _task_lines(execution_text: str) -> Iterator[tuple[str, str, str]]:
+    """Yield ``(marker, text, task_id)`` for every real execution-task line.
+
+    A line qualifies when it carries one of the four checkbox markers outside a
+    fenced code block and its text begins with a task id. Fences follow the
+    Markdown shape: an opening run of three or more backticks or tildes (at
+    most three leading spaces, optional info string) hides everything up to a
+    closing run of the same character with at least the same length and nothing
+    else on the line; an unclosed fence hides the rest of the document. An id
+    is ``N.N.N`` or ``T-N.N`` after an optional ``**`` opener and must be
+    followed by whitespace, ``*``, a dash, or the end of the line, so
+    near-misses such as ``1.1.1.1``, ``T-05.1x``, and ``1.1.1:`` stay ignored.
+    Duplicate ids are yielded; the caller decides which occurrence counts.
+    """
+    fence_char = ""
+    fence_length = 0
+    for line in execution_text.splitlines():
+        line = line.rstrip()
+        if fence_char:
+            indent = len(line) - len(line.lstrip(" "))
+            body = line[indent:] if indent <= 3 else ""
+            if len(body) >= fence_length and body == fence_char * len(body):
+                fence_char = ""
+            continue
+        opener = FENCE_OPEN_RE.match(line)
+        if opener:
+            fence_char = opener.group(1)[0]
+            fence_length = len(opener.group(1))
+            continue
+        task = TASK_RE.match(line)
+        task_id = TASK_ID_RE.match(task.group(2)) if task else None
+        if task_id is None:
+            continue
+        yield task.group(1).lower(), task.group(2).strip(), task_id.group(1)
+
+
 def parse_tasks(execution_text: str) -> tuple[Task, ...]:
-    """Parse only the four authoritative execution checklist markers."""
-    return tuple(Task(marker.lower(), text.strip()) for marker, text in TASK_RE.findall(execution_text))
+    """Return the execution tasks a plan document really declares.
+
+    Fenced examples and checkbox lines without a task id (deliverable and
+    acceptance lists, quoted templates) are ignored, and a task id that appears
+    more than once counts once, from its first occurrence in document order.
+    """
+    tasks: list[Task] = []
+    seen: set[str] = set()
+    for marker, text, task_id in _task_lines(execution_text):
+        if task_id in seen:
+            continue
+        seen.add(task_id)
+        tasks.append(Task(marker, text))
+    return tuple(tasks)
+
+
+def has_checkbox_lines(execution_text: str) -> bool:
+    """Return whether a document carries at least one checklist line.
+
+    Presence is deliberately id-agnostic: legacy execution plans may list
+    tasks without ids, and migration admission must stay tolerant of them.
+    Counting correctness is ``parse_tasks``' job; this predicate only answers
+    "does the document look like it declares tasks at all". Fences are not
+    stripped here for the same reason — a quoted checklist still proves the
+    document format.
+    """
+    return any(TASK_RE.match(line.rstrip()) for line in execution_text.splitlines())
 
 
 def next_task(tasks: tuple[Task, ...]) -> Task | None: