opencode-codeops 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.9.0 — 2026-10-04
+
+### Features
+
+- hygiene: require cleanup after every task with a temp safety net
+
+## 1.8.1 — 2026-10-04
+
+### Documentation
+
+- agents: refresh project guidance with specialist facts
+- plan: record ST-43 and final verification evidence
+- plan: add ST-44 for the ask-and-create acceptance path
+- plan: record ST-34 dispatch acceptance evidence
+
+### Fixes
+
+- test: broaden availability regression guard per re-review
+- docs: complete AR #27 availability correction per phase-4 review
+- docs: correct specialist availability per ST-35 observation
+
 ## 1.8.0 — 2026-10-04
 
 ### Documentation

package/README.md

@@ -136,6 +136,8 @@ These standards are active without any user action. They do not need to be copie
 
 The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.codeops.yml` directly — that file is managed exclusively by the `setup-codeops` skill — and if the installed skills version differs from the plugin version, so a stale install is visible.
 
+Every session also gets a workspace-hygiene guard: the plugin exports `CODEOPS_TMPDIR`, a per-session scratch directory under the OS temp directory. Skills and agents put temporary files there and delete them when the run completes; the plugin removes the directory when the session is deleted and sweeps directories abandoned by interrupted runs at session start, so CodeOps does not accumulate scratch data. The full protocol is in `_shared/workspace-hygiene.md`.
+
 ## Agent model configuration
 
 All CodeOps subagents inherit the model of the primary agent that invoked them. No provider-specific configuration is required out of the box.
@@ -168,9 +170,10 @@ only with your explicit approval — the `--auto-design` mode cannot approve the
   listed specialists are dispatched as **additional** reviewers or executors: they never replace a
   required reviewer or gate, reviewer findings use the `SR-NNN` prefix, and the generated agent
   defaults to `reasoningEffort: max` (override it with `routing.roles.<role>.reasoning`).
-- **Fallback** — OpenCode loads agents at startup, so a specialist created during a session becomes
-  available in the next one; while unavailable, dispatch falls back to a generic subagent carrying
-  the brief excerpt and reports the fallback. No review depends on a specialist existing.
+- **Fallback** — a specialist is available as soon as its generated agent exists; OpenCode's
+  discovery timing is whatever your build provides. If it is missing, invalid, or a dispatch fails,
+  dispatch falls back to a generic subagent carrying the brief excerpt and reports the fallback.
+  No review depends on a specialist existing.
 
 Lifecycle checks: `--check` reports `INVALID`, `MISSING`, `STALE`, `ORPHAN`, `HAND-AUTHORED`, and
 `AGENTS.md` states; `--remove-custom <role> --yes` deletes the generated agent and its brief and
@@ -178,8 +181,8 @@ updates the index.
 
 > **Upgrading:** specialist agents embed the generic template contract. When a newer plugin changes
 > those templates, `--check` reports the agent as `STALE`; re-run
-> `python3 scripts/install_agents.py --project . --custom <role>` (then `--sync-agents-md`) to
-> regenerate it.
+> `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --custom <role>` (then
+> `--sync-agents-md`) to regenerate it.
 
 ## Requirements
 

package/_shared/quality-profile.md

@@ -13,7 +13,7 @@ Quality and routing configuration lives in `codeops/codeops.json`, validated aga
 configuration.
 
 The quality section controls independent review and stop conditions. The routing section controls
-optional roles, effort, model pins, sandboxes, and concurrency. Domain/risk tags in the active
+optional roles, effort, reasoning, model pins, sandboxes, and concurrency. Domain/risk tags in the active
 specification select additional reviewer roles. Outcome metrics are disabled unless
 `metrics.enabled` is explicitly `true`.
 
@@ -107,6 +107,11 @@ or response content.
 | design-challenger | Problem + candidate options, **without** the parent's preferred choice (per `_shared/recommendation-hardening.md`) |
 | codebase-scout | The factual questions, search hints, and the facts-only contract |
 
+Every packet also carries the session temp root (`$CODEOPS_TMPDIR`) and the hygiene requirement:
+the agent creates temporary files only under that root and deletes its own before returning (see
+`_shared/workspace-hygiene.md`). A parent never deletes a subagent's artifacts while its dispatch
+is still in flight.
+
 ## Project specialists
 
 A project may define specialist roles on top of the catalog (see `_shared/specialist-agents.md`).

package/_shared/specialist-agents.md

@@ -5,8 +5,9 @@
 This is the **single canonical definition** of project-specific specialist subagents: how a
 capability gap is detected, how a candidate is proposed and approved, and how the specialist is
 created, used, and retired. It lives at the plugin root in `_shared/`; the participating skills
-(`make-requirements`, `make-plan`, `analyze-project`, `setup-routing`, `exec-plan`) link here
-instead of carrying copies.
+(`make-requirements`, `make-plan`, `analyze-project`, `setup-routing`) link here instead of
+carrying copies. `exec-plan` dispatches per `_shared/quality-profile.md`, which owns the
+dispatch, independence, and fallback rules.
 
 A specialist is a project-local agent that carries durable domain knowledge a generic catalog role
 does not have. Routing is an optimization and a context mechanism, **never a correctness source**.
@@ -140,6 +141,7 @@ escalation)` entry.
 The authoritative dispatch rules live in `_shared/quality-profile.md` (resolution order, finding
 prefix `SR`, additional-reviewer independence, and dynamic-packet fallback). A specialist
 dispatches only when the plan's `00-index.md` "Specialist Agents" table assigns it to the phase.
