@caddis/cli 0.4.0 → 0.4.2

package/bundles/antigravity-plugin/skills/tech-explainer/references/language.md

@@ -0,0 +1,141 @@
+# Simplified Technical English for explainers
+
+Read this during the STE rewrite pass (process step 6), not while drafting. Drafting in STE from the
+first word produces stilted, thin prose — write the ideas out normally, then compress them here.
+
+## Contents
+
+- [Why STE, and what it is not](#why-ste-and-what-it-is-not)
+- [The rules](#the-rules)
+- [The rewrite table](#the-rewrite-table)
+- [Building the vocabulary table (§2)](#building-the-vocabulary-table-2)
+- [Numbers](#numbers)
+- [Words to delete on sight](#words-to-delete-on-sight)
+- [The mechanical pass](#the-mechanical-pass)
+
+## Why STE, and what it is not
+
+Simplified Technical English comes from aerospace maintenance manuals, where a misread sentence
+grounds an aircraft. It constrains grammar and vocabulary so that a sentence has exactly one reading.
+
+It is **not** writing for a beginner. Your reader may be more senior than you. They are expert in a
+*different* area, and they are reading fast. STE removes the work of guessing which of two readings
+you meant, so their attention goes to your argument instead of your syntax.
+
+A side effect worth knowing: STE makes weak claims obvious. "Performance was somewhat impacted by
+the configuration" survives normal prose. Rewritten as "the configuration made X slower by Y" it
+either gets a number or gets deleted. **The rewrite pass is also a truth pass.**
+
+## The rules
+
+1. **One idea per sentence.** Target under 20 words. Split on `and`, `but`, `which`, `;`, and any
+   comma joining two independent clauses.
+2. **One word, one meaning.** Fix each term in §2 and use only that term. Synonym variation is good
+   literary style and bad technical style — the reader cannot tell whether "engine", "runtime", and
+   "backend" are three things or one.
+3. **One meaning, one word.** The converse: never use a defined term for anything else. If "program"
+   means the installable wrapper, do not also call a Python script a "program".
+4. **Active voice, actor named.** "We withdrew the result" > "the result was withdrawn". Passive
+   hides who did it, and in an investigation write-up that is exactly the information at stake.
+5. **Present tense for what is true, past tense for what was measured.** "Decode is 91.6% of the
+   time" (a property). "We measured 223 samples" (an event).
+6. **No idiom, no metaphor, no humour, no rhetorical questions.** These are the constructs that
+   translate worst and skim worst.
+7. **No hedging without a size.** Not "it seems likely" — instead name the uncertainty: "we measured
+   this once, with a test prompt, not a real prompt".
+8. **Never open a paragraph with a bare pronoun** referring to the previous paragraph. Readers land
+   mid-page. Name the subject again.
+9. **Front-load the sentence.** Subject and verb in the first six words. Put conditions after the
+   main clause: "Use TCC mode if the server runs as a Windows service" — not "If the server runs as
+   a Windows service, then in that case TCC mode should be used."
+10. **Lists for lists.** If a sentence contains three or more parallel items, make it a bulleted list
+    or a table. Prose is for judgement, not enumeration.
+11. **Bold the answer, not the emphasis.** Bold carries the sentence a skimming reader must not miss.
+    If half a paragraph is bold, none of it is.
+12. **Define on first use, inline, and again in §2.** The reader will not follow a link mid-document.
+
+## The rewrite table
+
+| Instead of                                                | Write                                                     |
+| --------------------------------------------------------- | --------------------------------------------------------- |
+| utilize, leverage                                         | use                                                       |
+| initiate, commence                                        | start                                                     |
+| terminate                                                 | stop                                                      |
+| in order to                                               | to                                                        |
+| due to the fact that                                      | because                                                   |
+| at this point in time                                     | now                                                       |
+| a number of, several                                      | the number (or "about 12")                                |
+| significantly faster                                      | 1.9 times faster                                          |
+| performance degradation was observed                      | it became slower — by X                                   |
+| there is a possibility that                               | X may happen if Y                                         |
+| it should be noted that                                   | *(delete; state the thing)*                               |
+| we were unable to determine                               | we did not measure this. To measure it: \<method\>        |
+| the aforementioned approach                               | *(name it)*                                               |
+| this is non-trivial                                       | this takes \<time\> and needs \<thing\>                   |
+| best-in-class, industry-standard, robust                  | *(delete; give the number or the source)*                 |
+| optimize, improve                                         | make faster / make smaller / reduce cost — say which      |
+| The result was withdrawn.                                 | We withdrew the result.                                   |
+
+## Building the vocabulary table (§2)
+
+Include a term when **any** of these is true:
+
+- It is an acronym (`TCC`, `MoE`, `GGUF`, `SLA`).
+- Two readers in the thread have used it to mean different things. These are the highest-value rows.
+- It has a common meaning and a narrow meaning here ("program", "engine", "wrapper", "load").
+- Your argument turns on the distinction between it and a neighbouring term.
+
+Format — one meaning, in plain words, using only terms already defined:
+
+```markdown
+| Word            | Meaning                                                                       |
+| --------------- | ----------------------------------------------------------------------------- |
+| **Token**       | A piece of a word. About 4 characters of English. A model reads and writes tokens. |
+| **Engine**      | The software that does the mathematics on the GPU.                            |
+| **Wrapper**     | A program that contains an engine, but does not replace it.                   |
+```
+
+Eight to twelve rows is typical. Above about fifteen, the table stops being read — move the rare
+terms to inline definitions at first use.
+
+Open the section with the instruction, not just the table: *"Use these words with one meaning only."*
+
+## Numbers
+
+Every number in the document carries three things, either inline or in the table it sits in:
+
+- **The unit.** "659 tokens per second", not "659".
+- **The basis.** Measured or calculated? From what sample? On what date? "measured from `gpt-4o`",
+  "223 samples", "measured 2026-08-07".
+- **Its precision.** Write "about 125" when the run-to-run spread is ±10. False precision ("125.4")
+  invites a challenge you cannot defend, and burns the credibility of the numbers that *are* exact.
+
+Ratios beat percentages when the gap is large: "about 5 times too slow" lands harder and is
+remembered better than "80% below target". Percentages are right for small differences: "0.3%
+slower".
+
+State the direction: "10.3% slower" not "10.3% difference".
+
+## Words to delete on sight
+
+`basically`, `essentially`, `simply`, `just`, `obviously`, `of course`, `clearly`, `actually`,
+`very`, `quite`, `fairly`, `really`, `arguably`, `interestingly`, `unfortunately`, `it turns out
+that`, `as we all know`.
+
+Each one either adds nothing or, worse, tells the reader their question was stupid. "Simply run the
+benchmark" is a sentence that makes a reader who then fails feel foolish, and they will not tell you.
+
+## The mechanical pass
+
+Work through the draft once per rule. Batching is faster and catches more than reading for "style".
+
+1. **Sentence length.** Find every sentence over 25 words. Split or cut it.
+2. **Passive voice.** Search `was `, `were `, `been `, `is being`. Rewrite with the actor named,
+   or confirm the actor genuinely does not matter.
+3. **Synonyms for defined terms.** For each row of §2, search the document for its synonyms and
+   replace them.
+4. **Bare numbers.** Search for digits. Every hit needs a unit and a basis.
+5. **Filler.** Search the delete-on-sight list.
+6. **Paragraph openings.** Scan the first three words of each paragraph for `This`, `It`, `They`,
+   `That`.
+7. **Read the five-line summary cold**, as though you had read nothing else.

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

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.26",
+  "version": "1.3.28",
   "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,176 @@
+---
+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
+```

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

@@ -0,0 +1,176 @@
+---
+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
+```