@caddis/cli 0.4.0 → 0.4.1

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.83",
+  "version": "1.3.86",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/check_doc_coverage.py

@@ -728,7 +728,7 @@ def remove_rows_with_targets(text: str, targets: list[str]) -> str:
 def _atomic_write(path: Path, text: str) -> bool:
     """Write ``text`` via a same-dir, per-process temp file + atomic replace. Returns True on success.
 
-    A crash mid-write can't leave a truncated DOC-MAP (mirrors dream_memory.save_facts). The temp name
+    A crash mid-write can't leave a truncated DOC-MAP. The temp name
     is PID-tagged so two concurrent runs don't fight over one temp. Returns **False (never raises)** if
     the target is locked — on Windows an open editor / AV can hold it — so a maintenance run degrades to
     a clear message instead of a stack trace.

package/bundles/antigravity-plugin/scripts/setup_project_ai.py

@@ -896,6 +896,7 @@ agent-log.jsonl
 .last-usage-review
 relay.md
 relay/
+session-state.md
 PROJECT-FACTS.md
 memory.jsonl
 """
@@ -1131,12 +1132,13 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
     """Create the harness-owned .caddis/ artifact tree + a default .gitignore + a config example.
 
     Committed subdirs: plans, handoffs, agent-docs, prd, kb, prompts, comms. Transient state
-    (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, PROJECT-FACTS.md, memory.jsonl)
-    is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
+    (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, session-state.md,
+    PROJECT-FACTS.md, memory.jsonl) is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
     Phase A3) — kb/ and prompts/ round out plans/prd/agent-docs/reviews so nothing has to
     scatter to the repo root or .github/. Also drops a documented `config.toml.example`
-    (guard/doc_coverage). Idempotent; never clobbers an existing .gitignore or
-    config example.
+    (guard/doc_coverage). Idempotent. An existing .caddis/.gitignore is never clobbered or
+    reordered, but MISSING entries are appended — otherwise a repo set up before an entry
+    existed would never receive it. The config example is left alone entirely.
 
     Writes into the repo's `.caddis/`.
     """
@@ -1198,7 +1200,34 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
         notes.append(f"scaffold: wrote {label}/kb/environment-map.md")
     gi = root / ".gitignore"
     if gi.exists():
-        notes.append(f"scaffold: {label}/.gitignore present — kept")
+        # APPEND what is missing rather than keeping the file frozen. The old behaviour was
+        # "present -> kept", so a repo scaffolded before an entry was added NEVER received it.
+        # That is not hypothetical: `session-state.md` is rewritten by the Stop hook on every
+        # turn and contains the operator's verbatim words, and an already-scaffolded repo was
+        # sitting one hook-fire away from committing it.
+        #
+        # Only ever adds; a line the user wrote themselves is never touched or reordered.
+        try:
+            existing = gi.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        have = {ln.strip() for ln in existing.splitlines()}
+        missing = [
+            ln for ln in ARTIFACT_GITIGNORE.splitlines()
+            if ln.strip() and not ln.startswith("#") and ln.strip() not in have
+        ]
+        if not missing:
+            notes.append(f"scaffold: {label}/.gitignore present — up to date")
+        else:
+            if not dry:
+                block = "" if existing.endswith("\n") or not existing else "\n"
+                block += "\n# added by caddis — newer transient artifacts\n"
+                block += "\n".join(missing) + "\n"
+                gi.write_text(existing + block, encoding="utf-8")
+            notes.append(
+                f"scaffold: {label}/.gitignore — added {len(missing)} missing entry(ies): "
+                + ", ".join(missing)
+            )
     else:
         if not dry:
             root.mkdir(parents=True, exist_ok=True)

package/bundles/antigravity-plugin/skills/_registry.md

@@ -39,6 +39,7 @@
 | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes. |
 | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
 | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
+| Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
 | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
 | Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, reverse proxy (IIS or nginx), and git-pull workflow. Use when deploying any web app to a Windows prod server, setting up NSSM services, configuring IIS or nginx reverse proxy, making code environment-aware for dev/prod, or troubleshooting prod deployment issues. |
 

package/bundles/antigravity-plugin/skills/safe-cleanup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```
+
+## Reference implementation
+
+The estate this skill came from keeps working tools at `.caddis/tools/`:
+
+- `venv-audit.py` - imports every dependency each `pyproject.toml` declares
+- `rebuild-venv.ps1` - renames aside, rebuilds, restarts services, refuses on links or live processes
+- `README-venv-safety.md` - the incident record
+
+Adapt rather than copy: the rules matter more than the scripts.

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.26",
+  "version": "1.3.27",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/_registry.md

@@ -51,6 +51,7 @@
 | Changelog Generator | `changelog-generator/` | Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation. |
 | Deploy Local | `deploy-local/` | End-to-end local deployment loop for Gitea-hosted projects. Use when the user wants to commit on dev, push to remote, monitor the golden CI/build/deploy workflow, validate prod on the configured prod host, and fix lint/test/pipeline failures until deployment is healthy. |
 | Monorepo | `monorepo/` | Monorepo management with Turborepo and pnpm workspaces. Use for Turborepo setup, turbo.json task dependencies, remote caching, pnpm workspace protocol, shared packages (ui-library, config, types), affected-only CI/CD builds, or monorepo structure (apps/ vs packages/). Covers pitfalls like circular deps, version drift, and hoisting issues. |
+| Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
 | Update Readme | `update-readme/` | Detect feature commits and update README sections (Features, API, Usage) with accurate repo-aware changes, then stage only README for a docs commit. Use when users add features/routes/components and want README maintained automatically. |
 
 ### Docs

package/bundles/antigravity-plugin-extras/skills/safe-cleanup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```
+
+## Reference implementation
+
+The estate this skill came from keeps working tools at `.caddis/tools/`:
+
+- `venv-audit.py` - imports every dependency each `pyproject.toml` declares
+- `rebuild-venv.ps1` - renames aside, rebuilds, restarts services, refuses on links or live processes
+- `README-venv-safety.md` - the incident record
+
+Adapt rather than copy: the rules matter more than the scripts.

package/bundles/codex/.codex/skills/devops/safe-cleanup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```
+
+## Reference implementation
+
+The estate this skill came from keeps working tools at `.caddis/tools/`:
+
+- `venv-audit.py` - imports every dependency each `pyproject.toml` declares
+- `rebuild-venv.ps1` - renames aside, rebuilds, restarts services, refuses on links or live processes
+- `README-venv-safety.md` - the incident record
+
+Adapt rather than copy: the rules matter more than the scripts.

package/bundles/manifest.json

@@ -1,8 +1,8 @@
 {
-  "poolVersion": "1.3.83",
+  "poolVersion": "1.3.86",
   "bundles": {
-    "antigravity-plugin": "1.3.83",
-    "antigravity-plugin-extras": "1.3.26",
+    "antigravity-plugin": "1.3.86",
+    "antigravity-plugin-extras": "1.3.27",
     "codex": "unknown"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",