opencode-codeops 2.5.0 → 2.6.0

package/bin/lib/test-selection.mjs

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+/**
+ * Pure test-selection algorithm.
+ *
+ * Given a loaded map, a change set, and a gate, decide which groups must run.
+ * The function is pure: it never reads Git, executes a command, or scans the
+ * repository. That keeps the most failure-sensitive logic easy to test and
+ * makes the CLI's job a thin I/O wrapper.
+ *
+ * The safety rule is simple: any uncertainty returns `mode: "full"` with a
+ * visible reason. A partial selection is never produced from an incomplete or
+ * malformed map.
+ *
+ * @module lib/test-selection
+ */
+
+import { isTargetBasedGroup, normalizeRepoPath } from "./test-map.mjs"
+import { matchesAnyGlob } from "./test-selection-glob.mjs"
+
+/** Gates that may narrow the run to less than every group. */
+export const PARTIAL_GATES = Object.freeze(["task", "phase", "pr"])
+
+/** Every gate the selector accepts. */
+export const ALL_GATES = Object.freeze(["task", "phase", "pr", "release", "acceptance", "nightly"])
+
+/** Tiers allowed at each gate; `null` means every tier. */
+const GATE_TIERS = Object.freeze({
+  task: Object.freeze(["task"]),
+  phase: Object.freeze(["task", "phase"]),
+  pr: Object.freeze(["task", "phase"]),
+  release: null,
+  acceptance: null,
+  nightly: null,
+})
+
+/** Stable reason order used in output and explanations. */
+const REASON_ORDER = Object.freeze([
+  "direct-source",
+  "direct-test",
+  "included",
+  "dependent",
+  "always-run",
+  "smoke",
+  "gate-all",
+])
+
+/**
+ * Add one reason to a group's reason set.
+ *
+ * @param {Map<string, Set<string>>} reasons Reason sets by group ID.
+ * @param {string} id Group ID.
+ * @param {string} reason Stable reason token.
+ */
+function addReason(reasons, id, reason) {
+  if (!reasons.has(id)) reasons.set(id, new Set())
+  reasons.get(id).add(reason)
+}
+
+/**
+ * Sort reasons into the documented order.
+ *
+ * @param {Set<string>} values Reason set.
+ * @returns {string[]} Ordered reasons.
+ */
+function orderedReasons(values) {
+  return [...values].sort((left, right) => REASON_ORDER.indexOf(left) - REASON_ORDER.indexOf(right))
+}
+
+/**
+ * Build the full-suite result.
+ *
+ * @param {object} input Result input.
+ * @param {string} input.reason Stable fallback reason.
+ * @param {object|null} input.policy Policy, when a map exists.
+ * @param {string|null} input.mapHash Map hash.
+ * @param {string} input.gate Gate.
+ * @param {object|null} input.base Resolved base.
+ * @param {string[]} input.changed Changed paths.
+ * @param {string[]} input.skipped Group IDs that did not run.
+ * @param {object[]} input.warnings Accumulated warnings.
+ * @param {string[]} [input.unknownPaths] Paths with no owner.
+ * @returns {object} Full selection result.
+ */
+function fullResult({ reason, policy, mapHash, gate, base, changed, skipped, warnings, unknownPaths = [] }) {
+  const commands = expandFullCommands(policy)
+  return {
+    schema: 1,
+    mode: "full",
+    gate,
+    base: base ?? null,
+    mapHash: mapHash ?? null,
+    changed,
+    selected: [],
+    deferred: [],
+    skipped,
+    commands,
+    budget: { estimatedSec: 0, status: "not-applicable" },
+    warnings,
+    reason,
+    fullCommand: policy?.full ?? null,
+    unknownPaths,
+  }
+}
+
+/**
+ * Expand a policy's full command into runner-shaped commands.
+ *
+ * @param {object|null} policy Map policy.
+ * @returns {Array<{id: string, argv: string[], cwd: string}>} Commands to run.
+ */
+function expandFullCommands(policy) {
+  const full = policy?.full
+  if (!Array.isArray(full) || full.length === 0) return []
+  if (full.every((token) => typeof token === "string")) {
+    return [{ id: "full", argv: [...full], cwd: "." }]
+  }
+  return full.map((argv, index) => ({ id: `full.${index + 1}`, argv: [...argv], cwd: "." }))
+}
+
+/**
+ * Compute the task-budget status without ever dropping a group.
+ *
+ * @param {object[]} selected Selected groups.
+ * @param {object} policy Map policy.
+ * @returns {{estimatedSec: number, status: string, breakdown?: object[]}} Budget summary.
+ */
+function budgetFor(selected, policy) {
+  const taskGroups = selected.filter((group) => group.tier === "task")
+  const estimatedSec = taskGroups.reduce((total, group) => total + (group.durationSec ?? 0), 0)
+  const target = policy.budgets?.taskTargetSeconds ?? 120
+  const acceptable = policy.budgets?.taskAcceptableSeconds ?? 180
+  const status = estimatedSec <= target ? "within-target" : estimatedSec <= acceptable ? "acceptable" : "over-budget"
+  if (status !== "over-budget") return { estimatedSec, status }
+  return {
+    estimatedSec,
+    status,
+    breakdown: taskGroups.map((group) => ({ id: group.id, durationSec: group.durationSec ?? 0 })),
+  }
+}
+
+/**
+ * Resolve a group's full test set and expand its argv command.
+ *
+ * `{tests}` always expands to every file the group owns, not only the files in
+ * the current change set. A source-only change therefore still runs the whole
+ * group, which is what makes a green task result meaningful.
+ *
+ * @param {object} group Selected group.
+ * @param {string[]|null} files Tracked repository files.
+ * @param {boolean} caseSensitive Match case sensitivity.
+ * @returns {{argv: string[], cwd: string}|null} Expanded command, or null when the test set is empty.
+ */
+function expandGroupCommand(group, files, caseSensitive) {
+  const tests = Array.isArray(group.tests) ? group.tests : []
+  const needsTests = group.run.command.some((token) => token === "{tests}")
+  const resolved = needsTests
+    ? (files ?? [])
+        .map(normalizeRepoPath)
+        .filter((file) => matchesAnyGlob(file, tests, { caseSensitive }))
+        .sort()
+    : []
+  if (needsTests && resolved.length === 0) return null
+
+  const argv = []
+  for (const token of group.run.command) {
+    if (token === "{tests}") argv.push(...resolved)
+    else argv.push(token)
+  }
+  return { argv, cwd: group.run.cwd ?? "." }
+}
+
+/**
+ * Select test groups for one gate.
+ *
+ * @param {object} input Selection input.
+ * @param {object|null} input.map Loaded map, or null for the no-map case.
+ * @param {string|null} [input.mapHash] Map hash for evidence.
+ * @param {string[]} [input.changed=[]] Changed repository paths.
+ * @param {string[]|null} [input.files=null] Tracked repository files for command expansion.
+ * @param {string} [input.gate="task"] Gate name.
+ * @param {string[]} [input.include=[]] Extra paths that must be considered changed.
+ * @param {boolean} [input.explicitFull=false] Force the full suite.
+ * @param {Record<string, string>} [input.env={}] Environment values.
+ * @param {object|null} [input.base=null] Resolved base evidence.
+ * @returns {object} Deterministic selection result.
+ * @throws {Error} When the gate is unknown.
+ * @example
+ * const result = selectTests({ map: loaded.map, changed: ["web/billing/Dialog.tsx"], gate: "task" })
+ */
+export function selectTests({
+  map,
+  mapHash = null,
+  changed = [],
+  files = null,
+  gate = "task",
+  include = [],
+  explicitFull = false,
+  env = {},
+  base = null,
+}) {
+  if (!ALL_GATES.includes(gate)) throw new Error(`unknown gate: ${gate}`)
+  const warnings = []
+  const policy = map?.policy ?? null
+  const groups = map?.groups ?? []
+  const allIds = groups.map((group) => group.id).sort()
+  const changedPaths = [...new Set([...changed, ...include].map(normalizeRepoPath))].sort()
+
+  if (!map) {
+    return fullResult({ reason: "no-map", policy: null, mapHash: null, gate, base, changed: changedPaths, skipped: [], warnings })
+  }
+
+  if (explicitFull || env.CODEOPS_FULL_TESTS === "1") {
+    return fullResult({ reason: "forced", policy, mapHash, gate, base, changed: changedPaths, skipped: allIds, warnings })
+  }
+
+  const caseSensitive = policy.caseSensitive !== false
+  if (!caseSensitive) {
+    warnings.push({ code: "case-insensitive", message: "path matching is case-insensitive by policy override" })
+  }
+  const matchOptions = { caseSensitive }
+
+  const fullOnPaths = (policy.fullOnPaths ?? []).filter((pattern) =>
+    changedPaths.some((path) => matchesAnyGlob(path, [pattern], matchOptions)),
+  )
+  if (fullOnPaths.length > 0) {
+    const matching = changedPaths.filter((path) => matchesAnyGlob(path, fullOnPaths, matchOptions))
+    return fullResult({
+      reason: "full-on-path",
+      policy,
+      mapHash,
+      gate,
+      base,
+      changed: matching,
+      skipped: allIds,
+      warnings,
+    })
+  }
+
+  const ignoreGlobs = (policy.ignorePaths ?? []).map((entry) => entry.glob)
+  const relevant = changedPaths.filter((path) => !matchesAnyGlob(path, ignoreGlobs, matchOptions))
+  if (changedPaths.length > 0 && relevant.length === 0) {
+    return {
+      schema: 1,
+      mode: "none",
+      gate,
+      base: base ?? null,
+      mapHash,
+      changed: changedPaths,
+      selected: [],
+      deferred: [],
+      skipped: allIds,
+      commands: [],
+      budget: { estimatedSec: 0, status: "not-applicable" },
+      warnings,
+      reason: "docs-only",
+      fullCommand: policy.full ?? null,
+      unknownPaths: [],
+    }
+  }
+
+  const includeSet = new Set(include.map(normalizeRepoPath))
+  const reasons = new Map()
+  const unknownPaths = []
+
+  for (const path of relevant) {
+    let matched = false
+    for (const group of groups) {
+      const sourceMatch = matchesAnyGlob(path, group.sources ?? [], matchOptions)
+      const testMatch = Array.isArray(group.tests) && matchesAnyGlob(path, group.tests, matchOptions)
+      if (sourceMatch) addReason(reasons, group.id, "direct-source")
+      if (testMatch) addReason(reasons, group.id, "direct-test")
+      if (sourceMatch || testMatch) {
+        matched = true
+        if (includeSet.has(path)) addReason(reasons, group.id, "included")
+      }
+    }
+    if (!matched) unknownPaths.push(path)
+  }
+
+  if (unknownPaths.length > 0) {
+    return fullResult({
+      reason: "unknown-path",
+      policy,
+      mapHash,
+      gate,
+      base,
+      changed: changedPaths,
+      skipped: allIds,
+      warnings,
+      unknownPaths,
+    })
+  }
+
+  const byId = new Map(groups.map((group) => [group.id, group]))
+  const dependents = new Map()
+  for (const group of groups) {
+    for (const dependency of group.dependsOn ?? []) {
+      if (!dependents.has(dependency)) dependents.set(dependency, [])
+      dependents.get(dependency).push(group.id)
+    }
+  }
+
+  const queue = [...reasons.keys()]
+  while (queue.length > 0) {
+    const current = queue.shift()
+    for (const dependent of dependents.get(current) ?? []) {
+      if (!reasons.has(dependent)) {
+        addReason(reasons, dependent, "dependent")
+        queue.push(dependent)
+      }
+    }
+  }
+
+  for (const group of groups) {
+    if (group.alwaysRun === true) addReason(reasons, group.id, "always-run")
+  }
+
+  const allowedTiers = GATE_TIERS[gate]
+  if (allowedTiers === null) {
+    for (const group of groups) {
+      if (!reasons.has(group.id)) addReason(reasons, group.id, "gate-all")
+    }
+  }
+
+  const deferred = []
+  for (const id of [...reasons.keys()]) {
+    const group = byId.get(id)
+    if (!group) continue
+    if (allowedTiers !== null && !allowedTiers.includes(group.tier)) {
+      reasons.delete(id)
+      deferred.push({ id: group.id, reason: "deferred-tier" })
+    }
+  }
+
+  if (gate === "pr") {
+    for (const id of policy.prSmoke ?? []) {
+      if (byId.has(id)) addReason(reasons, id, "smoke")
+    }
+  }
+
+  if (allowedTiers !== null) {
+    const selectedCount = reasons.size
+    const threshold = policy.fullThreshold ?? 0.6
+    if (groups.length > 0 && selectedCount / groups.length >= threshold) {
+      return fullResult({ reason: "threshold", policy, mapHash, gate, base, changed: changedPaths, skipped: allIds, warnings })
+    }
+  }
+
+  const selectedGroups = [...reasons.keys()]
+    .map((id) => byId.get(id))
+    .filter(Boolean)
+    .sort((left, right) => left.slice.localeCompare(right.slice) || left.id.localeCompare(right.id))
+
+  const commands = []
+  for (const group of selectedGroups) {
+    const command = expandGroupCommand(group, files, caseSensitive)
+    if (!command) {
+      return fullResult({
+        reason: "map.empty-group",
+        policy,
+        mapHash,
+        gate,
+        base,
+        changed: changedPaths,
+        skipped: allIds,
+        warnings,
+      })
+    }
+    commands.push({ id: group.id, argv: command.argv, cwd: command.cwd })
+  }
+
+  const budget = budgetFor(selectedGroups, policy)
+  if (budget.status === "over-budget") {
+    warnings.push({
+      code: "budget.over-budget",
+      message: `selected task groups estimate ${budget.estimatedSec}s; all groups are retained`,
+      breakdown: budget.breakdown,
+    })
+  }
+
+  const selectedIds = new Set(selectedGroups.map((group) => group.id))
+  const deferredIds = new Set(deferred.map((entry) => entry.id))
+  const skipped = allIds.filter((id) => !selectedIds.has(id) && !deferredIds.has(id))
+
+  return {
+    schema: 1,
+    mode: "groups",
+    gate,
+    base: base ?? null,
+    mapHash,
+    changed: changedPaths,
+    selected: selectedGroups.map((group) => ({
+      id: group.id,
+      slice: group.slice,
+      reasons: orderedReasons(reasons.get(group.id)),
+    })),
+    deferred: deferred.sort((left, right) => left.id.localeCompare(right.id)),
+    skipped,
+    commands,
+    budget: { estimatedSec: budget.estimatedSec, status: budget.status },
+    warnings,
+    reason: null,
+    fullCommand: policy.full ?? null,
+    unknownPaths: [],
+  }
+}
+
+/**
+ * Check whether a group is target-based and therefore exempt from `{tests}`.
+ *
+ * Re-exported so the CLI and templates do not need a second import path.
+ *
+ * @param {object} group Map group.
+ * @returns {boolean} `true` when the command has no `{tests}` placeholder.
+ */
+export function groupUsesTargetDiscovery(group) {
+  return isTargetBasedGroup(group)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {
@@ -14,7 +14,8 @@
     "./tui": "./plugin/tui.js"
   },
   "bin": {
-    "opencode-codeops": "bin/index.mjs"
+    "opencode-codeops": "bin/index.mjs",
+    "codeops-test": "bin/codeops-test.mjs"
   },
   "scripts": {
     "test": "node --test",
@@ -39,6 +40,7 @@
     "!scripts/*.test.mjs",
     "!scripts/*.spec.test.mjs",
     "bin/",
+    "!bin/fixtures/",
     "!bin/*.test.mjs",
     "!bin/*.spec.test.mjs",
     "references/",

package/schemas/test-map.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/blendsdk/opencode-codeops/schemas/test-map.schema.json",
+  "title": "CodeOps test-impact map",
+  "description": "A single-file map, a policy file, or one group fragment. The loader combines a policy file with fragments.",
+  "oneOf": [
+    { "$ref": "#/$defs/singleMap" },
+    { "$ref": "#/$defs/policyFile" },
+    { "$ref": "#/$defs/fragment" }
+  ],
+  "$defs": {
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\u0000).*$"
+    },
+    "argv": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "full": {
+      "oneOf": [
+        { "$ref": "#/$defs/argv" },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/argv" }
+        }
+      ]
+    },
+    "ignoreEntry": {
+      "type": "object",
+      "required": ["glob", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "glob": { "$ref": "#/$defs/path" },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "branches": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "integration": { "type": "array", "items": { "type": "string" } },
+        "feature": { "type": "array", "items": { "type": "string" } },
+        "release": { "type": "array", "items": { "type": "string" } },
+        "acceptance": { "type": "array", "items": { "type": "string" } },
+        "releaseTags": { "type": "array", "items": { "type": "string" } },
+        "unknown": { "enum": ["integration", "feature", "release", "acceptance"] }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "required": ["schema", "full"],
+      "additionalProperties": true,
+      "properties": {
+        "schema": { "const": 1 },
+        "full": { "$ref": "#/$defs/full" },
+        "budgets": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "taskTargetSeconds": { "type": "number", "minimum": 0 },
+            "taskAcceptableSeconds": { "type": "number", "minimum": 0 }
+          }
+        },
+        "branches": { "$ref": "#/$defs/branches" },
+        "ignorePaths": { "type": "array", "items": { "$ref": "#/$defs/ignoreEntry" } },
+        "fullOnPaths": { "type": "array", "items": { "$ref": "#/$defs/path" } },
+        "acceptance": {
+          "type": "object",
+          "required": ["mode"],
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "enum": ["automated", "manual", "external"] },
+            "groups": { "type": "array", "items": { "type": "string" } },
+            "checklist": { "type": ["string", "null"] }
+          }
+        },
+        "testRoots": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "array", "items": { "$ref": "#/$defs/path" } }
+          ]
+        },
+        "fullThreshold": { "type": "number", "minimum": 0, "maximum": 1 },
+        "prSmoke": { "type": "array", "items": { "type": "string" } },
+        "requirements": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["check"],
+            "additionalProperties": false,
+            "properties": { "check": { "$ref": "#/$defs/argv" } }
+          }
+        },
+        "caseSensitive": { "type": "boolean" }
+      }
+    },
+    "sliceAcceptance": {
+      "type": "object",
+      "required": ["mode", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["manual", "external", "na"] },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "group": {
+      "type": "object",
+      "required": ["id", "slice", "tier", "sources", "run"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "slice": { "type": "string", "minLength": 1 },
+        "tier": { "enum": ["task", "phase", "release", "acceptance"] },
+        "sources": { "type": "array", "items": { "$ref": "#/$defs/path" } },
+        "tests": { "type": "array", "items": { "$ref": "#/$defs/path" } },
+        "dependsOn": { "type": "array", "items": { "type": "string" } },
+        "alwaysRun": { "type": "boolean" },
+        "durationSec": { "type": "number", "minimum": 0 },
+        "parallelSafe": { "type": "boolean" },
+        "requires": { "type": "array", "items": { "type": "string" } },
+        "owner": { "type": "string" },
+        "description": { "type": "string" },
+        "acceptance": { "$ref": "#/$defs/sliceAcceptance" },
+        "run": {
+          "type": "object",
+          "required": ["command"],
+          "additionalProperties": false,
+          "properties": {
+            "command": { "$ref": "#/$defs/argv" },
+            "cwd": { "$ref": "#/$defs/path" }
+          }
+        }
+      }
+    },
+    "singleMap": {
+      "type": "object",
+      "required": ["schema", "policy", "groups"],
+      "additionalProperties": false,
+      "properties": {
+        "schema": { "const": 1 },
+        "policy": { "$ref": "#/$defs/policy" },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } }
+      }
+    },
+    "policyFile": {
+      "$ref": "#/$defs/policy"
+    },
+    "fragment": {
+      "type": "object",
+      "required": ["schema", "groups"],
+      "additionalProperties": false,
+      "properties": {
+        "schema": { "const": 1 },
+        "domain": { "type": "string" },
+        "owner": { "type": "string" },
+        "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } }
+      }
+    }
+  }
+}

