opencode-codeops 2.4.0 → 2.6.0

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.

package/skills/organize-tests/references/language-adapters.md

@@ -0,0 +1,54 @@
+# Language Adapter Recipes
+
+> **CodeOps Artifact Schema**: 1
+
+The selector core is language-neutral. Each adapter is only a discovery method
+and an argv command stored in the map. Never add a language branch to the core.
+
+| Ecosystem | Natural unit | Discovery | Subset command |
+| --- | --- | --- | --- |
+| Node `node --test` | test file | file globs | `node --test {tests}` |
+| Vitest | test file | config/project | `npx vitest run {tests}` |
+| Jest | test file | config | `npx jest --runTestsByPath {tests}` |
+| Rust | crate or target | `cargo metadata` | `cargo test -p <crate> --lib --tests` |
+| Python | file or node ID | `pytest --collect-only` | `python3 -m pytest {tests}` |
+| Go | package | `go list ./...` | `go test ./pkg/...` |
+| JVM | class or package | Gradle/Maven tasks | `./gradlew test --tests com.example.core.*` |
+| .NET | project or class | `dotnet test --list-tests` | `dotnet test --filter FullyQualifiedName~Core` |
+| C/C++ | binary or target | `ctest -N`, Bazel query | `ctest -R ^core_`, Bazel target |
+| Ruby | file | runner config | `rspec {files}` |
+| PHP | file | runner config | `phpunit {files}` |
+| Custom | project unit | project command | project argv |
+
+## Target-based groups
+
+Rust unit tests are inline in source, Go tests are package-level, and C/C++
+tests are binary/target-level. These runners discover their own unit, so a
+target-based group may omit `tests`. Ownership is then validated through
+`sources` plus a smoke run of the command; the group is exempt from file-glob
+ownership checks.
+
+A target-based command must still prove a nonzero test count. The preview records
+that count.
+
+## File-based groups
+
+Node, Vitest, Jest, Python, Ruby, and PHP groups use `tests` globs. `{tests}`
+expands to every file the group owns, independent of the change set. A
+source-only change therefore still runs the group's whole test set.
+
+## Custom adapter
+
+Use `--custom` when no recipe fits. Ask for both commands:
+
+- the full verify command;
+- the subset command, as argv tokens, with `{tests}` where file paths belong.
+
+Run the subset once and record the count. If the command cannot run a subset,
+keep the project on the full gate; do not invent a selector.
+
+## Cross-language projects
+
+Use one fragment per ecosystem and a shared `policy.json`. The full command may
+be a single umbrella script or an array of argv commands. Never let one
+ecosystem's group command run another ecosystem's suite.

package/skills/organize-tests/references/map-health.md

@@ -0,0 +1,47 @@
+# Map Health and Audit
+
+> **CodeOps Artifact Schema**: 1
+
+A map can be valid JSON and still be unhealthy. The audit looks for drift and
+ownership defects that make selection quietly less useful.
+
+## Checks
+
+| Finding | Meaning | Action |
+| --- | --- | --- |
+| `map.orphan-test` | A test under a test root belongs to no group | Add it to an owning group, or record an explicit ignore/acceptance decision; the skill never deletes a test |
+| `map.overlap` | A test belongs to more than one group | Give it exactly one owner |
+| `map.unknown-source` | A source path is owned, full-on, or ignored by nothing | Add ownership, a full-on rule, or a documented ignore |
+| `map.slice-no-task` | A slice has no fast task tier | Add a task group or split the slice |
+| `map.slice-no-release` | A slice has no release/acceptance path | Add a release group or a per-slice acceptance record |
+| `map.group.slow` | A task group estimates above 180 s | Split it or move slow tests to a higher tier |
+| `map.empty-group` | A file-based group matches no tracked test | Fix the glob or remove the group |
+| never selected | A group has never run in recorded evidence | Check its sources and dependency edges |
+| flaky candidate | A group fails intermittently | Stabilize the test; do not hide it in a higher tier |
+
+A file is a test candidate when a group's `tests` glob claims it or its name follows a
+test convention (`.test.`, `.spec.`, `_test.`, `test_*`, `*Test`, or a `.rs` file under a
+test root). Fixtures and helpers under a test root are not orphan tests.
+
+## Strict mode
+
+`check --strict` promotes drift warnings to errors and exits 4. Malformed map
+rules still exit 3. Release and acceptance CI runs strict mode so a stale map
+cannot silently widen selection.
+
+## Refresh
+
+`--refresh` may update globs, dependency edges, and timings. It preserves manual
+group edits, owner fields, and acceptance records. It never renames an ID; a
+renamed group is a new group with a new owner decision.
+
+## Slow groups
+
+A slow task tier is a design smell, not a selector failure. Split the slice or
+move the slow test to `phase` or `release`. Never drop the test from the map to
+make the budget green.
+
+## Reporting
+
+Every audit finding names the path or group ID and the rule code. The report is
+read-only; the user decides whether to refresh, split, or accept the finding.