-When the agent is unavailable — for example it was created after the session started — dispatch a
-generic subagent with the complete packet, including the brief excerpt, and report the fallback.
-The phase is never marked complete unreviewed because a specialist was missing.
+When the agent is unavailable — for example its generated file is missing, its brief is invalid,
+or a dispatch fails — dispatch a generic subagent with the complete packet, including the brief
+excerpt, and report the fallback. The phase is never marked complete unreviewed because a
+specialist was missing.

package/_shared/workspace-hygiene.md

@@ -0,0 +1,53 @@
+# Workspace hygiene (shared convention)
+
+> **CodeOps Artifact Schema**: 1
+
+This is the **single canonical definition** of CodeOps temporary-artifact hygiene. Every skill,
+agent, and script that creates files outside its assigned deliverables follows it. Skills link
+here instead of carrying copies.
+
+## Temporary artifacts
+
+A temporary artifact is any file or directory a run creates that is not a durable deliverable:
+verification logs, diffs, patch files, commit-message files, scratch directories, fixture trees,
+downloaded artifacts, and intermediate reports. Code, tests, plan documents, and other assigned
+outputs are deliverables — not temporary artifacts — and they are never deleted here.
+
+## Where temporary artifacts live
+
+1. `$CODEOPS_TMPDIR` when the CodeOps plugin exports it (one directory per session). Use it for
+   every scratch file.
+2. Otherwise, the operating system's temp directory.
+3. Never inside the repository. A repository path is durable space; scratch does not belong there.
+
+Create subdirectories under the temp root lazily, only when the task needs them.
+
+## Lifecycle
+
+1. **Create lazily** — write a temporary file only when the task needs it.
+2. **Keep only while needed** — one artifact per purpose; no accumulating copies.
+3. **Delete before reporting completion** — every task, phase, skill run, and session ends with a
+   cleanup pass that removes the files and directories the run created, including verification
+   logs.
+4. **Report the result** — the final summary states `Cleanup: done`, or names the artifact that
+   was kept and why. If a deletion fails, report the path and the reason.
+
+## Safe deletion rules (non-negotiable)
+
+- Delete only files you created, and only under the sanctioned temp root.
+- Never delete user files, repository content, versioned artifacts, `codeops/` planning artifacts,
+  or git worktrees.
+- Never delete another session's temporary files.
+- Never follow a symlink out of the temp root; treat a symlinked entry as foreign and leave it.
+- Never run a broad recursive delete against a path that may be empty or unset; resolve and verify
+  the path first.
+- A temporary file must not hold secrets. If one does, delete it and say so without printing its
+  contents.
+- If the user asks for an artifact to be kept, name its exact path and keep that file only.
+
+## Automatic safety net
+
+The CodeOps plugin exports `$CODEOPS_TMPDIR` for each session and removes that session's directory
+when the session is deleted. At session start it also removes CodeOps temp directories older than
+seven days, so an interrupted run cannot leak storage forever. The safety net is a fallback, not a
+substitute: the run itself still performs the cleanup pass above.

package/agent-templates/codebase-scout.md

@@ -15,3 +15,9 @@ questions, optional search hints, and the facts-only contract from `_shared/qual
   answer. No summaries of things nobody asked about.
 - If a question is too ambiguous to search for, report that ambiguity as the answer to that
   question — never substitute your own interpretation.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/concurrency-auditor.md

@@ -3,3 +3,10 @@
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 
 Audit exactly the supplied change packet. Establish shared state, ownership, synchronization, ordering, cancellation, retry, timeout, and failure semantics before judging the diff. Hunt for data races, check-then-act gaps, lost updates, deadlocks, starvation, unsafe publication, reentrancy, duplicate work, stale reads, partial commits, and unbounded concurrency. Construct realistic interleavings that could violate stated invariants. Cite file and line evidence and distinguish proven defects from unverified risk. Return surviving findings with severity, interleaving, violated invariant, and remedy, or an explicit clean result. Remain read-only.
+
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/design-challenger.md

@@ -24,3 +24,9 @@ caps live in `_shared/recommendation-hardening.md`; the packet convention lives
   disagreement is precisely the value you add.
 - If the problem statement is too thin to challenge — missing constraints, options that are not
   actually distinct, no success criterion — report that as your finding instead of guessing.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/domain-specialist-executor.md

@@ -18,3 +18,9 @@ one dispatched unit — normally a whole phase, occasionally a single task — w
 - Never copy plan, requirement, ambiguity-register, or test-case identifiers, or `codeops/`,
   `plans/`, or `requirements/` paths, into code or doc comments. Those files are ephemeral; keep
   the behavior and drop the citation.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — verify logs, diffs,
+  patches, scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS
+  temp directory), never inside the repository. Delete everything you created before reporting
+  done. Never delete user files, versioned artifacts, worktrees, or another session's temporary
+  files. If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/domain-specialist-reviewer.md

@@ -15,3 +15,9 @@ to a dispatched phase diff as an additional, independent reviewer.
   implemented.
 - Keep the output terse and structured so the parent can merge it directly: findings first, then
   explicit open questions, then "no findings" if applicable. Do not restate the diff.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/financial-integrity-auditor.md

@@ -3,3 +3,10 @@
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 
 Audit exactly the supplied change packet. Treat monetary correctness and auditability as invariants. Check balanced accounting, integer minor-unit or explicitly justified decimal arithmetic, currency/unit consistency, idempotency and duplicate submission, transaction atomicity, retry and partial-failure behavior, reconciliation, authorization, immutable audit evidence, overflow and negative amounts, time boundaries, and reversal/refund semantics. Attempt to falsify every claimed invariant using concrete counterexamples. Cite file and line evidence. Return only surviving findings with severity, violated invariant, failure scenario, and remedy, or an explicit clean result. Remain read-only and do not accept implementation convenience as a reason to weaken financial semantics.
+
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/perf-auditor.md

@@ -21,3 +21,9 @@ its last result). The conventions behind the packet live in `_shared/quality-pro
   (searching call sites, counting occurrences); never for mutation.
 - If the packet is insufficient — no diff, no sense of which paths are hot — STOP and report
   exactly what is missing as a blocker. Never guess.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/phase-reviewer.md