package/skills/analyze-project/SKILL.md

@@ -20,7 +20,14 @@ description: Analyze the current repository and create or refresh concise CodeOp
 ```
 
 5. Include project type, principal languages/frameworks, authoritative build/test/verify commands, high-level structure, generated-file warnings, and CodeOps artifact/config locations.
-6. If the managed section exists, replace only its contents. Preserve all other text byte-for-byte.
+6. If the managed section exists, replace only its generated contents outside the `CODEOPS-TESTING` block. Preserve all other text byte-for-byte.
+6b. **Testing block.** Detect `codeops/test-map.json` or `codeops/test-map/` and the project's
+   `full` command. The `<!-- CODEOPS-TESTING:START -->` / `<!-- CODEOPS-TESTING:END -->` block
+   inside the managed section is owned by the `organize-tests` skill: preserve it byte-for-byte,
+   never render or overwrite it, and warn when it is missing or stale. With no map and no block,
+   report that no map is present and do not create a block; an existing no-map block is preserved
+   as-is. Warn (advisory only) when CI has no full gate on a release/acceptance branch. The block
+   contract is in [_shared/test-selection.md](../../_shared/test-selection.md).
 7. On a non-integration branch, preview changes to repository-wide guidance and ask before writing unless repository policy explicitly permits branch-local updates.
 8. In compact mode, remove duplication and stale generated detail from the managed section only. Flag suspected hand-authored bloat; never silently rewrite it.
 9. Validate every recorded command or mark it explicitly unverified.

package/skills/exec-plan/SKILL.md

@@ -145,7 +145,9 @@ summary template. The essentials:
 
 ### Step 1 — Load the plan
 
-1. Read `plans/$ARGUMENTS/99-execution-plan.md`.
+1. Read `plans/$ARGUMENTS/99-execution-plan.md`. An old plan with a single `**Verify**` line
+   uses that line as the gate command; with a map, derive the task command, otherwise it serves
+   both.
 2. Find incomplete tasks — both `[ ]` and implemented-but-unverified `[~]`; read supporting specs
    in `plans/$ARGUMENTS/`.
 3. Determine the starting point: a `[~]` task is resumed first (re-verify, then promote or keep
@@ -177,12 +179,17 @@ For each task, in order:
      points in [execution-protocol.md](execution-protocol.md) §Progress Reporting; a failed or
      missing report never blocks any step.
 
-3. **Verify** — run your project's verify command (from the project's AGENTS.md, or detected
-   project conventions), output captured per the protocol's **Verify-output capture rule**
-   (PASS one-liner; on failure the last 50 log lines + log path). Pass → promote `[~]` → `[x]`;
-   fail → fix and re-verify (mark stays `[~]`). Immediately after every `[x]` promotion, run the
-   protocol's read-only progress-bar command for the selected plan and show its exact output in the
-   next commentary update. Only `[x]` contributes to the displayed completion count.
+3. **Verify** — run the task command: the plan's `**Task verify**` line, or the map's `task`
+   gate with `--baseline <phase-tree>` and `--include <spec-file>` for the plan's declared spec
+   file(s). With neither, run the plan's `**Verify (gate)**` command, or the project's full verify
+   (from AGENTS.md or detected conventions), output captured per the protocol's
+   **Verify-output capture rule** (PASS one-liner; on failure
+   the last 50 log lines + log path). A changed path outside the phase's expected modification
+   set, or a shared/config/test-infrastructure change, forces the full gate. Pass → promote `[~]`
+   → `[x]`; fail → fix and re-verify (mark stays `[~]`). Immediately after every `[x]` promotion,
+   run the protocol's read-only progress-bar command for the selected plan and show its exact
+   output in the next commentary update. Only `[x]` contributes to the displayed completion
+   count.
 4. **Commit** per the active commit mode (see [commit-modes.md](commit-modes.md)) — the commit
    gate keys off `[x]`.
 5. **Techdocs check (after each phase):** if the phase introduced architectural changes and
@@ -215,7 +222,8 @@ For each task, in order:
 
 1. Finish the current task before stopping.
 2. **🚨 First, update `99-execution-plan.md`** with all completed tasks (before anything else).
-3. Run the verify command.
+3. Run the task command when the plan is not complete and the session stops inside a phase;
+   run the full gate at plan completion or a phase boundary.
 4. Handle the commit per the active commit mode.
 5. Report a session summary (must state `Execution Plan Updated: ✅`). Template in
    [execution-protocol.md](execution-protocol.md).