opencode-codeops 2.5.0 → 2.6.0

package/skills/exec-plan/execution-protocol.md

@@ -50,6 +50,11 @@ Suggestion only — the user may proceed without upgrading.
 
 ### Phase start
 
+Record the phase's expected modification set from its task target paths and deliverables. The set
+drives the fallback rule: a task-time change outside it, or a shared/configuration/test-infrastructure
+change, runs the full gate. For an old plan, the rule is unchanged: a single `**Verify**` line is the gate
+command; with a map, derive the task command, otherwise use the same line for tasks.
+
 Before a phase's first task (and before a T-NN mini-plan's first task), snapshot the complete
 non-ignored worktree—including staged, unstaged, and untracked files—into a temporary Git tree,
 without changing the real index:
@@ -102,8 +107,16 @@ complete. For each task, in order:
    and update the Progress header. Do this before running verification or anything else — if the
    session crashes now, the implementation progress is preserved and the resume session knows the
    task still needs verification.
-4. Run verification (your project's verify command — from the project's AGENTS.md, or detected
-   project conventions), with output captured per the **Verify-output capture rule** below.
+4. Run verification, with output captured per the **Verify-output capture rule** below. Use the
+   task command for a normal task: the plan's validated `**Task verify**` line, or the map's
+   `task` gate with `--baseline <phase-baseline-tree>` and `--include <declared-spec-file>` for
+   every plan-declared specification test file. If neither exists, use the plan's
+   `**Verify (gate)**` command, or the project's full verify command (from AGENTS.md or detected
+   conventions). Run the full gate at phase exit, plan
+   completion, before push/release, and whenever a changed path falls outside the phase's
+   expected modification set or touches shared/configuration/test infrastructure. A single
+   `**Verify**` line is the gate command; a map may derive the task command from it, otherwise
+   that line serves both.
    - **PASS** → before promoting, run the **documentation-standard self-check** below on the files
      this task changed. Missing documentation and leaked plan references are invisible to
      build+test, so a green verify is NOT sufficient — the self-check is a hard part of the

package/skills/git-commit/SKILL.md

@@ -14,7 +14,7 @@ A request to commit authorizes a local commit only. Push only when the user expl
 1. Resolve the repository root and inspect `git status --short`, staged/unstaged diffs, and recent commit style.
 2. If clean, report `nothing to commit` and stop.
 3. Inspect every untracked file. Stop and ask before staging likely secrets, credentials, build output, large binaries, or unrelated scratch files.
-4. Resolve the authoritative verification command from `AGENTS.md`, CodeOps plan Verify lines, or project manifests. Run it with output captured to a log under `$CODEOPS_TMPDIR` (fallback: the OS temp directory), never in the repository. On failure, report the failure tail and do not stage or commit.
+4. Resolve the authoritative verification command from `AGENTS.md`, CodeOps plan Verify lines, or project manifests. For a normal commit, a validated scoped `**Task verify**` command or the map's `task` gate may replace the full command; record the command and scope in the verification note. Run the full gate for a release, merge, or push commit, and whenever the staged diff touches shared, configuration, manifest, or test infrastructure. Never bypass hooks. Run with output captured to a log under `$CODEOPS_TMPDIR` (fallback: the OS temp directory), never in the repository. On failure, report the failure tail and do not stage or commit. The gate rules are in [_shared/test-selection.md](../../_shared/test-selection.md).
 5. Stage deliberately by explicit paths or coherent groups. Avoid `git add .` when the working directory may be a monorepo subtree or unrelated changes exist.
 6. Review `git diff --cached --check`, the staged stat, and the staged diff. Ensure the commit contains one coherent purpose and preserves unrelated user changes.
 7. Write a Conventional Commit message to a temporary file under `$CODEOPS_TMPDIR` (fallback: the OS temp directory) and commit with `git commit -F`. Never use an inline multiline message.

package/skills/make-plan/SKILL.md