package/skills/organize-tests/references/project-wrapper.md

@@ -0,0 +1,72 @@
+# Project Wrapper Guidance
+
+> **CodeOps Artifact Schema**: 1
+
+A wrapper is optional. It gives a project short npm scripts without copying
+selector logic. The wrapper is a thin adapter over the plugin CLI.
+
+## Rules
+
+- No selection logic in the wrapper.
+- No language detection, glob parsing, or command rewriting.
+- Forward every argument unchanged.
+- Resolve the project root and map path once, then call the CLI.
+- Keep the file small enough to review in one screen.
+
+## Example
+
+`scripts/codeops-test.mjs`:
+
+```js
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { dirname, join } from "node:path"
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..")
+const cli = process.env.CODEOPS_TEST_CLI ?? "codeops-test"
+const result = spawnSync(cli, process.argv.slice(2), {
+  cwd: root,
+  stdio: "inherit",
+  shell: false,
+})
+process.exitCode = result.status ?? 1
+```
+
+Package scripts:
+
+```json
+{
+  "scripts": {
+    "verify:task": "node scripts/codeops-test.mjs run --gate task",
+    "verify:phase": "node scripts/codeops-test.mjs run --gate phase",
+    "test:map:check": "node scripts/codeops-test.mjs check --strict"
+  }
+}
+```
+
+The full verify command stays the project's existing command:
+
+```json
+{
+  "scripts": {
+    "verify": "npm run typecheck && npm run test"
+  }
+}
+```
+
+## When not to use a wrapper
+
+A project may call `node bin/codeops-test.mjs` or the installed `codeops-test`
+binary directly. The AGENTS testing block names whichever command is real. Never
+invent a script name that does not exist.
+
+## Verification
+
+After adding a wrapper, run:
+
+1. `npm run test:map:check` — the map is valid.
+2. `npm run verify:task` with one real change — a nonzero selected set runs.
+3. `npm run verify` — the full gate still passes.
+
+Record the observed counts in the adoption evidence.

package/skills/organize-tests/references/shadow-mode.md

