@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/plan-dead-code/references/output-templates.md

@@ -0,0 +1,133 @@
+# Output template — `plan-dead-code.md`
+
+Copy this shape. The numbers below are illustrative; every count in a real
+report comes from an executed command, and the only estimated column is
+"After Phase 1".
+
+**One row per chain head.** A dead file explains its own exports and the
+packages only it imported — those are *children*, listed in the last column,
+never as separate rows. Twenty-seven findings that collapse to three heads is
+a three-row table, and reporting it as twenty-seven inflates the work.
+
+````markdown
+# Dead-Code Audit — <repo>
+
+_Audit-only. Nothing is deleted, fixed, or installed until each phase is approved._
+
+## Stack fingerprint
+- Bundler: Vite 6 · React 19 · TS paths: yes (`@/*`)
+- shadcn: `src/components/ui` (34 files)
+- Supabase: types at `src/types/supabase.ts` · Edge Functions: `supabase/functions` (5)
+- Dynamic surfaces: `src/router.tsx:18` template-string lazy import
+- Existing: no knip config · ESLint `no-unused-vars: warn` · tsconfig `noUnusedLocals: false`
+- Behavior locked by tests? partial — `src/lib/**` covered, `src/routes/**` not
+
+## Proposed `knip.json`
+```json
+<adapted from references/knip-config.md>
+```
+Configuration hints resolved: 3 (vite plugin entry, vitest plugin, tailwind postcss)
+First-run findings: 312 → after configuration: 41. **271 were never dead code.**
+
+## Baseline
+| Issue type | `--production` | default | After Phase 1 (est.) |
+|---|---|---|---|
+| Unused files | 9 | 15 | 0 |
+| Unused dependencies | 4 | 4 | 0 |
+| Unused devDependencies | 0 | 3 | 3 |
+| Unlisted dependencies | 1 | 1 | 0 (add) |
+| Unresolved imports | 0 | 0 | 0 |
+| Unused exports | 22 | 61 | ~6 |
+| Unused exported types | 6 | 22 | ~4 |
+| Unused enum members | 0 | 4 | 4 |
+| Duplicate exports | 0 | 2 | 2 |
+| **Total (`--max-issues` seed)** | **12** | **41** | — |
+
+Production mode is the number that should reach 0 first: those are findings in
+shipped code.
+
+## Findings (chain heads only)
+| # | Type | Path / symbol | Verdict | Sev | Effort | Children |
+|---|---|---|---|---|---|---|
+| D1 | file | `src/lib/formatDate.ts` | kill | Med | S | dep `date-fns`, exports ×3 |
+| D2 | file | `src/components/ui/{accordion,carousel,…}.tsx` ×7 | kill — unused shadcn, re-addable | Low | S | exports ×14, dep `embla-carousel-react` |
+| D3 | file | `src/components/DashboardV2.tsx` | kill — router imports `Dashboard.tsx` | Med | S | exports ×2 |
+| D4 | export | `src/lib/utils.ts` — 23 of 31 exports unused | kill barrel; inline 8 to callers | Med | **M** | — |
+| D5 | dep | `axios` (fetch used everywhere) | kill | **High** — advisory GHSA-… | S | — |
+| D6 | unlisted | `clsx` imported, never declared | add at the resolved version | Med | S | — |
+| K1 | file | `src/routes/Admin.tsx` | keep-config → `entry: ["src/routes/*.tsx!"]` | — | S | — |
+| K2 | export | `src/lib/api.ts#client` | keep-tagged → `@public` (used by `scripts/`) | — | S | — |
+| K3 | export | `src/hooks/useAuth.ts#__testReset` | keep-tagged → `@internal` (production mode only) | — | S | — |
+| N1 | file | `public/img/legacy/**` (12 files) | needs-owner — reached by template string? | — | S | — |
+
+Verdicts: `kill` · `keep-tagged` · `keep-config` · `needs-owner`. **A keep row
+always names its remedy** — a keep with no remedy is an `ignore` in disguise,
+and the next agent will delete it.
+
+## Residue metrics
+| Metric | Count |
+|---|---|
+| `console.log/debug/info` outside tests | 41 |
+| `debugger` | 2 |
+| `.only` / `.skip` / `.todo` | 1 / 6 / 0 |
+| commented-out code blocks | 18 |
+| `@ts-ignore` + `@ts-expect-error` / `eslint-disable` | 9 / 14 |
+| `: any` / `as any` | 37 |
+| empty `catch {}` | 5 |
+| unused locals (`tsc --noEmit`) | not run — `noUnusedLocals` is off |
+| orphan `public/` assets | 12 (3.4 MB) |
+| env referenced-not-declared / declared-not-referenced | 2 / 5 |
+| duplication (`jscpd`) | 6.2% · 7 clones ≥50 tokens |
+| `*V2` / `*New` / `*Old` / `* copy` files | 4 |
+| **bundle leak (`service_role` in `dist`)** | **0 — clean** |
+
+## Root causes
+Not a list of items — the thing to fix:
+1. `src/lib/utils.ts` is a dumping ground (D4). One split removes 23 findings.
+2. shadcn was installed wholesale (D2). 7 of 34 components are unwired.
+3. `noUnusedLocals` has never been on, so nothing inside files was ever checked.
+
+## Phased burndown
+- **Phase 1 — Config + files** → commit `knip.json`; delete D1–D3. Re-run; expect deps to *rise* before they fall.
+- **Phase 2 — Exports + types** → `--fix-type exports,types`; split D4; linter cascade; repeat until stable.
+- **Phase 3 — Dependencies** → remove D5 + chain survivors; add D6; clean install; build.
+- **Phase 4 — Residue** → console, `debugger`, `.only`, commented blocks, orphan versions, assets, `.env.example` sync.
+- **Phase 5 — Suppressions** → 9 `@ts-ignore` → fix or `@ts-expect-error` + reason.
+- **Phase 6 — Ratchet** → `knip` script + CI job at `--max-issues 3`, into the `housekeep-gates` aggregator.
+- **Phase 7 — Supabase arm** → 2 never-queried tables, 1 uninvoked Edge Function, 3 unused indexes, types-drift guard. Drops are migrations, after approval.
+
+Risk per phase, and what must keep working: Phase 1 must not break the
+template-string router (K1); Phase 3 must not remove a dep reached only from
+`tailwind.config.ts`; Phase 7 touches no production data.
+
+## Ratchet target
+`--max-issues` seed: 41 default / 12 production → after Phase 3: ≤10 / 0 → target 0 / 0.
+Duplication 6.2% → ≤4%. Suppressions 23 → ≤15. All shrink-only.
+
+## Execution handoff
+Approve a phase to run it via `housekeep-dead-code`. `.skip` rows and TODO
+counts → `housekeep-backlog`. Duplication → `workflow-refactor`. Schema drops →
+`plan-data-integrity` then `db-migrator`.
+````
+
+## Why the table has a Children column
+
+Without it, agents report chains as independent findings and the plan looks
+five times larger than the work. The re-run after Phase 1 is where children
+disappear — and where a *few new* findings appear, because deleting a file can
+orphan the dependency only it imported. Both directions are expected; say so
+in the plan so the apply pass does not treat the delta as a surprise.
+
+## Severity and effort
+
+**Severity** — High: an unused dependency with an open advisory, an orphan file
+holding credentials or PII fixtures, duplicated business logic that has already
+diverged. Medium: unused files and exports. Low: unused types, enum members,
+class members.
+
+**Effort** — S: delete a file, drop an `export` keyword. M: a barrel, a
+dumping-ground split, a duplicate merge. L: anything needing a framework config
+change or a database migration.
+
+Severity orders the phases; effort decides whether an item belongs here or in
+`workflow-refactor`.