@@ -233,9 +233,16 @@ decisions remain user-owned.
 3b. Every addition accepted through scope exploration must also carry its owning `SE-*`
     back-reference. `Defer`, `Discard`, and `Superseded` entries never produce plan tasks.
 4. `07-testing-strategy.md` must contain concrete **Specification Test Cases (ST-*)** with input→expected-output pairs, each traced to a requirement / spec doc / AR entry. Expectations come from the SPEC, never from imagined implementation behavior.
-4b. **Confirm the verify command once.** The command that fills every Verify line comes from the
-   project's AGENTS.md or manifests — state what you detected and have the user confirm it (an AR
-   entry like any decision). If nothing is detectable, ask — **never invent a command**.
+4b. **Confirm the verify commands once.** The gate command that fills every `**Verify**` /
+   `**Verify (gate)**` line comes from the project's AGENTS.md or manifests — state what you
+   detected and have the user confirm it (an AR entry like any decision). If nothing is
+   detectable, ask — **never invent a command**. Optionally record a `**Task verify**` scoped
+   command for task/commit verification. Run the task command once during authoring, record the
+   observed test count as `**Task verify evidence**: <N> tests observed, <date>`, and reject a
+   command that runs zero tests. Record the plan's declared spec file(s) so exec-plan can
+   pass them with `--include`. With no map and no scoped command, generate exactly today's plan
+   (one `**Verify**` line). The canonical gate ladder is
+   [../../_shared/test-selection.md](../../_shared/test-selection.md).
 5. `99-execution-plan.md` must structure every feature phase with the mandatory three-session ordering (Spec Tests → Implementation → Impl Tests & Hardening), carrying each phase's tasks as a **single checkbox list** — the plan's single source of truth for progress; a task line appears exactly once in the document. The full ordering rules are in [templates.md](templates.md).
 6. If you discover a NEW ambiguity while writing, STOP immediately and add it to the register.
    In normal mode get the user's decision; with active auto-design resolve an eligible technical

package/skills/make-plan/quality-checklist.md

@@ -44,6 +44,10 @@ Run this before finalizing the plan documents. The **Specification-First Testing
 - [ ] Spec test tasks reference ST-cases from `07-testing-strategy.md`
 - [ ] Spec test and impl test files use separate naming conventions (`*.spec.test.*` and `*.impl.test.*`)
 - [ ] A red-phase verification task exists in the execution plan (verify spec tests fail before implementation)
+- [ ] `07-testing-strategy.md` carries the optional `Test slices` table, or records `N/A — full verify only`
+- [ ] Every ST-case maps to a test slice or a validated scoped command
+- [ ] Every slice has a task-tier test and a release/acceptance group or recorded acceptance reason
+- [ ] The full gate command is recorded; a `**Task verify**` command, when present, proved a nonzero test count
 
 ## ✅ No Dead Code
 - [ ] No unused parameters (except interface contracts, overrides, and framework-required signatures)

package/skills/make-plan/templates.md

@@ -312,6 +312,21 @@ With no RD upstream, `01-requirements.md` IS the owning requirements doc:
 - Adjust targets per project in `01-requirements.md` (an AR-referenced decision) — never
   silently.
 
+## Test Slices & Groups (optional)
+
+> Fill this table when the project has a test map (`codeops/test-map.json` or
+> `codeops/test-map/`) or when the plan records a validated `**Task verify**` scoped command.
+> For a map-less project with no scoped command, write `N/A — full verify only` and keep the
+> existing plan shape.
+
+| Slice | Tier | Test Files | Sources | Depends On | Gate |
+| ----- | ---- | ---------- | ------- | ---------- | ---- |
+| [slice] | task | [paths] | [paths] | [slice/group] | task |
+| [slice] | release | [paths] | [paths] | [task group] | release |
+
+Every slice needs a task-tier test. Every slice needs a release or acceptance group, or a
+recorded manual/external/N/A acceptance reason.
+
 ## 🚨 Specification Test Cases (MANDATORY — NON-NEGOTIABLE)
 
 > These test cases are derived EXCLUSIVELY from requirements (`01-requirements.md`),
@@ -478,7 +493,10 @@ task-size criteria in [quality-checklist.md](quality-checklist.md))
 - [ ] Deliverable 1
 - [ ] All verification passing
 
