opencode-codeops 2.4.0 → 2.6.0

package/scripts/discovery-toggle.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * Enable or disable Discovery in an existing CodeOps project.
+ *
+ * The toggle is deliberately small and deterministic: it edits only
+ * `codeops/codeops.json` and, when the managed block exists, the Discovery
+ * line in `AGENTS.md`. It refuses symlinks and malformed configuration, and
+ * preserves every unrelated key.
+ *
+ * @module discovery-toggle
+ */
+
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/** The managed AGENTS.md line for an enabled Discovery page. */
+export const DISCOVERY_LINE =
+  "- Discovery: enabled — question rounds open in the local Discovery page"
+
+const START_MARKER = "<!-- CODEOPS-PROJECT:START -->"
+const END_MARKER = "<!-- CODEOPS-PROJECT:END -->"
+
+/** A user-facing toggle failure. */
+export class DiscoveryToggleError extends Error {}
+
+/** True for a non-null, non-array object. */
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+/** Refuse a symlink or a missing regular file. */
+function assertRegularFile(path, label) {
+  if (!existsSync(path)) {
+    throw new DiscoveryToggleError(`${label} does not exist.`)
+  }
+  const stats = lstatSync(path)
+  if (stats.isSymbolicLink()) {
+    throw new DiscoveryToggleError(`${label} is a symlink; refusing to write through it.`)
+  }
+  if (!stats.isFile()) {
+    throw new DiscoveryToggleError(`${label} is not a regular file.`)
+  }
+}
+
+/** Refuse a symlinked codeops directory. */
+function assertDirectory(path, label) {
+  if (!existsSync(path)) {
+    throw new DiscoveryToggleError(`${label} does not exist; run setup-codeops first.`)
+  }
+  const stats = lstatSync(path)
+  if (stats.isSymbolicLink()) {
+    throw new DiscoveryToggleError(`${label} is a symlink; refusing to write through it.`)
+  }
+  if (!stats.isDirectory()) {
+    throw new DiscoveryToggleError(`${label} is not a directory.`)
+  }
+}
+
+/** Normalize a config's discovery object without discarding known keys. */
+function nextDiscovery(existing, enable) {
+  if (existing !== undefined && !isPlainObject(existing)) {
+    throw new DiscoveryToggleError("codeops/codeops.json has a malformed discovery object.")
+  }
+  const discovery = { ...(existing ?? {}) }
+  discovery.enabled = enable
+  if (enable && discovery.chatMaxQuestions === undefined) {
+    discovery.chatMaxQuestions = 3
+  }
+  if (
+    discovery.chatMaxQuestions !== undefined &&
+    (!Number.isInteger(discovery.chatMaxQuestions) || discovery.chatMaxQuestions < 0)
+  ) {
+    throw new DiscoveryToggleError("discovery.chatMaxQuestions must be a non-negative integer.")
+  }
+  return discovery
+}
+
+/** Add or remove the managed Discovery line inside an AGENTS.md managed block. */
+function updateAgents(text, enable) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n"
+  const lines = text.split(/\r?\n/)
+  const starts = lines
+    .map((line, index) => (line.trim() === START_MARKER ? index : -1))
+    .filter((index) => index >= 0)
+  const ends = lines
+    .map((line, index) => (line.trim() === END_MARKER ? index : -1))
+    .filter((index) => index >= 0)
+  if (starts.length !== 1 || ends.length !== 1 || starts[0] > ends[0]) {
+    return { status: "block-missing", changed: false, text }
+  }
+  const start = starts[0]
+  const end = ends[0]
+  const block = lines.slice(start, end + 1)
+  const existing = block.findIndex((line) => line.trim() === DISCOVERY_LINE)
+  if (enable) {
+    if (existing >= 0) return { status: "already-enabled", changed: false, text }
+    const anchor = block.findIndex((line) => line.trim().startsWith("- Specialist coverage:"))
+    if (anchor === -1) {
+      return { status: "anchor-missing", changed: false, text }
+    }
+    block.splice(anchor + 1, 0, DISCOVERY_LINE)
+  } else {
+    if (existing === -1) return { status: "already-disabled", changed: false, text }
+    block.splice(existing, 1)
+  }
+  lines.splice(start, end - start + 1, ...block)
+  return { status: enable ? "enabled" : "disabled", changed: true, text: lines.join(eol) }
+}
+
+/**
+ * Toggle Discovery for one project.
+ *
+ * @param {{ root?: string, enable: boolean, dryRun?: boolean }} options
+ * @returns {{ configPath: string, discovery: object, changed: boolean,
+ *   agents: string, dryRun: boolean }}
+ */
+export function toggleDiscovery(options) {
+  if (typeof options.enable !== "boolean") {
+    throw new DiscoveryToggleError("enable must be true or false.")
+  }
+  const root = resolve(options.root ?? process.cwd())
+  const dryRun = options.dryRun === true
+  const codeopsDir = join(root, "codeops")
+  assertDirectory(codeopsDir, "codeops/")
+  const configPath = join(codeopsDir, "codeops.json")
+  assertRegularFile(configPath, "codeops/codeops.json")
+
+  const original = readFileSync(configPath, "utf8")
+  let config
+  try {
+    config = JSON.parse(original)
+  } catch {
+    throw new DiscoveryToggleError("codeops/codeops.json is not valid JSON.")
+  }
+  if (!isPlainObject(config)) {
+    throw new DiscoveryToggleError("codeops/codeops.json must contain a JSON object.")
+  }
+  const discovery = nextDiscovery(config.discovery, options.enable)
+  const nextConfig = { ...config, discovery }
+  const nextText = JSON.stringify(nextConfig, null, 2) + "\n"
+  const configChanged = nextText !== original
+
+  const agentsPath = join(root, "AGENTS.md")
+  let agents = "missing"
+  let agentsText = null
+  let agentsChanged = false
+  if (existsSync(agentsPath)) {
+    const stats = lstatSync(agentsPath)
+    if (stats.isSymbolicLink()) {
+      agents = "symlink"
+    } else if (!stats.isFile()) {
+      agents = "not-a-file"
+    } else {
+      const result = updateAgents(readFileSync(agentsPath, "utf8"), options.enable)
+      agents = result.status
+      agentsChanged = result.changed
+      agentsText = result.text
+    }
+  }
+
+  if (!dryRun) {
+    if (configChanged) writeFileSync(configPath, nextText)
+    if (agentsChanged && agentsText !== null) writeFileSync(agentsPath, agentsText)
+  }
+
+  return {
+    configPath,
+    discovery,
+    changed: configChanged,
+    agents,
+    dryRun,
+  }
+}
+
+/** Print command usage. */
+function printUsage() {
+  console.log(`Toggle Discovery in an existing CodeOps project.
+
+Usage:
+  node scripts/discovery-toggle.mjs --root <repo> --enable-discovery [--dry-run]
+  node scripts/discovery-toggle.mjs --root <repo> --disable-discovery [--dry-run]
+
+Options:
+  --root <dir>          Repository root (defaults to the current directory)
+  --enable-discovery    Set discovery.enabled to true
+  --disable-discovery   Set discovery.enabled to false
+  --dry-run             Show the result without writing files
+  -h, --help            Show this help
+`)
+}
+
+/** Run the command line. */
+function main() {
+  const args = process.argv.slice(2)
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage()
+    return
+  }
+  const rootIndex = args.indexOf("--root")
+  const root = rootIndex >= 0 ? args[rootIndex + 1] : process.cwd()
+  if (root === undefined) {
+    throw new DiscoveryToggleError("--root requires a directory.")
+  }
+  const enable = args.includes("--enable-discovery")
+  const disable = args.includes("--disable-discovery")
+  if (enable === disable) {
+    throw new DiscoveryToggleError("Use exactly one of --enable-discovery or --disable-discovery.")
+  }
+  const result = toggleDiscovery({
+    root,
+    enable,
+    dryRun: args.includes("--dry-run"),
+  })
+  const action = enable ? "enabled" : "disabled"
+  console.log(
+    `${result.dryRun ? "[dry-run] " : ""}Discovery ${action} in ${result.configPath} ` +
+      `(chatMaxQuestions: ${result.discovery.chatMaxQuestions ?? "default 3"}).`,
+  )
+  console.log(`AGENTS.md: ${result.agents}.`)
+  if (result.dryRun && result.changed) {
+    console.log("No files were written.")
+  }
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (invokedDirectly) {
+  try {
+    main()
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}

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.
@@ -28,7 +35,7 @@ description: Analyze the current repository and create or refresh concise CodeOp
 
 ## Discovery switch
 
-`analyze-project` accepts `--with-discovery` and `--without-discovery`; passing both flags is a usage error. Both flags validate `codeops/codeops.json` against `schemas/codeops-config.schema.json` before changing anything: an invalid file stops the run with its schema errors and writes nothing (never discard malformed quality, routing, or metrics policy). Refuse to write when `codeops/` or `codeops/codeops.json` is a symlink or not a regular file; never write through a link.
+`analyze-project` accepts `--with-discovery` and `--without-discovery`; passing both flags is a usage error. Existing projects can also use `setup-codeops --enable-discovery` / `--disable-discovery` for the config-only toggle. Both flags validate `codeops/codeops.json` against `schemas/codeops-config.schema.json` before changing anything: an invalid file stops the run with its schema errors and writes nothing (never discard malformed quality, routing, or metrics policy). Refuse to write when `codeops/` or `codeops/codeops.json` is a symlink or not a regular file; never write through a link.
 
 - `--with-discovery`: set `discovery.enabled: true`, keeping every other key. When no file exists, create the minimal AR-35 file with the layout resolved from `_shared/layout-convention.md` (`nested` → `codeops`, `flat` → `.`):
   ```json

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).

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).