@@ -0,0 +1,60 @@
+# Shadow Adoption
+
+> **CodeOps Artifact Schema**: 1
+
+Shadow mode proves that a proposed map selects every test the full suite would
+fail. It is evidence, not a switch. Adoption requires zero missed failures; never enable the map from a single run.
+
+## Procedure
+
+1. Compute the selected set for the current diff with an explicit baseline.
+2. Run the selected groups with `--no-fail-fast`; capture every result.
+3. Run the full command regardless of the selected result.
+4. Compare the two results.
+5. Write the evidence record and report the verdict.
+6. Never enable the map automatically; a user or the skill decides after
+   reviewing the evidence.
+
+## Verdicts
+
+| Selected | Full | Verdict | Action |
+| --- | --- | --- | --- |
+| pass | pass | `zero-missed` | Candidate for adoption after review |
+| pass | fail | `escaped` | Refuse adoption; name the escaped failure |
+| fail | pass | `selected-failure` | Refuse adoption; fix selection or flake |
+| fail | fail | `both-failed` | No adoption signal; report both tails |
+
+The skill must refuse adoption on an escaped verdict. An `escaped` verdict is the dangerous case: the selected slice was green while
+the full suite was red. The report must name the escaping group and include the
+full failure tail. Do not explain it away as flaky without evidence.
+
+## Evidence shape
+
+```json
+{
+  "verdict": "zero-missed",
+  "gate": "pr",
+  "changed": ["src/a/dialog.ts"],
+  "mapHash": "<sha256>",
+  "selected": ["a.unit"],
+  "selectedResult": "passed",
+  "fullResult": "passed",
+  "escaped": [],
+  "enabled": false
+}
+```
+
+The record contains no test output, secrets, or environment values. Failure
+tails may appear in the human report but not in a committed map.
+
+## Repetition
+
+Run shadow mode on several real change sets, including:
+
+- a single-slice change;
+- a shared-contract change;
+- a change that should force full;
+- a docs-only change.
+
+A single green shadow run is not enough to prove a selector. Adopt only after
+the project has seen zero missed failures across representative changes.

package/skills/setup-codeops/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: setup-codeops
 description: >-
-  Sets up or upgrades CodeOps in the current git repo. It scaffolds a fresh nested codeops/ layout, auto-migrates a flat requirements/ + plans/ layout, and detects obsolete traceability.json workflow-state graphs in an existing nested project. Use when the user says "setup-codeops", "/setup-codeops", "set up codeops", "initialize codeops", "upgrade existing codeops", "migrate to the nested layout", or "scaffold the codeops structure". Supports --dry-run and unattended --yes. Every migration previews deterministically, refuses unsafe or ambiguous apply, requires clean Git state for writes, and is idempotent. setup-codeops is the SOLE writer of the layout marker.
+  Sets up or upgrades CodeOps in the current git repo. It scaffolds a fresh nested codeops/ layout, auto-migrates a flat requirements/ + plans/ layout, and detects obsolete traceability.json workflow-state graphs in an existing nested project. Use when the user says "setup-codeops", "/setup-codeops", "set up codeops", "initialize codeops", "upgrade existing codeops", "migrate to the nested layout", or "scaffold the codeops structure". Supports --dry-run, unattended --yes, and --enable-discovery/--disable-discovery for existing projects. Every migration previews deterministically, refuses unsafe or ambiguous apply, requires clean Git state for writes, and is idempotent. setup-codeops is the SOLE writer of the layout marker.
 ---
 
 # CodeOps Layout Setup (`setup-codeops`)
@@ -21,8 +21,9 @@ it is the single source of truth for the layout. Do not re-encode paths here.
 - This skill sets up the *structure*. It never authors requirements, plans, or roadmaps — that is
   `make-requirements` / `make-plan` / `roadmap`, which then resolve paths via the convention doc.
 - A fresh scaffold enables Discovery by default (`discovery.enabled: true`,
-  `chatMaxQuestions: 3`). Existing projects keep their current setting; enable it with
-  `analyze-project --with-discovery` or by adding the setting manually.
+  `chatMaxQuestions: 3`). Existing projects can toggle it with
+  `setup-codeops --enable-discovery` / `--disable-discovery`; `analyze-project --with-discovery`
+  remains available for the same config change with guidance refresh.
 
 ## Dispatch — detect repo state, then branch
 
@@ -59,6 +60,31 @@ fresh scaffold should live in version control) and suggest `git init` first.
 | *(none)* | Interactive: scaffold creates the skeleton; either migration previews then asks for one confirmation before applying. |
 | `--dry-run` | Preview only — compute and show what would happen; change **nothing**. |
 | `--yes` | Apply an unblocked migration without confirmation, then verify it. Safety refusals still apply. |