package/skills/plan-dead-code/references/preservation-contract.md

@@ -0,0 +1,50 @@
+# Preservation contract — plan-dead-code
+
+This pass produces a document. It changes no behavior and no files other than
+writing `plan-dead-code.md`.
+
+## Never do in this pass
+
+- **Delete, `--fix`, `rm`, or edit `package.json` / the lockfile.** The
+  deliverable is a report plus a *proposed* config.
+- **Commit `knip.json`.** It lives in the report; `housekeep-dead-code`
+  commits it.
+- **Add an `ignore` glob** for anything other than a machine-generated file
+  you regenerate rather than edit. `entry`, `paths`, `--production`, and the
+  `@public` / `@internal` / `@alias` tags are the real remedies.
+- **Report a chain child as its own finding.** Children live under their head.
+- **Treat a passing test as proof something is alive.** Production mode
+  decides reachability; a test that only imports dead code is dead too.
+- **Print an env value, a token, or a connection string.** Names only.
+- **Write to a database.** Every schema query in Phase 3g is read-only.
+- **Estimate a count.** Every baseline number comes from an executed command.
+  If a check could not run, the row reads `not run` with the reason.
+
+## Before any change proposal
+
+One line per phase: **what currently works here that must keep working.** The
+router, the auth flow, the build, the scripts CI runs, the webhook nobody
+imports. A phase without that line is not reviewable.
+
+## Verdict buckets
+
+| Bucket | Meaning |
+|---|---|
+| `kill` | Unreachable in production mode *after* the config was settled |
+| `keep-tagged` | Reachable, or deliberately public — remedy is `@public` / `@internal` / `@alias` |
+| `keep-config` | The finding is a gap in Knip's model — remedy is `entry`, `paths`, or a plugin |
+| `chain` | Disappears when its parent goes; not counted separately |
+| `needs-owner` | Plausibly dead, but a human must decide. Never upgraded to `kill` to shrink the list |
+| `defer` | Real, but over M effort → `workflow-refactor` / `housekeep-backlog` |
+
+## The failure this contract prevents
+
+An agent runs `knip` on a vibe-coded repo, gets three hundred findings, and
+starts deleting. Typecheck stays green and the unit tests stay green, because
+neither can see a route loaded by template string, an Edge Function called by
+a Stripe webhook, or an asset referenced from a CSS `url()`. The app breaks in
+production, and the commit that broke it deleted forty other things at the same
+time.
+
+Configuration first, evidence per row, and one category per commit exist to
+make that specific outcome impossible.