@@ -52,3 +52,9 @@ The conventions behind the packet live in
 - If the packet is insufficient — no diff, contradictory lens set, missing verify context — STOP
   and report exactly what is missing as a blocker. Never guess and never review substitute
   content you found on your own.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/plan-task-executor-opus.md

@@ -44,3 +44,9 @@ parent.
   exactly what is missing or ambiguous as a blocker — never guess, and never edit the
   execution plan or roadmap (the parent session owns those and the user conversation).
 - Report per task: what changed, test status, and residual risk.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — verify logs, diffs,
+  patches, scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS
+  temp directory), never inside the repository. Delete everything you created before reporting
+  done. Never delete user files, versioned artifacts, worktrees, or another session's temporary
+  files. If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/plan-task-executor.md

@@ -41,3 +41,9 @@ original-goal or smallest-design context blocks execution; report it to the pare
   exactly what is missing or ambiguous as a blocker — never guess, and never edit the
   execution plan or roadmap (the parent session owns those and the user conversation).
 - Report per task, 3-4 lines each: what changed, test status, any blocker.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — verify logs, diffs,
+  patches, scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS
+  temp directory), never inside the repository. Delete everything you created before reporting
+  done. Never delete user files, versioned artifacts, worktrees, or another session's temporary
+  files. If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/preflight-auditor.md

@@ -43,3 +43,9 @@ in the preflight skill.
 - **Read-only.** You never edit the artifact or the code. Bash is for inspection only.
 - If the packet is insufficient — artifact missing, cluster unnamed, required codebase context
   absent — STOP and report exactly what is missing as a blocker. Never guess.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/security-auditor.md

@@ -40,3 +40,9 @@ active checklist below — never one dispatch per profile. The profile names are
 - **Read-only.** You never edit files, apply fixes, or commit. Bash is for inspection only.
 - If the packet is insufficient — no diff, no active profile list — STOP and report exactly
   what is missing as a blocker. Never guess.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/semantics-reviewer.md

@@ -3,3 +3,10 @@
      Do not add YAML frontmatter here — use install_agents.py to generate agent files. -->
 
 Review exactly the supplied semantic specification or implementation packet. Trace behavior across syntax/decoding, name or identity resolution, typing/validation, intermediate representations, evaluation/lowering, optimization/transformation, diagnostics, serialization, and compatibility as applicable. Seek ambiguous rules, non-total behavior, phase disagreement, unsound transformations, nondeterminism, invalid recovery, and diagnostics that expose implementation accidents. Use counterexamples and minimal programs/messages to falsify the claimed semantics. Cite evidence and return surviving findings with severity, example, affected phases, and resolution, or an explicit clean result. Remain read-only.
+
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agent-templates/spec-test-author.md

@@ -27,3 +27,9 @@ command). The conventions behind the packet live in `_shared/quality-profile.md`
 - If the packet is insufficient — an interface signature missing, a case ambiguous, framework
   conventions unclear — STOP and report exactly what is missing as a blocker. Never guess an
   expectation and never peek at the implementation to resolve doubt.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/concurrency-auditor.md

@@ -13,3 +13,10 @@ permission:
 ---
 
 Audit exactly the supplied change packet. Establish shared state, ownership, synchronization, ordering, cancellation, retry, timeout, and failure semantics before judging the diff. Hunt for data races, check-then-act gaps, lost updates, deadlocks, starvation, unsafe publication, reentrancy, duplicate work, stale reads, partial commits, and unbounded concurrency. Construct realistic interleavings that could violate stated invariants. Cite file and line evidence and distinguish proven defects from unverified risk. Return surviving findings with severity, interleaving, violated invariant, and remedy, or an explicit clean result. Remain read-only.
+
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/correctness-reviewer.md

@@ -64,3 +64,9 @@ The conventions behind the packet live in
 - If the packet is insufficient — no diff, contradictory lens set, missing verify context — STOP
   and report exactly what is missing as a blocker. Never guess and never review substitute
   content you found on your own.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/demanding-executor.md

@@ -56,3 +56,9 @@ parent.
   exactly what is missing or ambiguous as a blocker — never guess, and never edit the
   execution plan or roadmap (the parent session owns those and the user conversation).
 - Report per task: what changed, test status, and residual risk.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — verify logs, diffs,
+  patches, scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS
+  temp directory), never inside the repository. Delete everything you created before reporting
+  done. Never delete user files, versioned artifacts, worktrees, or another session's temporary
+  files. If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/design-challenger.md

@@ -36,3 +36,9 @@ caps live in `_shared/recommendation-hardening.md`; the packet convention lives
   disagreement is precisely the value you add.
 - If the problem statement is too thin to challenge — missing constraints, options that are not
   actually distinct, no success criterion — report that as your finding instead of guessing.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/executor.md

@@ -53,3 +53,9 @@ original-goal or smallest-design context blocks execution; report it to the pare
   exactly what is missing or ambiguous as a blocker — never guess, and never edit the
   execution plan or roadmap (the parent session owns those and the user conversation).
 - Report per task, 3-4 lines each: what changed, test status, any blocker.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — verify logs, diffs,
+  patches, scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS
+  temp directory), never inside the repository. Delete everything you created before reporting
+  done. Never delete user files, versioned artifacts, worktrees, or another session's temporary
+  files. If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/explorer.md