-**Verify**: [Project's verify command from AGENTS.md / detected conventions]
+**Test slices**: [optional — slice/tier summary, or `N/A — full verify only`]
+**Task verify**: [optional validated scoped command and observed test count, or omit]
+**Verify (gate)**: [full project verify command from AGENTS.md / detected conventions]
+**Verify**: [legacy alias — same as the gate command when only one line is used]
 
 ---
 

package/skills/organize-tests/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: organize-tests
+description: Build or refresh a test-impact map for an existing project so local development runs only affected feature-slice test groups while CI keeps a full-suite release gate. Use for organize tests, group tests, test impact map, speed up tests, affected-only testing, test selection, or test-suite health. Detects runners and language adapters, inventories tests, proposes feature slices and tiered groups, runs shadow-mode adoption, updates AGENTS.md and CI additively, and audits drift. Never edits tests or weakens the full gate.
+---
+
+# Organize Tests
+
+`organize-tests` adopts opt-in test-impact selection in an existing project. It
+reads the project, proposes feature-slice groups and language adapters, previews
+every write, proves the selection in shadow mode, and only then applies the map.
+The full suite remains the release, acceptance, and CI gate.
+
+The skill is additive. It never edits, moves, deletes, or weakens a test. It
+never removes a CI job or bypasses the full gate. A project can stop after any
+preview and keep its current verification flow.
+
+## Modes
+
+| Mode | Behavior |
+| --- | --- |
+| default | Analyze, propose, preview, ask, then apply |
+| `--dry-run` | Analysis and proposal only; write nothing |
+| `--check` | Read-only validation and drift report |
+| `--refresh` | Update globs, edges, and timings; preserve manual group edits |
+| `--shadow` | Run the selected and full suites, write evidence, never enable automatically |
+| `--audit` | Report orphans, overlaps, slow groups, never-selected groups, and flaky candidates |
+| `--no-ci` | Skip the CI patch; map and AGENTS block only |
+| `--custom` | Force the custom-command adapter for an unsupported language |
+
+## Protocol
+
+### 1. Preflight
+
+Resolve the Git root, layout, existing map, manifests, runner configuration, CI
+files, and `AGENTS.md` managed blocks. Refuse unsafe writes: a symlinked or
+non-regular map, a malformed existing map, or a project with no full command.
+Never overwrite a map the skill does not own.
+
+### 2. Inventory tests
+
+Enumerate test units with the project's native discovery. Record the owning
+source path, the test path or target, and the observed test count. The recipes
+are in [references/analysis-protocol.md](references/analysis-protocol.md) and
+[references/language-adapters.md](references/language-adapters.md).
+
+### 3. Propose slices
+
+Use feature slices for business applications, pipeline stages for compilers,
+packages for libraries, and workspace packages for monorepos. One test unit owns
+exactly one group. Target 5–15 groups; split a slice that is slow or spans
+unrelated behavior.
+
+### 4. Derive dependencies
+
+Use the native graph (Cargo metadata, Go list, Bazel/Nx, Maven/Gradle modules)
+or production imports. `dependsOn` points upstream: a group lists what it needs.
+A change selects its own group and downstream dependents, never upstream
+providers. Never let shared test utilities pull unrelated groups together; when
+uncertain, add an edge or make the group `alwaysRun`.
+
+### 5. Assign tiers
+
+`task` is the fast unit, component, or contract tier. `phase` covers API, DB,
+and integration behavior. `release` covers end-to-end and acceptance behavior.
+Every slice needs at least one task-tier group and either a release/acceptance
+group or a per-slice acceptance record:
+
+```json
+{ "acceptance": { "mode": "manual", "reason": "approved by the owning team" } }
+```
+
+Valid modes are `manual`, `external`, and `na`. Every record needs a reason.
+
+### 6. Synthesize commands
+
+Build argv commands per adapter. Run each candidate once and record the observed
+test count; a command that runs zero tests is invalid. Resolve `{tests}` to the
+group's full test set. For target-based runners (Rust, Go, C/C++), omit `tests`
+when the command performs its own discovery; ownership then comes from `sources`
+plus the command smoke test. Add `policy.prSmoke` groups for the PR gate and a
+`requirements` probe for every `requires` name.
+
+### 7. Preview
+
+Show a summary table (slice, tier, tests, sources, dependsOn, duration, command),
+file coverage, the map layout, the AGENTS block diff, and the CI diff. On a
+non-integration branch, ask before writing.
+
+### 8. Shadow
+
+Run the selected groups, then the full suite, regardless of the first result.
+Adoption requires zero missed failures. An escaped failure refuses adoption and
+is reported with the group and failure tail. Never enable the map from shadow
+mode. See [references/shadow-mode.md](references/shadow-mode.md).
+
+### 9. Apply with staging
+
+Render the map, policy, fragments, optional wrapper, `CODEOPS-TESTING` block,
+CI diff, and package scripts in a staging area under `$CODEOPS_TMPDIR`. Validate
+the map and every diff. Back up existing files, write in a fixed order, and
+restore every prior file on failure. Never leave a partial map or a half-updated
+block. Validate the staged result with `check --strict`.
+
+### 10. Verify
+
+Run `check`, one real selection, the full suite once, and `npm pack` or the
+project build as applicable. Record the evidence. When `--metrics` is enabled,
+emit only content-free fields: gate, selected/total, budget status, fallback
+reason, and map hash. Never include test names, paths, output, or user text.
+
+### 11. Refresh/audit
+
+`--refresh` updates globs, edges, and timings without discarding manual groups or
+owner fields. `--check` reports drift. `--audit` reports orphans, overlaps,
+slices without a task tier, slow groups, never-selected groups, and flaky
+candidates. The health rules are in
+[references/map-health.md](references/map-health.md).
+
+## AGENTS.md testing block
+
+Only `organize-tests` writes the `<!-- CODEOPS-TESTING:START -->` /
+`<!-- CODEOPS-TESTING:END -->` block. `analyze-project` detects it, preserves it
+byte-for-byte, and warns when it is missing or stale; it never renders the block.
+The contract, the optional `Test slices` table (slice, tier, tests, sources,
+gate), and the wrapper guidance are in
+[references/agents-testing-block.md](references/agents-testing-block.md).
+
+## CI patch rules
+
+- Add a required full gate for release, acceptance, and package branches.
+- Add an optional affected PR job behind a stable `verify` aggregator.
+- Add nightly only when the project wants it; use the change marker.
+- Add provenance only when the project builds a deployable artifact.
+- Suggest a `.github/CODEOWNERS` entry for `codeops/test-map/**`; on approval,
+  add it without touching existing ownership rules.
+- Preserve existing jobs, caching, toolchain setup, and branch filters. Preview
+  every diff and never remove a job.
+- Never use `pull_request_target` with fork code or expose secrets to fork PRs.
+
+The advisory templates are in
+[references/ci-github-actions.md](references/ci-github-actions.md) and
+[references/project-wrapper.md](references/project-wrapper.md). They are
+previewed like every other change and are never applied automatically.
+
+## Safety rules
+
+- Never edit, move, delete, or weaken a test.
+- Never remove a CI job or weaken the full gate.
+- No adoption on shadow misses.
+- Refuse malformed or symlinked maps and paths outside the root.
+- Stage and validate every write; restore prior files on failure.
+- Idempotent refresh; preserve manual group edits and owner fields.
+- No map write without preview and approval on non-integration branches.
+
+## Output contract
+
+The preview names the map layout, each slice and tier, the command per group, the
+file coverage, and every file that will change. The shadow report records the
+verdict, selected groups, selected result, full result, escaped groups, and
+`enabled: false`. The apply report lists the written files and the validation
+result. The audit report names every finding with a path or group ID.
+
+---
+
+> **Workspace hygiene (non-negotiable):** put every temporary artifact this run creates in
+> `$CODEOPS_TMPDIR` (fallback: the OS temp directory), never in the repository, and delete them
+> all before reporting completion. Never delete user files, versioned artifacts, worktrees, or
+> another session's temporary files. Full rules:
+> [_shared/workspace-hygiene.md](../../_shared/workspace-hygiene.md).

package/skills/organize-tests/references/agents-testing-block.md

@@ -0,0 +1,80 @@
+# AGENTS.md Testing Block
+
+> **CodeOps Artifact Schema**: 1
+
+The testing block tells an agent how to verify this project without re-reading
+the map. It lives inside the existing `CODEOPS-PROJECT` managed block and is
+owned by one writer.
+
+## Ownership
+
+`organize-tests` is the **sole writer** of the block. `analyze-project` detects
+the block and preserves it byte-for-byte on every refresh; it never renders or
+overwrites it, and it warns when the block is missing or stale. A project that
+has no map is not given a block by `analyze-project`.
+
+The block markers are:
+
+```markdown
+<!-- CODEOPS-TESTING:START -->
+<!-- CODEOPS-TESTING:END -->
+```
+
+## With a map
+
+```markdown
+<!-- CODEOPS-TESTING:START -->
+- Test map: `codeops/test-map/` (8 groups, 3 slices)
+- Task verify: `npm run verify:task` (affected task-tier groups + dependents)
+- Phase verify: `npm run verify:phase` (task + phase tiers)
+- Gate verify: `npm run verify` (full suite; release/acceptance/CI)
+- Map check: `npm run test:map:check`
+- Last map check: 2026-11-11 23:36
+<!-- CODEOPS-TESTING:END -->
+```
+
+The commands are the project's real commands. Never invent a script name; if the
+project does not want a wrapper, point at the CLI command instead.
+
+## Optional Test slices table
+
+A project that wants a map-less reference may add a human-readable table after
+the commands. It is informational; the map remains the source of truth.
+
+| Slice | Tier | Tests | Sources | Gate |
+| --- | --- | --- | --- | --- |
+| `billing.invoice-dialog` | task | `web/billing/**/*.test.tsx` | `web/billing/**` | task |
+| `billing.invoice-dialog` | release | `tests/e2e/billing/**` | `web/billing/**` | release |
+| `shared.auth` | task | `shared/auth/**/*.test.ts` | `shared/auth/**` | always-run |
+
+The table columns are slice, tier, tests, sources, and gate. Keep it short; a
+large table belongs in the map, not in `AGENTS.md`.
+
+## Without a map
+
+```markdown
+<!-- CODEOPS-TESTING:START -->
+- Testing: full suite only (no test map)
+- Gate verify: `npm run verify`
+<!-- CODEOPS-TESTING:END -->
+```
+
+The no-map text preserves today's behavior. `analyze-project` leaves an existing
+no-map block untouched.
+
+## Refresh rules
+
+- Replace only the block contents; preserve surrounding managed and
+  hand-authored text byte-for-byte.
+- Keep exactly one block; stop on duplicate or reversed markers and name the
+  manual fix.
+- Update `Last map check` only after a successful `check`.
+- Write with the file's dominant line ending; keep exactly one block; fail without writing on duplicate or reversed markers.
+- Never put secrets, absolute machine paths, or test output in the block.
+
+## Wrapper guidance
+
+A thin project wrapper is optional. If the project wants npm scripts, generate a
+small file that calls the plugin CLI with the project's map path and forwards
+arguments. The wrapper contains no selection logic; it must not grow into a
+second implementation. Record the wrapper path in the block.

package/skills/organize-tests/references/analysis-protocol.md

@@ -0,0 +1,94 @@
+# Analysis and Inventory Protocol
+
+> **CodeOps Artifact Schema**: 1
+
+This reference describes how `organize-tests` turns a repository into a proposed
+test map. It is evidence-first: every group traces to a real source path, a real
+test unit, and a command that was observed to run at least one test.
+
+## 1. Project reconnaissance
+
+Read, without writing:
+
+- the Git root and current branch;
+- `codeops/test-map.json` and `codeops/test-map/` when present;
+- manifests and lockfiles (`package.json`, `Cargo.toml`, `go.mod`,
+  `pyproject.toml`, `pom.xml`, `build.gradle`, `*.sln`, `CMakeLists.txt`);
+- runner configuration (`vitest.config.*`, `jest.config.*`, `pytest.ini`,
+  `nextest.toml`, CTest files);
+- CI workflows, especially the full verify job;
+- the `CODEOPS-PROJECT` and `CODEOPS-TESTING` blocks in `AGENTS.md`.
+
+Record the project's full verify command and the exact file or script that
+defines it. A missing full command stops adoption.
+
+## 2. Test inventory
+
+For each test unit, record:
+
+| Field | Meaning |
+| --- | --- |
+| `test` | Repo-relative file path, target name, or test ID |
+| `source` | The production path or target that owns it |
+| `runner` | Detected adapter |
+| `count` | Observed number of tests |
+| `durationSec` | Observed or estimated duration |
+
+Use native discovery where possible. Do not guess a test count; run the
+candidate command and read the reported number.
+
+## 3. Slice proposal
+
+Group units by the feature or pipeline stage a developer changes, not by folder
+alone:
+
+- business app: dialog, invoice, inventory, auth;
+- compiler: lexer, parser, codegen, assembler, linker, e2e;
+- library: public API, adapters, compatibility;
+- monorepo: workspace package boundaries.
+
+One unit belongs to exactly one group. A slice carries one or more tiers of the
+same feature. Split a slice when its task tier exceeds the budget or when its
+tests cover unrelated behavior.
+
+## 4. Dependency graph
+
+Collect edges from the native graph first. Fall back to production imports, not
+test imports. `dependsOn` lists upstream groups: a parser group is upstream of a
+codegen group. Selection walks reverse edges, so changing the parser selects
+codegen and its dependents, while changing codegen does not select the parser.
+
+Shared test utilities are not a dependency shortcut. If a helper is used by
+unrelated slices, keep it in a narrow shared group or mark the consumers
+`alwaysRun`; never merge unrelated slices to satisfy the helper.
+
+## 5. Command synthesis
+
+Build an argv command per group. Verify it:
+
+1. run it once on the current tree;
+2. confirm it exits zero;
+3. confirm the reported test count is greater than zero;
+4. confirm it runs a subset, not the whole suite.
+
+Record the count in the preview. A zero-test command is rejected. A command that
+runs the whole suite defeats the purpose and is moved back to the full gate.
+
+## 6. Preview contents
+
+The preview must show:
+
+- the chosen layout (single file or policy plus fragments);
+- every slice, tier, source glob, test glob, dependency, and duration;
+- the exact command per group and its observed count;
+- files that will be created or changed;
+- the AGENTS block diff and the CI diff;
+- validation findings from the staged map.
+
+Nothing is written before the preview is accepted.
+
+## 7. Evidence to keep
+
+Record the observed counts, the shadow verdict, the `check --strict` result, and
+the date of the last map check. Evidence lives in the plan or the adoption
+report, not in shipped source comments.

package/skills/organize-tests/references/ci-github-actions.md

@@ -0,0 +1,178 @@
+# GitHub Actions Test-Selection Templates
+
+> **CodeOps Artifact Schema**: 1
+
+These templates are advisory. `organize-tests` previews every diff and never
+removes an existing job. A project can keep its current full gate and adopt only
+the map, or adopt the affected PR job later.
+
+## Shape
+
+```text
+PR:
+  plan(affected) -> test shards -> verify aggregator (required)
+
+release/** / hotfix/** / v* tag:
+  full gate -> build artifact -> package -> provenance -> deploy
+
+acceptance/**:
+  full gate + acceptance groups -> provenance
+```
+
+## Affected plan and shards
+
+```yaml
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.plan.outputs.matrix }}
+      mode: ${{ steps.plan.outputs.mode }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - run: npm ci --ignore-scripts
+      - id: plan
+        run: node bin/codeops-test.mjs plan --gate pr --since "origin/${{ github.base_ref }}" --json > plan.json
+      - run: echo "matrix=$(jq -c .matrix plan.json)" >> "$GITHUB_OUTPUT"
+      - run: echo "mode=$(jq -r .mode plan.json)" >> "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: test-plan
+          path: plan.json
+
+  test:
+    needs: plan
+    if: needs.plan.outputs.mode == 'groups' && needs.plan.outputs.matrix != '{"include":[]}'
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm ci --ignore-scripts
+      - uses: actions/download-artifact@v4
+        with:
+          name: test-plan
+      - run: node bin/codeops-test.mjs run --selection plan.json --group "${{ matrix.group }}"
+```
+
+The plan has four modes: `groups`, `full`, `none`, and `skip`. Every mode
+returns a matrix object. `none` and `skip` use an empty matrix. A full run is a
+separate job, never a fake group entry, so `run --group full` remains a usage
+error.
+
+```yaml
+  full:
+    needs: plan
+    if: needs.plan.outputs.mode == 'full'
+    uses: ./.github/workflows/verify-full.yml
+
+  check:
+    needs: plan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm ci --ignore-scripts
+      - run: node bin/codeops-test.mjs check --strict
+
+  verify:
+    needs: [plan, test, full, check]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          test "${{ needs.plan.result }}" = "success"
+          test "${{ needs.check.result }}" = "success"
+          if [ "${{ needs.plan.outputs.mode }}" = "groups" ]; then
+            test "${{ needs.test.result }}" = "success"
+          fi
+          if [ "${{ needs.plan.outputs.mode }}" = "full" ]; then
+            test "${{ needs.full.result }}" = "success"
+          fi
+```
+
+The stable `verify` job is the required branch-protection check. Dynamic matrix
+names are never required checks. `check --strict` runs beside it so a malformed
+map stays visible even when selection falls back to full.
+
+## Release and acceptance
+
+Release and acceptance always run the full gate. Build the artifact only after
+the gate, or build first and let the gate consume the artifact.
+
+```yaml
+  verify:
+    uses: ./.github/workflows/verify-full.yml
+
+  package:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm ci --ignore-scripts
+      - run: npm run build
+      - run: node bin/codeops-test.mjs provenance write --gate release --artifact dist/app.tar.gz --source-commit "$GITHUB_SHA" --record release.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-evidence
+          path: release.json
+```
+
+`--source-commit` records the commit the full gate tested. When the gate ran on
+source, the artifact must be reproducible; `provenance verify` fails on a
+different digest or source commit. Acceptance uses `--gate acceptance` and
+records the manual or external result.
+
+## Nightly
+
+```yaml
+name: Nightly Full
+on:
+  schedule: [{ cron: "0 3 * * *" }]
+  workflow_dispatch:
+concurrency:
+  group: nightly-full
+  cancel-in-progress: false
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    outputs:
+      run_full: ${{ steps.plan.outputs.run_full }}
+    steps:
+      - uses: actions/checkout@v7
+        with: { fetch-depth: 0 }
+      - run: npm ci --ignore-scripts
+      - id: plan
+        env:
+          CODEOPS_LAST_FULL_SHA: ${{ vars.CODEOPS_LAST_FULL_SHA }}
+        run: node bin/codeops-test.mjs plan --gate nightly --last-full-sha "$CODEOPS_LAST_FULL_SHA" --json > plan.json
+      - run: echo "run_full=$(jq -r '.mode != "skip"' plan.json)" >> "$GITHUB_OUTPUT"
+  full:
+    needs: plan
+    if: needs.plan.outputs.run_full == 'true'
+    uses: ./.github/workflows/verify-full.yml
+  update-marker:
+    needs: full
+    if: needs.full.result == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - run: gh variable set CODEOPS_LAST_FULL_SHA --body "$GITHUB_SHA"
+        env:
+          GH_TOKEN: ${{ github.token }}
+```
+
+The marker updates only after a successful full run. Never update it from a
+failed or skipped job.
+
+## Governance
+
+- Protect `codeops/test-map/**` with a `CODEOWNERS` entry; map changes are
+  reviewed like CI changes.
+- Use `pull_request`, never `pull_request_target` with fork code. The map
+  contains commands and must be treated as code.
+- Preserve existing caching, toolchain setup, permissions, and branch filters.
+- Do not add a path filter that lets release or acceptance skip the full gate.