package/skills/plan-dead-code/references/residue-greps.md

@@ -0,0 +1,84 @@
+# Residue grep pack
+
+What Knip cannot see: junk *inside* live files, plus assets, env, and
+duplication. `plan-dead-code` records the counts; `housekeep-dead-code`
+applies the fix column. Adjust `src` to the detected source directory.
+
+**Counting convention.** Use `rg -o … | wc -l` for a repo total of *matches*.
+`rg -c` prints per-file counts of matching *lines*, so two `console.log` calls
+on one line count once — fine for triage, wrong for a ratchet. Pick one and
+keep it: the baseline and the post-cleanup number must be produced by the same
+command or the ratchet compares nothing.
+
+| Class | Count command | Fix (housekeep only) |
+|---|---|---|
+| Debug logging | `rg -o "console\.(log\|debug\|info)\(" src --glob '!**/*.{test,spec}.*' \| wc -l` | Delete, or route through the project's existing logger. **Never add a logger to satisfy this pass.** `console.error/warn` in catch blocks stay. |
+| `debugger` | `rg -n "^\s*debugger;?\s*$" src` | Delete |
+| Focused tests | `rg -n "\b(it\|test\|describe)\.only\(" src tests e2e 2>/dev/null` | Remove the **modifier**. `.only` silently disables the rest of its file, so the suite may go red — that is a bug it was hiding |
+| Skipped tests | `rg -n "\b(it\|test\|describe)\.(skip\|todo)\(\|\bx(it\|describe)\(" src tests e2e 2>/dev/null` | Do not delete the test → un-skip and fix, or register rows in `housekeep-backlog` |
+| Commented-out code | `rg -n "^\s*//\s*(const\|let\|var\|import\|export\|return\|if \(\|for \(\|await \|function\|\}\|<[A-Za-z])" src` | Delete the block. Git is the archive; "keep for reference" is not a reason |
+| Placeholders | `rg -n -i "your logic here\|implement me\|lorem ipsum\|placeholder text\|TODO: implement" src` | Wire or delete. If the control is user-visible → `plan-stub-checker` |
+| TODO / FIXME / HACK | `rg -o "TODO\|FIXME\|HACK\|XXX" src \| wc -l` | Count only → `housekeep-backlog` |
+| Orphan versions | `rg --files src \| rg -i "(v2\|v3\|new\|old\|copy\|backup\|final\|tmp)\.(tsx?\|css)$"` | Confirm which one the router/imports actually use; delete the rest. The survivor keeps its original name |
+| Dumping grounds | see script below | >15 exports: split by domain, or inline single-caller helpers |
+| `@ts-ignore` / `@ts-expect-error` | `rg -o "@ts-ignore\|@ts-expect-error" src \| wc -l` | Fix the type, or convert to `@ts-expect-error <reason>` — it self-expires, and TS reports it once the error is gone |
+| `eslint-disable` | `rg -o "eslint-disable\|biome-ignore" src \| wc -l` | Per-line with a reason, or fix. File-level disables are removed and the file fixed |
+| `any` | `rg -o ":\s*any\b\|as any\b\|<any>" src \| wc -l` | Ratchet metric. Fix only where it hides a real bug this pass. **Never widen a type to remove a suppression** |
+| Empty catch | `rg -n -U "catch\s*(\([^)]*\))?\s*\{\s*\}" src` | Log + rethrow, or one line saying why swallowing is correct |
+| Orphan assets | see script below | Delete. Confirm no reference from CSS, `index.html`, or storage seeds first |
+| Env drift | see script below | Add missing keys to `.env.example`; remove declared-but-unreferenced. **Names only — never print values** |
+| Duplication | `npx jscpd src --min-tokens 50 --min-lines 5 --reporters console` | Behavior-preserving → `workflow-refactor`, never bundled with a deletion commit |
+| Bundle leak | `npm run build && rg -l "service_role\|SUPABASE_SERVICE_ROLE" dist` | **Any hit stops the pass** → `plan-secrets-audit` immediately |
+
+The bundle-leak row is not dead-code hygiene — it is the one check here that
+can find a live credential in shipped output. Run it even if the rest of
+Phase 3 is skipped.
+
+## Dumping grounds
+
+An AI-written `lib/utils.ts` accretes helpers nobody deletes. Rank by export
+count so the barrel itself becomes the finding:
+
+```bash
+for f in $(rg --files src | rg "(utils|helpers)/.*\.tsx?$|lib/utils\.tsx?$"); do
+  echo "$(rg -c '^export ' "$f" 2>/dev/null || echo 0) $f"
+done | sort -rn
+```
+
+If one file explains twenty unused-export findings, that is **one M-effort
+fix**, not twenty S-effort ones. Report the barrel.
+
+## Orphan assets
+
+```bash
+for f in $(find public -type f ! -name "*.md" 2>/dev/null); do
+  b=$(basename "$f")
+  rg -q --fixed-strings "$b" src index.html 2>/dev/null || echo "orphan: $f ($(du -h "$f" | cut -f1))"
+done
+```
+
+Repeat for `src/assets` against `src`. Because the loop searches `src`, fonts
+referenced only from a CSS `@font-face` count as used.
+
+**Known false positive:** hashed or templated references
+(`` `/img/${slug}.png` ``, Vite's `new URL('./x.png', import.meta.url)`) never
+match a basename scan. A directory reached only by template string is
+`needs-owner`, not dead.
+
+## Env drift
+
+Both directions matter: referenced-but-undeclared breaks production;
+declared-but-unreferenced is dead config.
+
+```bash
+rg -o "import\.meta\.env\.[A-Z0-9_]+" src | sed 's/.*env\.//' | sort -u  > /tmp/env-used
+rg -o "process\.env\.[A-Z0-9_]+"      src | sed 's/.*env\.//' | sort -u >> /tmp/env-used
+sort -u -o /tmp/env-used /tmp/env-used
+rg -o "^[A-Z0-9_]+" .env.example | sort -u > /tmp/env-declared
+
+echo "referenced, not declared:"; comm -23 /tmp/env-used /tmp/env-declared
+echo "declared, not referenced:"; comm -13 /tmp/env-used /tmp/env-declared
+```
+
+Any `VITE_` / `NEXT_PUBLIC_` key whose value is not meant for the browser is a
+secrets finding, not an env-hygiene one → `plan-secrets-audit`.

package/skills/plan-dependency-provenance/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: plan-dependency-provenance
+description: >
+  Plan-only audit of dependencies for hallucinated or slopsquatted packages,
+  supply-chain risk, and license gaps. Use when "check my dependencies", "is
+  this package real", "slopsquatting", "SBOM", or "did the AI hallucinate a
+  package".
+license: MIT
+effort: high
+---
+
+# Dependency Provenance & Supply-Chain Audit + Remediation Plan
+
+**Degree of freedom: HIGH** — resolve, classify, plan. Stay **plan-only**.
+Never install a suspect package to "check".
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **plan-dependency-provenance** (this) | Slopsquatting / SBOM / license plan |
+| `plan-security-audit` | OWASP umbrella burndown |
+| `workflow-housekeep` | Apply dependency updates after approval |
+| `plan-dead-code` | Unimported deps + unreachable source (graph fact) |
+
+## How to reason (every plan item)
+
+1. **Propose** — verify, remove, pin, or license-remediate a package
+2. **Risk** — squat, unsigned install, license conflict, or lockfile roll
+3. **Keep-working** — packages that already resolve, pin, and license clean
+4. **Phase** — verify/remove → lock & pin → license → de-bloat (do not execute)
+
+## Worked example
+
+> **Propose:** remove `fast-cache-utils` (no registry hit); do not `npm install` it to "check".
+> **Risk:** AI-suggested name is a squat — install *is* the attack.
+> **Keep-working:** `zod` resolves, MIT, maintained repo.
+> **Phase:** Phase 1 — verify/remove suspect packages.
+
+**Role:** Senior supply-chain engineer + open-source compliance specialist.
+
+**Task:** Resolve every direct dependency against its registry, run checklist A–E,
+build the provenance table, phase remediations, emit `plan-dependency-provenance.md`.
+**Audit & plan only — never install suspect packages to verify.**
+
+**Verify every package is real, safe, and licensed. Install nothing until approved.**
+
+In a vibe-coding loop "just install the suggested package" is the default move —
+and it's now a documented attack surface. The Cloud Security Alliance's 2026
+research found AI coding tools recommend **non-existent package names ~20% of the
+time**, and **43% of those hallucinated names recur on every run of the same prompt.**
+Consistent hallucinations are predictable; predictable names are registerable.
+Attackers pre-register them on npm/PyPI — **slopsquatting** — then wait for
+developers (or autonomous agents) to run the exact `npm install` / `pip install`
+the AI just wrote. With agents executing their own generated install commands, the
+human checkpoint disappears entirely.
+
+This skill is the **audit-and-plan** half. Execution (removal, replacement, pinning,
+license remediation) is handed off after you approve each phase.
+
+---
+
+## When this fires
+
+Trigger phrases: *"check my dependencies"*, *"is this package real"*,
+*"slopsquatting"*, *"are my packages safe"*, *"audit my supply chain"*, *"license
+check"*, *"generate an SBOM"*, *"did the AI invent a package"*, *"pre-launch /
+pre-open-source dependency audit"*.
+
+Do **not** fire for: routine version bumps (`/update-deps`), bundle-size trimming
+(`audit-bundle-size`), or general repo cleanup (`workflow-housekeep`). This skill
+owns *existence, integrity, provenance, and licensing* of dependencies.
+
+---
+
+## Why a dedicated skill
+
+`/update-deps` assumes the packages are *legitimate* and just need upgrading.
+This skill asks the prior question the AI era forces: *is this package even real,
+who published it, when, and under what license?*
+
+---
+
+## The audit  [HIGH freedom]
+
+### A · Existence & slopsquatting (the AI-era core)
+- **Resolve every direct dependency** against its registry, including names you recognize — recognizing a name is not knowing its current registry state. Flag any that don't
+  exist, were published very recently, have near-zero downloads, or inconsistent history.
+- **Typo / confusion check** — names one edit away from a popular package
+  (`reqests`, `lodahs`), or conflation names merging two real packages.
+- **AI-origin flag** — obscure/novel deps in vibe-coded projects: guilty-until-verified.
+- **Maintainer & repo signals** — no source repo, single recent maintainer: elevate.
+
+### B · Lockfile & integrity
+- **Lockfile present and committed?** No lockfile = every install is a fresh roll.
+- **Pinned vs floating** — wildcard/`^`/`latest` on security-sensitive deps.
+- **Lockfile drift** — manifest and lockfile disagree.
+
+### C · Provenance & patch history
+- **Source repo reachable**, actively maintained, not archived.
+- **Known vulnerabilities** — flag deps with open advisories (recommend Socket.dev /
+  Phylum / `npm audit` / `pip-audit` in execution).
+- **Install scripts** — postinstall reaching network/filesystem: flag for review.
+
+### D · Licensing
+- **License inventory** — SPDX per dependency. Flag copyleft in proprietary paths,
+  "no license", conflicts with project license.
+- **Attribution gaps** — bundled code lacking NOTICE.
+
+### E · Bloat & blast radius
+- **Transitive depth** — direct vs total; duplicate libs.
+- **Unused dependencies** — declared but never imported. Flag the *manifest
+  fact* here; the module-graph proof and removal belong to `plan-dead-code`
+  → `housekeep-dead-code`. Do not hand-verify with a grep — a dep reached
+  only from a config string looks unused and is not.
+
+For each finding: package, issue, evidence, severity, remediation *direction*.
+
+---
+
+## Procedure  [HIGH freedom]
+
+1. **Inventory.** Parse manifests + lockfiles. State ecosystems and resolution limits.
+2. **Resolve & classify.** Checklist A–E. Tag Critical / High / Med / Low.
+3. **Build the provenance table** — key artifact.
+4. **Phase the burndown.** Verify/remove suspect packages first.
+5. **Emit `plan-dependency-provenance.md`, then end the turn** with a standalone recap in chat: the two or three highest-impact findings and the first phase to approve. The file is the deliverable — write it before the recap. **Do not install anything.**
+
+---
+
+## Guardrails  [LOW freedom — run exactly]
+
+- **Plan only.** No `install`, `add`, `remove`, `update`, or lockfile edits.
+- **Never install to "check".** That is exactly the attack.
+- **Guilty until verified** for AI-suggested obscure deps.
+- **Existence ≠ safety.** Run the full checklist.
+- **License is a real finding.**
+- **Recommend `create-hook`** pre-install allowlist as regression gate.
+- **Minimal quoting** of manifests.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — registry resolve (or "none found"), not vibe
+2. **plan-only** — no install/add/remove/update to "check"
+3. **phase justified** — squat/non-existent is Phase 1, not de-bloat
+4. **right-owner** — routine bumps → `/update-deps`; bundle trim → `audit-bundle-size`; unimported deps + dead source → `plan-dead-code`
+5. **no-false-safety** — exists ≠ safe; license is a finding
+
+---
+
+## Report template — `plan-dependency-provenance.md`
+
+```markdown
+# Dependency Provenance & Supply-Chain Audit — <repo>
+
+_Audit-only. Nothing is installed, removed, or upgraded until each phase is approved._
+
+## Scope
+- Ecosystems: npm ☐ pip ☐ other ☐  | Direct deps: n  Transitive: n
+- Lockfile(s): present ☐ committed ☐  | Assumptions: …
+
+## Verdict
+| Severity | Count | Worst case |
+|----------|-------|-----------|
+| Critical | n | non-existent / squat-suspect / malicious package installed |
+| High     | n | no lockfile, license conflict, open advisory |
+| Medium   | n | floating pins, abandoned upstream |
+| Low      | n | bloat, unused deps |
+
+## Provenance table (suspect + notable)
+| Package | Exists? | First pub | Weekly DLs | License | Repo | Verdict |
+|---------|---------|-----------|------------|---------|------|---------|
+| fast-cache-utils | ❓ none found | — | — | — | none | Crit: likely hallucinated → remove |
+
+## Findings
+| # | Package | Issue | Evidence | Sev | Direction |
+|---|---------|-------|----------|-----|-----------|
+
+## Phased burndown
+- **Phase 1 — Verify/remove suspect packages** → manual verify + removal
+- **Phase 2 — Lock & pin** → `workflow-housekeep`
+- **Phase 3 — License & advisories** → wire Socket.dev/Phylum/npm-audit
+- **Phase 4 — De-bloat** → remove unused/duplicate deps
+- **Gate** → `create-hook` pre-install allowlist
+
+## Execution handoff
+Approve a phase to run it. Re-scan after; add the install-time gate.
+```
+
+---
+
+## Chains with
+
+- **Pre-launch hardening loop** — supply-chain layer alongside security spine.
+- **`plan-secrets-audit`** — both feed `create-hook` regression gates.
+- **Execution:** `workflow-housekeep`, `create-hook`, `/update-deps` (after verified),
+  `audit-security`.
+- **Verify:** re-resolve tree; confirm install-time gate is live.
+
+> Planned at high effort; executed at the default effort under the approved-plan execution rule (`approved-plan-execution.mdc`). The plan says *which* packages are suspect; the rule forbids "just installing it to see".

package/skills/plan-docs-sync/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: plan-docs-sync
+description: >
+  Plan-only audit of documentation against actual code behavior. Use when
+  "docs drift", "sync docs with code", "audit documentation", "stale README",
+  "onboarding docs broken", "phantom docs", or "docs out of date".
+  Decisions/ADRs → docs-adr.
+license: MIT
+effort: high
+---
+
+# Docs Drift Audit + Sync Plan
+
+**Degree of freedom: MIXED** — inventory globs are exact; drift judgment
+is high. Stay **plan-only**. No rewrites until approved.
+
+**Role:** Senior engineer + technical writer.
+
+**Task:** Audit all documentation against what the code **actually does**, find every drift,
+plan corrections. README, CONTRIBUTING, setup/onboarding, API docs, JSDoc/docstrings,
+architecture notes, `.env.example`, CLI `--help`, changelogs. **Audit & plan only.**
+
+## This skill vs neighbors
+
+| Skill | Does |
+|-------|------|
+| **plan-docs-sync** (this) | Plan doc corrections from code truth |
+| `docs-writer` | Write/improve docs (execution) |
+| `workflow-housekeep` | README refresh as part of housekeeping |
+| `plan-stub-checker` | Stubs/dead UI — often surfaces phantom docs |
+
+**Loop position:** run **last** in the six-skill plan loop. See `docs/PLAN-LOOPS.md`.
+
+## How to reason (every plan item)
+
+1. **Propose** — correction that makes the doc match code truth
+2. **Risk** — onboard fail, phantom API, or invented behavior if left stale
+3. **Keep-working** — claims already backed by path:line
+4. **Phase** — factual drift first; wording last (do not execute)
+
+## Worked example
+
+> **Propose:** drop `STRIPE_WEBHOOK_SECRET` from the README setup list (absent from `.env.example` and code); document `POST /v1/webhooks/stripe` which exists undocumented.
+> **Risk:** onboarding fails on a phantom env var; integrators miss a live endpoint.
+> **Keep-working:** CONTRIBUTING install steps match `package.json` scripts.
+> **Phase:** first sync slice — factual drift only.
+
+---
+
+## ⛔ Preservation Contract  [LOW freedom — run exactly]
+
+Read `references/preservation-contract.md`. Acknowledge in output #1.
+
+Core guardrail: **docs describe real, current behavior — never aspirational or invented.**
+
+---
+
+## References
+
+| File | Contents |
+|------|----------|
+| `references/drift-taxonomy.md` | Types, detection passes, guardrails |
+| `references/output-templates.md` | Burndown, phased sync plan |
+
+---
+
+## Phase flow
+
+```
+1. Inventory all doc surfaces
+2. Code-as-source-of-truth pass
+3. Reverse pass (missing docs)
+4. Onboarding replay (.env.example + CLI help)
+5. Signature + cross-doc consistency + links
+6. Burndown + phased sync plan
+7. Research + guardrails (docs-as-code, CI drift checks)
+```
+
+---
+
+## Phase 1 — Doc inventory  [LOW freedom — run exactly]
+
+```
+Glob: README.md CONTRIBUTING.md docs/**/*.md **/*README*.md
+Glob: .env.example
+```
+
+List: README, CONTRIBUTING, docs/, inline JSDoc targets, OpenAPI, CLI help, changelog.
+
+---
+
+## Phase 2–5 — Detection  [HIGH freedom]
+
+Execute all passes in `references/drift-taxonomy.md`.
+
+**Onboarding-drift check (standout):** extract env var names + setup commands from onboarding docs; diff against `.env.example` keys and `package.json` scripts; run CLI `--help` where safe and compare.
+
+Every drift: **doc claim** + **code truth** (path:line). Can't verify → `[NEEDS VERIFICATION]`.
+
+---
+
+## Phase 6 — Burndown + sync plan  [HIGH freedom — plan only]
+
+Template: `references/output-templates.md`
+
+Quantify: e.g. "9 phantom env vars, 14 undocumented endpoints, 6 onboarding steps that fail".
+
+Per drift: before/after correction + "what's still accurate here". **Plan only — no rewrites until approval.**
+
+**Industry enhancements** (Firecrawl, current year): docs-as-code, doc-in-same-PR, CI drift vs `.env.example` + CLI help, generated API refs, `llms.txt`.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — every drift is doc claim + code path:line (or `[NEEDS VERIFICATION]`)
+2. **plan-only** — no rewrites; deletions are proposals
+3. **phase justified** — factual drift before wording polish
+4. **right-owner** — why-we-chose-X → `docs-adr`; stubs/dead UI → `plan-stub-checker`
+5. **no-false-safety** — never document invented or aspirational behavior
+
+---
+
+## Required output (in order)
+
+1. Preservation-contract acknowledgment
+2. Drift taxonomy results (counts per type)
+3. Per-doc drift inventory (checklist)
+4. Burndown table (code-truth + risk)
+5. Sync + enhancement plan, phased
+6. Guardrails/tooling
+7. Research notes + citations
+8. Open questions / `[NEEDS VERIFICATION]` list
+
+End the turn with a standalone recap in chat: the two or three highest-impact drifts and the first sync slice to approve. The report is the deliverable — write it before the recap.
+
+---
+
+## Rules  [LOW freedom — run exactly]
+
+- Plan only — do not rewrite docs until approved.
+- Code is source of truth. Every drift = doc claim + code fact.
+- Never document invented or aspirational behavior.
+- Stale docs get corrected, not deleted. Deletions are proposals.
+- Separate factual drift vs subjective wording improvement.

package/skills/plan-docs-sync/references/drift-taxonomy.md

@@ -0,0 +1,43 @@
+# Drift Taxonomy & Methodology
+
+## Types
+
+| Type | Definition |
+|------|------------|
+| **stale** | Doc describes old behavior (renamed params, changed defaults, moved files) |
+| **missing** | Shipped feature/flag/endpoint/env with no docs |
+| **phantom** | Doc describes feature/route/option that no longer exists or never shipped |
+| **contradictory** | Two docs disagree, or doc vs inline comment disagree |
+| **onboarding-breaking** | Setup steps fail — wrong install cmd, env var mismatch, dead link, outdated version |
+| **inline-rot** | Comments/docstrings lie; `@param`/`@returns` ≠ signature |
+| **api-contract** | Documented request/response ≠ actual endpoint/schema |
+
+## Detection passes
+
+1. **Code-as-source-of-truth:** for each doc claim, find proving/disproving code. Cite both.
+2. **Reverse pass (missing docs):** routes, exported APIs, env vars, CLI commands, flags, config keys → zero docs?
+3. **Onboarding replay:** setup docs vs `package.json` scripts, `.env.example`, install/run, CLI `--help`.
+4. **Onboarding-drift CI pattern:** correlate doc env/setup claims against live `.env.example` + `npm run … -- --help` output.
+5. **Signature check:** JSDoc/docstring vs real function signature.
+6. **Cross-doc consistency:** README vs CONTRIBUTING vs inline vs API docs.
+7. **Link/asset check:** internal links, anchors, referenced files resolve.
+
+## Discovery commands
+
+```
+Glob: **/*.md **/docs/**
+Glob: **/.env.example
+Read: package.json scripts
+Shell: npm run <cli> -- --help  (when safe)
+Grep: "@param|@returns" glob "*.{ts,tsx,js,py}"
+Glob: **/openapi.* **/swagger.*
+```
+
+## Guardrails (research-backed)
+
+- **Docs-as-code:** doc updates in same PR as behavior change
+- PR checklist: "did behavior change? update doc in this PR"
+- CI: correlate onboarding docs vs `.env.example` + CLI help
+- Auto-generate API reference from OpenAPI/source where possible
+- Hand-written = *why*; generated = *what*
+- `llms.txt` for external AI-readable docs when applicable