@@ -27,3 +27,9 @@ questions, optional search hints, and the facts-only contract from `_shared/qual
   answer. No summaries of things nobody asked about.
 - If a question is too ambiguous to search for, report that ambiguity as the answer to that
   question — never substitute your own interpretation.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/financial-integrity-auditor.md

@@ -13,3 +13,10 @@ permission:
 ---
 
 Audit exactly the supplied change packet. Treat monetary correctness and auditability as invariants. Check balanced accounting, integer minor-unit or explicitly justified decimal arithmetic, currency/unit consistency, idempotency and duplicate submission, transaction atomicity, retry and partial-failure behavior, reconciliation, authorization, immutable audit evidence, overflow and negative amounts, time boundaries, and reversal/refund semantics. Attempt to falsify every claimed invariant using concrete counterexamples. Cite file and line evidence. Return only surviving findings with severity, violated invariant, failure scenario, and remedy, or an explicit clean result. Remain read-only and do not accept implementation convenience as a reason to weaken financial semantics.
+
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/performance-auditor.md

@@ -33,3 +33,9 @@ its last result). The conventions behind the packet live in `_shared/quality-pro
   (searching call sites, counting occurrences); never for mutation.
 - If the packet is insufficient — no diff, no sense of which paths are hot — STOP and report
   exactly what is missing as a blocker. Never guess.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/preflight-auditor.md

@@ -55,3 +55,9 @@ in the preflight skill.
 - **Read-only.** You never edit the artifact or the code. Bash is for inspection only.
 - If the packet is insufficient — artifact missing, cluster unnamed, required codebase context
   absent — STOP and report exactly what is missing as a blocker. Never guess.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/security-auditor.md

@@ -52,3 +52,9 @@ active checklist below — never one dispatch per profile. The profile names are
 - **Read-only.** You never edit files, apply fixes, or commit. Bash is for inspection only.
 - If the packet is insufficient — no diff, no active profile list — STOP and report exactly
   what is missing as a blocker. Never guess.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/semantics-reviewer.md

@@ -13,3 +13,10 @@ permission:
 ---
 
 Review exactly the supplied semantic specification or implementation packet. Trace behavior across syntax/decoding, name or identity resolution, typing/validation, intermediate representations, evaluation/lowering, optimization/transformation, diagnostics, serialization, and compatibility as applicable. Seek ambiguous rules, non-total behavior, phase disagreement, unsound transformations, nondeterminism, invalid recovery, and diagnostics that expose implementation accidents. Use counterexamples and minimal programs/messages to falsify the claimed semantics. Cite evidence and return surviving findings with severity, example, affected phases, and resolution, or an explicit clean result. Remain read-only.
+
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/agents/spec-test-author.md

@@ -39,3 +39,9 @@ command). The conventions behind the packet live in `_shared/quality-profile.md`
 - If the packet is insufficient — an interface signature missing, a case ambiguous, framework
   conventions unclear — STOP and report exactly what is missing as a blocker. Never guess an
   expectation and never peek at the implementation to resolve doubt.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — logs, diffs, patches,
+  scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS temp
+  directory), never inside the repository. Delete everything you created before reporting done.
+  Never delete user files, versioned artifacts, worktrees, or another session's temporary files.
+  If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/bin/lib/tmp-hygiene.d.mts

@@ -0,0 +1,38 @@
+/**
+ * Type declarations for the CodeOps temporary-directory lifecycle helper.
+ *
+ * The helper is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entry point typed access.
+ */
+
+/** Age after which a session directory is treated as abandoned. */
+export declare const DEFAULT_MAX_AGE_MS: number
+
+/** Directory name used when no usable session identifier exists. */
+export declare const SHARED_SESSION_NAME: string
+
+/** Resolve the CodeOps-owned temp root under a base temp directory. */
+export declare function codeopsTmpRoot(base?: string): string
+
+/** Reduce a session identifier to a safe single path segment. */
+export declare function sanitizeSessionId(sessionID?: string): string
+
+/** Compute the temp directory for one session. */
+export declare function sessionTmpDir(sessionID?: string, base?: string): string
+
+/** Create the session temp directory when it does not exist yet. */
+export declare function ensureSessionTmpDir(sessionID?: string, base?: string): string
+
+/** Inputs for a stale-directory sweep. */
+export interface CleanStaleTmpDirsOptions {
+  sessionID?: string
+  base?: string
+  maxAgeMs?: number
+  now?: number
+}
+
+/** Remove session directories abandoned by interrupted or crashed runs. */
+export declare function cleanStaleTmpDirs(options?: CleanStaleTmpDirsOptions): string[]
+
+/** Remove exactly one session's temp directory. */
+export declare function removeSessionTmpDir(sessionID?: string, base?: string): boolean