+| `--enable-discovery` | Enable Discovery in an existing project without re-scaffolding. Preserves every other config key. |
+| `--disable-discovery` | Disable Discovery, keeping `chatMaxQuestions` and every other config key. |
+
+`--enable-discovery` and `--disable-discovery` are mutually exclusive. Validate that before the
+layout branch so a usage error never changes the repository.
+
+## Discovery toggle
+
+After the layout branch (no-op, migration, or fresh scaffold), apply exactly one discovery flag
+when present:
+
+```bash
+node "${CODEOPS_PLUGIN_ROOT}/scripts/discovery-toggle.mjs" --root . --enable-discovery
+node "${CODEOPS_PLUGIN_ROOT}/scripts/discovery-toggle.mjs" --root . --disable-discovery
+```
+
+Add `--dry-run` to preview. The script validates the JSON, refuses symlinked `codeops/` or
+`codeops/codeops.json`, preserves unrelated policy, and adds or removes the managed line
+`- Discovery: enabled — question rounds open in the local Discovery page` when the
+`CODEOPS-PROJECT` block exists. If `AGENTS.md` is absent or has no managed block, the config still
+changes; report that guidance should be refreshed with `analyze-project`.
+
+A fresh scaffold starts enabled. Passing `--disable-discovery` during scaffold turns it off; passing
+`--enable-discovery` is idempotent. Without either flag, an existing project keeps its current
+setting and a fresh scaffold stays enabled.
 
 ## Migration engines (delegation — do not re-implement)
 
@@ -86,6 +112,7 @@ deletion, and idempotency.
 
 - [scaffold.md](scaffold.md) — the minimal fresh-repo skeleton.
 - [migration.md](migration.md) — flat-layout and legacy workflow-state migration UX.
+- `scripts/discovery-toggle.mjs` — deterministic config and managed-line toggle.
 - [_shared/layout-convention.md](../../_shared/layout-convention.md) — the layout/path/ID/marker source of truth.
 
 ## Grounded Options & Recommendations

package/standards/coding-standards-full.md

@@ -71,6 +71,34 @@ These apply to all code I write unless this project's `AGENTS.md` overrides a sp
 
 # Testing standards
 
+## Prime directives for verification
+
+1. **Test-first is unchanged.** Specification tests are written before implementation and run
+   red, then green. Selection never changes this.
+2. **The inner loop runs the smallest safe verification slice.** With a valid map, a task runs the
+   selected feature-slice `task` groups plus fast static checks. Without a map, a plan's
+   `**Task verify**` command may provide the same scoped behavior; otherwise the full verify runs
+   as today.
+3. **The outer gate is always full.** The full verify runs at phase/plan completion, before
+   push/release, at acceptance, and in CI. A green slice is not a release signal.
+4. **Selection fails closed.** Unknown paths, shared infrastructure, manifests/lockfiles,
+   test-runner/config changes, CI changes, stale/invalid maps, and selector errors select the
+   full suite. No silent skips.
+5. **Spec tests are never skipped.** The feature's spec test file always runs, even if the map
+   would not select its group. The executor passes the plan's declared spec file(s) with
+   `--include`; the selector adds the owning group, or falls back to full if the spec file is
+   unowned.
+6. **Evidence is explicit.** Verification names the groups or scoped command used, what was
+   deferred, and the baseline. CI remains authoritative.
+
+**Conditional wording.** Run the project's full verify command before completing any task or
+committing, unless the project has a valid `codeops/test-map.json` or `codeops/test-map/`
+directory, or the plan records a validated `**Task verify**` scoped command. With either opt-in,
+the task-level verify may run the selected test groups plus the project's fast static checks, or
+the plan-scoped command. The full verify still runs at phase/plan completion, before push/merge,
+at acceptance, and in CI. Any selection error, unknown path, shared change, or stale map falls
+back to the full verify. The canonical protocol is `_shared/test-selection.md`.
+
 - **Run the project's verify command (build + test) before completing any task or committing.** No code is "done" while any test fails.
 - **Targeted vs. full:** iterate with targeted tests, but run the **full** verify before declaring completion.
 - **Maximum, granular coverage:** happy path, edge/boundary cases, error/invalid inputs, and integration — each test focused on one thing with a clear failure message.