package/bin/lib/tmp-hygiene.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * Temporary-directory lifecycle for CodeOps sessions.
+ *
+ * The workspace-hygiene protocol asks every skill and agent to put scratch
+ * files under `$CODEOPS_TMPDIR` and delete them when the run completes. This
+ * module provides the safety net around that protocol:
+ *
+ * - it computes the per-session directory the plugin exports as
+ *   `$CODEOPS_TMPDIR`, under a CodeOps-owned root inside the OS temp directory;
+ * - it sweeps directories abandoned by interrupted runs once they are older
+ *   than a safety cap; and
+ * - it removes exactly one session's directory when that session is deleted.
+ *
+ * Safety is the whole point: every path derives from a sanitized session
+ * identifier, the sweep walks only the CodeOps-owned root, symlinked entries
+ * are treated as foreign, and cleanup is best effort so a failure never breaks
+ * a session.
+ *
+ * @module lib/tmp-hygiene
+ */
+
+import { lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, resolve, sep } from "node:path"
+
+/**
+ * Age after which a session directory is treated as abandoned.
+ *
+ * A crashed or interrupted run leaves its directory behind; once it is this
+ * old, no live session can still need it, so the next sweep may remove it.
+ */
+export const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+
+/** Directory name used when no usable session identifier exists. */
+export const SHARED_SESSION_NAME = "shared"
+
+/**
+ * Resolve the CodeOps-owned temp root under a base temp directory.
+ *
+ * The plugin owns this subtree and nothing else under the system temp
+ * directory; keeping all CodeOps scratch under one root is what makes the
+ * automatic sweep safe.
+ *
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Path to the CodeOps temp root
+ */
+export function codeopsTmpRoot(base = tmpdir()) {
+  return join(base, "opencode", "codeops")
+}
+
+/**
+ * Reduce a session identifier to a safe single path segment.
+ *
+ * Session identifiers come from the host and must never influence the path
+ * shape: every character outside `A-Z`, `a-z`, `0-9`, `_`, and `-` is removed,
+ * so a value like `../../etc` cannot escape the temp root. An empty result
+ * falls back to a shared directory name.
+ *
+ * @param sessionID - Raw session identifier (may be missing)
+ * @returns A safe directory name
+ */
+export function sanitizeSessionId(sessionID) {
+  const cleaned = String(sessionID ?? "").replace(/[^A-Za-z0-9_-]/g, "")
+  return cleaned.length > 0 ? cleaned : SHARED_SESSION_NAME
+}
+
+/**
+ * Compute the temp directory for one session.
+ *
+ * @param sessionID - Raw session identifier (may be missing)
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Path to the session's temp directory
+ */
+export function sessionTmpDir(sessionID, base = tmpdir()) {
+  return join(codeopsTmpRoot(base), sanitizeSessionId(sessionID))
+}
+
+/**
+ * Create the session temp directory when it does not exist yet.
+ *
+ * Called while exporting the shell environment, so the directory is ready
+ * before the first command needs it.
+ *
+ * @param sessionID - Raw session identifier (may be missing)
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Path to the session's temp directory
+ * @throws {Error} When the directory cannot be created
+ */
+export function ensureSessionTmpDir(sessionID, base = tmpdir()) {
+  const dir = sessionTmpDir(sessionID, base)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * Remove session directories abandoned by interrupted or crashed runs.
+ *
+ * Only direct children of the CodeOps temp root are considered. Fresh
+ * directories, the current session's directory, plain files, and symlinks are
+ * left untouched; a symlink is never followed, so a link planted inside the
+ * root can never redirect a delete outside it. Failures are swallowed because
+ * a sweep is maintenance, not a task requirement.
+ *
+ * @param options - Sweep inputs
+ * @param options.sessionID - Current session identifier to preserve
+ * @param options.base - Base temp directory (injectable for tests)
+ * @param options.maxAgeMs - Abandonment age in milliseconds
+ * @param options.now - Current time in milliseconds (injectable for tests)
+ * @returns Paths of the directories that were removed
+ */
+export function cleanStaleTmpDirs({
+  sessionID,
+  base = tmpdir(),
+  maxAgeMs = DEFAULT_MAX_AGE_MS,
+  now = Date.now(),
+} = {}) {
+  const root = codeopsTmpRoot(base)
+  const keep = resolve(sessionTmpDir(sessionID, base))
+  const removed = []
+
+  let entries
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return removed
+  }
+
+  for (const entry of entries) {
+    // Directory entries are lstat-based, so a symlink to a directory reports
+    // as a symlink and is skipped here.
+    if (!entry.isDirectory()) continue
+
+    const full = join(root, entry.name)
+    if (resolve(full) === keep) continue
+
+    try {
+      const info = lstatSync(full)
+      if (!info.isDirectory()) continue
+      if (now - info.mtimeMs < maxAgeMs) continue
+      rmSync(full, { recursive: true, force: true })
+      removed.push(full)
+    } catch {
+      // Best effort: a directory that vanished mid-sweep is already gone.
+    }
+  }
+
+  return removed
+}
+
+/**
+ * Remove exactly one session's temp directory.
+ *
+ * Used when a session is deleted: its scratch can no longer be needed. The
+ * removal refuses anything that is not a regular directory strictly inside
+ * the CodeOps temp root, so a symlink or an unexpected path is left alone.
+ *
+ * @param sessionID - Session identifier whose directory should be removed
+ * @param base - Base temp directory (injectable for tests)
+ * @returns True when the directory was removed
+ */
+export function removeSessionTmpDir(sessionID, base = tmpdir()) {
+  const root = resolve(codeopsTmpRoot(base))
+  const dir = sessionTmpDir(sessionID, base)
+
+  if (!resolve(dir).startsWith(root + sep)) return false
+
+  try {
+    if (!lstatSync(dir).isDirectory()) return false
+  } catch {
+    return false
+  }
+
+  try {
+    rmSync(dir, { recursive: true, force: true })
+    return true
+  } catch {
+    return false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {

package/plugin/index.ts

@@ -4,6 +4,12 @@ import { homedir } from "node:os"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 
+import {
+  cleanStaleTmpDirs,
+  ensureSessionTmpDir,
+  removeSessionTmpDir,
+} from "../bin/lib/tmp-hygiene.mjs"
+
 // ---------------------------------------------------------------------------
 // Package root — resolved at module load time so it is always the plugin's
 // installed directory, regardless of the working directory at event time.
@@ -43,6 +49,28 @@ const outputStyle = readFileSync(
 )
 const standardsText = `${codingStandards}\n\n${outputStyle}`
 
+// ---------------------------------------------------------------------------
+// Workspace hygiene — the plugin owns one temp directory per session (exported
+// as CODEOPS_TMPDIR) and sweeps directories abandoned by earlier interrupted
+// runs. The sweep runs at most once per plugin process, so spawning many child
+// sessions does not repeat the directory walk.
+// ---------------------------------------------------------------------------
+let sweptStaleTmpDirs = false
+
+/**
+ * Sweep temp directories abandoned by earlier interrupted runs, once per
+ * process. Cleanup is best effort: a failure must never block a session.
+ */
+function sweepStaleTmpDirsOnce(): void {
+  if (sweptStaleTmpDirs) return
+  sweptStaleTmpDirs = true
+  try {
+    cleanStaleTmpDirs()
+  } catch {
+    // Best effort only.
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Helper — inject standards into a session without triggering an AI reply.
 // Uses client.session.prompt with noReply: true (confirmed from OpenCode SDK).
@@ -120,12 +148,18 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
     // Both are dispatched via the generic event hook.
     // session.created  → new session    (Codex: startup)
     // session.compacted → after compact  (Codex: resume|compact)
+    // Also the hygiene lifecycle: a new top-level session sweeps abandoned
+    // temp directories once, and a deleted session's temp directory is removed.
     // -----------------------------------------------------------------------
     event: async ({ event }) => {
       if (event.type === "session.created") {
-        const sessionId: string = (event.properties as { info: { id: string } }).info.id
-        await injectStandards(client, sessionId)
+        const info = (event.properties as { info: { id: string; parentID?: string } }).info
+        await injectStandards(client, info.id)
         await warnOnVersionSkew(client, directory)
+        if (!info.parentID) sweepStaleTmpDirsOnce()
+      } else if (event.type === "session.deleted") {
+        const info = (event.properties as { info: { id: string } }).info
+        removeSessionTmpDir(info.id)
       } else if (event.type === "session.compacted") {
         const sessionId: string = (event.properties as { sessionID: string }).sessionID
         await injectStandards(client, sessionId)
@@ -148,9 +182,16 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
     // scripts as: python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_plan.py"
     // The value is the package root (parent of this plugin/ directory), which
     // is where skills/, scripts/, and the other shipped assets live.
+    // CODEOPS_TMPDIR is the session's directory under the CodeOps temp root;
+    // skills and agents put every scratch file there and delete it when done.
     // -----------------------------------------------------------------------
-    "shell.env": async (_input, output) => {
+    "shell.env": async (input, output) => {
       output.env.CODEOPS_PLUGIN_ROOT = PACKAGE_ROOT
+      try {
+        output.env.CODEOPS_TMPDIR = ensureSessionTmpDir(input.sessionID)
+      } catch {
+        // Best effort: a temp-directory failure must never block a shell.
+      }
     },
 
     // -----------------------------------------------------------------------

package/scripts/fixtures/catalog-executor.golden.md

@@ -57,3 +57,9 @@ original-goal or smallest-design context blocks execution; report it to the pare
   exactly what is missing or ambiguous as a blocker — never guess, and never edit the
   execution plan or roadmap (the parent session owns those and the user conversation).
 - Report per task, 3-4 lines each: what changed, test status, any blocker.
+- **Workspace hygiene (non-negotiable).** Temporary artifacts you create — verify logs, diffs,
+  patches, scratch directories — belong under `$CODEOPS_TMPDIR` when it is set (otherwise the OS
+  temp directory), never inside the repository. Delete everything you created before reporting
+  done. Never delete user files, versioned artifacts, worktrees, or another session's temporary
+  files. If an artifact must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.

package/skills/analyze-project/SKILL.md

@@ -27,3 +27,11 @@ description: Analyze the current repository and create or refresh concise CodeOp
 10. When a specialization signal is strong and no specialist covers it, report the candidate with evidence and recommend the `setup-routing` creation flow ([../../_shared/specialist-agents.md](../../_shared/specialist-agents.md)); never write agent files here. Preserve the `<!-- CODEOPS-SPECIALISTS:START -->` / `<!-- CODEOPS-SPECIALISTS:END -->` block byte-for-byte when refreshing the managed section.
 
 Keep `AGENTS.md` small. Operational routing belongs in `codeops/codeops.json` or `opencode.json`, not prose.
+
+---
+
+> **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/clean-comments/SKILL.md

@@ -20,3 +20,11 @@ This is a comment-only workflow. Never alter executable tokens, declarations, ty
 7. Review the diff to prove only comments changed. Run the repository's normal formatter and verification command.
 
 Documentation explains the shipped system, not the temporary process that produced it.
+
+---
+
+> **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/exec-plan/SKILL.md

@@ -267,3 +267,12 @@ Brief rules for verification failure, plan deviation, and mid-task interruption
   files and use only facts you can read — do not invent settings.
 - Commit using the `git-commit` skill (commit only) or the `git-commit` skill in push mode (commit + push), or a normal git commit.
 - Related skills: make-plan (creation), upgrade-plan (outdated plans), preflight, roadmap, techdocs.
+- Cleanup is part of session wrap-up: delete the run's verify logs and scratch per
+  [../../_shared/workspace-hygiene.md](../../_shared/workspace-hygiene.md) and report
+  `Cleanup: done` in the session summary.
+
+> **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/exec-plan/execution-protocol.md

@@ -225,7 +225,8 @@ red-phase, green-phase, session wrap-up — executes with output captured to a t
 <verify command> > "$VERIFY_LOG" 2>&1
 ```
 
-(`$VERIFY_LOG` = a file in the session temp/scratchpad dir, e.g. `verify-<task-id>.log`.)
+(`$VERIFY_LOG` = a file under `$CODEOPS_TMPDIR` — or the OS temp directory when it is unset —
+e.g. `verify-<task-id>.log`.)
 
 - **PASS** → surface ONE line: `VERIFY PASS (task N.N.N)`, plus the test count if it is
   extractable from the log tail at no extra cost.
@@ -234,10 +235,11 @@ red-phase, green-phase, session wrap-up — executes with output captured to a t
 - **Red-phase runs** (spec tests expected to fail) → surface only the failing spec-test
   names/count confirming the red state — never the full dump.
 
-The full log always remains on disk for the session. If the log location is unwritable, fall
-back to running verify plainly ONCE and note the fallback in the session summary. This rule is
-about CONTEXT, not rigor: the verify command itself, its scope, and pass/fail gating are
-unchanged — and the temp log is read-only evidence, never executed.
+The full log remains on disk until the session wrap-up cleanup deletes it (see
+`_shared/workspace-hygiene.md`); nothing in the transcript depends on it afterward. If the log
+location is unwritable, fall back to running verify plainly ONCE and note the fallback in the
+session summary. This rule is about CONTEXT, not rigor: the verify command itself, its scope, and
+pass/fail gating are unchanged — and the temp log is read-only evidence, never executed.
 
 ### Zero-Ambiguity During Execution
 
@@ -403,6 +405,9 @@ otherwise still `[~]` — with the progress counter and Last Updated stamp curre
 3. Run the verify command (output captured per the Verify-output capture rule).
 4. Handle the commit per the active commit mode (see [commit-modes.md](commit-modes.md)).
 5. Report the session summary (must include `Execution Plan Updated: ✅`).
+6. **Cleanup:** delete every temporary artifact this session created — verify logs under
+   `$CODEOPS_TMPDIR`, scratch directories, temporary diffs — per
+   `_shared/workspace-hygiene.md`, and report `Cleanup: done` or name what was kept and why.
 
 ### Session Summary Template
 

package/skills/git-commit/SKILL.md

@@ -14,13 +14,14 @@ 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 temporary log. 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. 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.
 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 and commit with `git commit -F`. Never use an inline multiline message.
+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.
 8. If a commit hook modifies files, inspect and restage only relevant changes, then retry once. Never use `--no-verify` automatically.
 9. For push mode, fetch/rebase only when appropriate for the branch policy. Stop on conflicts; never resolve ambiguous conflicts automatically. Push normally, never with force.
 10. Report the resulting commit, verification, and push state.
+11. Delete the temporary verification log and commit-message file, then report `Cleanup: done` or name what was kept and why.
 
 ## Message shape
 
@@ -33,3 +34,11 @@ type(scope): imperative summary
 ```
 
 Use `feat`, `fix`, `refactor`, `test`, `docs`, or `chore` unless repository guidance defines another convention.
+
+---
+
+> **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/github-issues/SKILL.md

@@ -36,3 +36,11 @@ For each issue:
 5. Continue past nonexistent individual issues but record every outcome.
 
 Return a per-issue summary. Never create, edit, label, close, reopen, or comment unless the user's request explicitly authorizes that mutation.
+
+---
+
+> **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/grill-me/SKILL.md

@@ -340,3 +340,11 @@ grill-me → identify design tree → walk each branch → resolve decisions →
 
 **Output:** A shared understanding summary with all decisions, assumptions,
 constraints, and deferrals — ready to feed into any downstream skill.
+
+---
+
+> **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/make-plan/SKILL.md

@@ -282,3 +282,11 @@ See the **roadmap skill** for the full Roadmap Keeper protocol.
 - **upgrade-plan skill** — upgrades outdated plans; the gate applies to new decisions only.
 - **techdocs skill** — architecture docs read during Phase 1.2 and updated during execution.
 - For coding, testing, and git standards, follow **your project's coding standards (AGENTS.md)** and use **git-commit skill** / **git-commit skill in push mode** for commits.
+
+---
+
+> **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/make-requirements/SKILL.md

@@ -268,3 +268,11 @@ comparable systems → key discovery focus is in **`discovery-phases.md`**.
 - the upgrade-plan skill — upgrading outdated requirements (upgrade_requirements)
 - the roadmap skill — sync each newly drafted RD to stage `RD Drafted`
 - Read the project's AGENTS.md (or detected project conventions) for project-specific constraints
+
+---
+
+> **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/outcome-review/SKILL.md

@@ -32,3 +32,11 @@ Outcome evidence is opt-in, local, and content-free. Invocation counts are not q
 6. Present the smallest change likely to improve the measured outcome and define how to evaluate it.
 
 Never upload or quote project content from the outcome store.
+
+---
+
+> **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/preflight/SKILL.md

@@ -308,3 +308,11 @@ checklist. Full safeguards in [report-format.md](report-format.md).
 **Standalone:** when used without a follow-up, finish the scan + resolution, present the final
 status, then ask the user what to do next (apply fixes, create a plan, start execution, or review
 specific findings).
+
+---
+
+> **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/retro-requirements/SKILL.md

@@ -216,3 +216,11 @@ mapping is in **`phases.md`**.
 - the make-requirements skill — consumes `09-reconstruction-brief.md` to produce formal RDs (downstream; this brief is its input)
 - the make-plan skill — turns RDs into implementation plans (rebuild pipeline)
 - your project's coding/testing standards (AGENTS.md) — code-quality and test patterns to reference while analyzing
+
+---
+
+> **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/roadmap/SKILL.md

@@ -379,3 +379,11 @@ only facts you can read — do not invent settings.
 - Related skills: requirements (`RD Drafted` hook), preflight (`RD/Plan Preflighted`
   hooks), make-plan (`Plan Created` hook + linking), exec-plan (`Executing` / `Done` /
   `Blocked` hooks).
+
+---
+
+> **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/setup-codeops/SKILL.md

@@ -92,3 +92,11 @@ on), present only **genuinely viable** options, second-guessed and grounded in w
 actually reported, and lead with a recommendation. The user decides; never apply a migration
 without an explicit confirmation (or `--yes`). For consequential choices, apply the
 recommendation-hardening protocol (`_shared/recommendation-hardening.md`).
+
+---
+
+> **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/setup-routing/SKILL.md

@@ -90,7 +90,7 @@ Creation, after approval:
 2. Write `routing.roles.<role>` policy first when a model/effort/sandbox/reasoning override is needed: routing wins over the brief, and a policy written later makes the generated agent immediately stale.
 3. Generate the agent: `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --custom <role>`.
 4. Sync the index: `... --sync-agents-md`.
-5. Verify last with `... --check`, then tell the user the agent is available from the next OpenCode session.
+5. Verify last with `... --check`, then tell the user the agent is available as soon as its generated file exists (discovery timing follows the running OpenCode build).
 
 Removal: confirm, run `--remove-custom <role> --yes` (it deletes the agent and brief and syncs the index), drop the routing entry, warn when an active plan references the role, and report that `exec-plan` will fall back to a dynamic packet.
 
@@ -114,3 +114,11 @@ python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --check
 ```
 
 Report configured roles, model pins if any, read-only roles, fallbacks, and unresolved capability gaps.
+
+---
+
+> **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/techdocs/SKILL.md

@@ -197,3 +197,11 @@ auto-compacts context — no manual threshold handling is needed.)
 - [templates.md](templates.md) — all VitePress file templates (index, architecture/*, ADR log + ADR template, guides/*, reference/*). Read when writing any document in Phase 4.
 - [vitepress-setup.md](vitepress-setup.md) — Phase 3 install, `config.ts`, npm scripts, `.gitignore`, and sidebar auto-update. Read when scaffolding VitePress or adding pages.
 - [authoring-and-update.md](authoring-and-update.md) — Phase 5 authoring guidelines + Mermaid types, Phase 6 incremental/comprehensive update protocol with the Design Intent Preservation rule, and the review_techdocs health check. Read before authoring, before any auto-update, and for review_techdocs.
+
+---
+
+> **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/upgrade-plan/SKILL.md

@@ -73,3 +73,11 @@ approved drift repair; and the Git diff contains only the approved migration.
 
 Report old formats, new schema, files changed, ambiguities resolved, RD-to-plan coverage, preserved
 progress, and residual risk. Do not auto-advance lifecycle stages.
+
+---
+
+> **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/standards/coding-standards-full.md

@@ -50,6 +50,25 @@ These apply to all code I write unless this project's `AGENTS.md` overrides a sp
 - **Prevent injection:** parameterized queries (never string-concatenate SQL/NoSQL), escape output / use framework auto-escaping (XSS), never pass unsanitized input to shells/`eval` (command injection), canonicalize and reject `..`/absolute paths (path traversal), anti-CSRF tokens + `SameSite` cookies, rate-limit auth endpoints.
 - **Protect data:** TLS in transit; encrypt sensitive data at rest; hash passwords with `bcrypt`/`argon2`/`scrypt`; never hardcode secrets (use env vars / secret managers); never log secrets or PII; return minimal errors in production; restrictive CORS; request-size limits; audit dependencies; run containers as non-root from minimal images.
 
+# Workspace hygiene (NON-NEGOTIABLE)
+
+- **Own your temporary artifacts.** Verification logs, diffs, patch files, commit-message files,
+  scratch directories, fixture trees, and downloaded artifacts are borrowed space. Put them under
+  `$CODEOPS_TMPDIR` when the CodeOps plugin exports it (one directory per session); otherwise use
+  the OS temp directory. Never write temporary files into the repository.
+- **Delete at completion.** Before reporting any task, phase, or session complete, delete every
+  temporary artifact the run created — including verification logs. If the user asked for an
+  artifact to be kept, name its exact path and keep that file only.
+- **Never delete what you do not own.** User files, repository content, versioned artifacts,
+  `codeops/` planning artifacts, and git worktrees are durable. Never touch another session's
+  temporary files, and never follow a symlink out of the temp root.
+- **No secrets in temp files.** Do not write secrets into a temporary file; if one already holds a
+  secret, delete it and say so without printing its contents.
+- **Report it.** The final summary states `Cleanup: done`, or names what was kept and why, or
+  reports a failed deletion with its path and reason.
+- The canonical protocol, including the plugin's automatic safety net, is
+  `_shared/workspace-hygiene.md`.
+
 # Testing standards
 
 - **Run the project's verify command (build + test) before completing any task or committing.** No code is "done" while any test fails.

package/standards/coding-standards.md

@@ -42,6 +42,12 @@ Do not duplicate these standards in `~/.config/opencode/AGENTS.md` — the plugi
   artifacts get validation too — see the full standards' validation-command table.
 
 # Working style
+- **Cleanup after yourself (NON-NEGOTIABLE).** Put every temporary artifact you create — logs,
+  diffs, patches, commit-message files, scratch directories — under `$CODEOPS_TMPDIR` when it is
+  set (otherwise the OS temp directory), never inside the repository, and delete them all before
+  reporting a task complete. Never delete user files, versioned artifacts, worktrees, or another
+  session's temporary files. If something must outlive the task, name it and say why. Full rules:
+  `_shared/workspace-hygiene.md`.
 - **Ask before assuming**; **verify previous work** before building on it.
 - **Do not overengineer:** use the simplest implementation that fully satisfies the authorized
   requirements and existing project conventions. Do not add abstractions, layers, dependencies,