@mrciphersmith/keryx 0.2.98 → 0.2.99

package/src/gdskills/bundled/skills/quality/api-truth/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: api-truth
+model_tier: deep
+description: |
+  Use when code is about to call a dependency nobody has read today — a client
+  method, an option object, a config key, a CLI flag — and the only thing
+  vouching for the signature is somebody's recollection of it. Recollection has
+  a cutoff date; the version resolved in this project does not. Settles what
+  "checked" means: the version actually installed here rather than the newest
+  one, the artefacts that carry it in rank order, and which side wins when the
+  published documentation and the installed build disagree. Every call that went
+  out unchecked is MARKED as unchecked, so a later reader can tell a verified
+  signature from a remembered one.
+  NOT for: moving a project onto newer releases of the packages it already has,
+  and NOT for picking which library or architectural pattern to adopt before
+  anything is installed.
+triggers:
+  - "check this against the installed version"
+  - "is that still the API"
+  - "did you make that signature up"
+  - "which version do we actually have"
+  - "look up the real API"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "quality"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# API Truth
+
+A remembered API call is a claim about a version. The claim is usually right,
+which is the problem: it fails quietly, in the small fraction of cases where the
+library moved, and it fails in the worst possible way — the code compiles, the
+option object accepts the unknown key and ignores it, and nothing surfaces until
+production or never.
+
+Model weights have a cutoff date. A dependency does not. The gap between them
+grows every day the project is alive, and no signal inside the editor announces
+it.
+
+This skill is not "look things up". Looking things up on every call is a rule
+agents follow twice and abandon. It is four decisions: **when** the check is
+worth its cost, **which version** counts as the truth, **what** counts as a
+source, and **how** the unchecked calls are marked so somebody downstream can
+see them.
+
+---
+
+## 1. The version is the one installed here, not the latest
+
+"I checked the docs" means nothing until it names a version. The default failure
+is checking the current documentation of a library this project pinned eighteen
+months ago — same defect as recollection, with a citation attached.
+
+Three different numbers exist, and only one of them runs:
+
+| Number | Where | What it is |
+|---|---|---|
+| The range | `package.json` / `pyproject.toml` / `go.mod` | What the project will *accept*. Not a version. |
+| The resolved version | `bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `poetry.lock`, `Cargo.lock`, `go.sum` | What a fresh install produces. |
+| The installed version | `node_modules/<pkg>/package.json` → `"version"`; `pip show <pkg>`; `cargo tree -p <pkg>` | What is on disk and executing **now**. |
+
+Read the third. When the third and the second disagree, the tree is stale and
+that is itself worth reporting — a call verified against a stale tree is
+verified against nothing anyone else has.
+
+For a transitive dependency, the version your direct dependency pulls is often
+not the version at the top level. Resolve the one on the actual path.
+
+## 2. When the check is worth paying for
+
+A skill that says *always verify everything* is ignored by the third task. The
+cost is real, so spend it where the failure is silent.
+
+**Check before writing the call when any of these hold:**
+
+- The symbol is not visible in types you can see — an untyped package, a config
+  object typed `Record<string, unknown>`, a CLI flag, an HTTP endpoint, a
+  template convention. Nothing will catch you.
+- The option is a **key in a bag**. Unknown keys in option objects, YAML, and
+  env-var maps are ignored in silence; a typo and a removed option are
+  indistinguishable from working code.
+- The call has an effect you cannot see locally — a write, a payment, an auth
+  decision, a migration, a cache invalidation, a webhook.
+- You know a major version boundary sits between your recollection and the
+  installed number, or you cannot say which side of one you are on.
+- Defaults matter to the behaviour you promised. Defaults change in *minor*
+  releases more often than signatures do, and no compiler mentions it.
+
+**Do not pay for it when:**
+
+- The call is typed and the type-checker runs on it. A strict `tsc --noEmit`
+  against the package's own shipped `.d.ts` **is** a check against the installed
+  version, performed by a machine, for free — that is §3's rank 1 already done.
+- A test you watched fail and then pass exercises this exact call path.
+- You read this same symbol, at this same version, earlier in this session.
+  Record it once; do not re-fetch per call site.
+- It is the language or runtime standard library at a version the toolchain
+  already pins.
+
+Everything outside both lists is a judgement call, and the tiebreaker is: how
+long would this defect stay invisible? Loud and immediate — write it and let the
+failure teach you. Silent — check first.
+
+## 3. What counts as a source, in rank order
+
+1. **The installed artefact itself** — the `.d.ts` beside the package, the
+   `node_modules` source, `inspect.signature`, the binary's `--help`. It cannot
+   be at the wrong version, because it *is* the version. Highest rank, and
+   usually the fastest to reach.
+2. **The package's own documentation, pinned to the installed version** — the
+   docs for the exact version installed, reached by whichever of these the
+   environment actually has. None of them ships with this skill or is installed
+   for you; check what is there before you reach for one:
+
+   - A versioned docs URL, or the repository at the tag matching that version.
+   - A docs-retrieval tool, where one is configured — a `ctx7`-style MCP server,
+     or `npx ctx7@latest library "Library Name" "<the actual question>"` then
+     `npx ctx7@latest docs /org/project/<installed-version> "<the question>"` if
+     that CLI is reachable. Official spelling ("Next.js", not "nextjs"), the real
+     question rather than one word, three commands of budget, no credentials.
+   - With neither, the docs shipped *inside* the installed artefact — its README,
+     its `docs/`, the binary's long help — pinned by construction. If that is
+     empty too, rank 2 is unavailable here: say so and rely on rank 1.
+3. **The package's own documentation, unpinned** — acceptable only after you
+   state the gap between it and the installed version, and treat everything it
+   says as provisional across that gap.
+4. **The changelog or migration guide**, for the narrow question of *what
+   changed between two versions you have named*. Not for what the API is now.
+5. **A blog post, a forum answer, another project's code, and your own
+   recollection** — all the same rank, which is *hypothesis*. They are worth
+   something: they tell you what to go and look at in ranks 1–3. They are worth
+   nothing as evidence, and a citation of one is not a check.
+
+## 4. When the documentation and the installed build disagree
+
+This is common, and it is the point where a careless agent picks the wrong side.
+
+**The installed artefact wins.** Documentation describes a version, usually the
+newest; `node_modules` is what executes. If the docs show an option the types do
+not have, the option does not exist here.
+
+The disagreement is not noise to route around — it is a finding, and it has to
+be named before you carry on:
+
+- Say which version the docs were at and which is installed. Nine times out of
+  ten the gap explains the disagreement, and now the next person does not
+  re-derive it.
+- Same version, still disagreeing? Then the docs are wrong, or you are reading a
+  different export path, or a patch/override is rewriting the package. Check the
+  path before concluding the docs are wrong.
+- Never split the difference by writing the documented call and adding a
+  fallback for the installed one. Two paths, one of which has never run, is a
+  larger defect than the one you were avoiding.
+- If the behaviour you need exists only in the documented version, that is an
+  upgrade decision and it belongs to whoever owns the dependency — say so, and
+  do not smuggle the bump in beside the feature.
+
+## 5. Marking what was not verified
+
+This is the part that survives into review, and the part agents skip.
+
+A checked call and a remembered call look identical in a diff. Unless the
+difference is written down, the reviewer inherits a file where every line
+carries the same implied confidence, and the one guess is camouflaged by forty
+facts around it.
+
+At the call site, on anything that went out unchecked:
+
+```
+// unverified: <symbol> against <pkg>@<version> — from recollection,
+// settle with: <the command or file that would settle it>
+```
+
+In the report or PR body, a short section that lists them: the symbol, the
+package and version, why the check was skipped (§2), and the one observation
+that would close it. An empty list is a fine result and should be stated as
+empty rather than omitted.
+
+And the converse, which is the cheaper half: when you *did* check, say against
+what. "Verified against `@aws-sdk/client-s3@3.620.0` types" is a sentence a
+reviewer can re-run. "I checked the docs" is not.
+
+Never mark a call verified on the strength of rank 5.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "It compiled, so the API is right." | Compilation proves the shape the *types* declare, and the silent failures live where types do not reach: unknown keys in an option bag, a string enum the library parses at runtime, a config file, a CLI flag. Those compile perfectly and do nothing. |
+| "I read the library's documentation, so this is checked." | Not until the version is named. The docs site serves the newest release; this project resolves whatever the lockfile says. An unversioned citation is a remembered call with a footnote — the same defect, harder to spot. |
+| "`package.json` says `^4.2.0`, so we are on 4.x." | That is the range the project accepts, not the build that is running. Read `node_modules/<pkg>/package.json`, and when it disagrees with the lockfile, say so — the tree is stale and nobody else's is like it. |
+| "The docs show this option but the types do not, so the types are out of date." | Backwards nearly every time. The types ship inside the installed package; the docs describe some version, usually a newer one. The artefact on disk is what executes — name the gap instead of overriding it. |
+| "I will write the documented call and add a fallback for the old signature." | You have shipped two branches and exercised one. The dead branch is never run, never tested and wrong in a way nobody discovers, and you took on that debt to avoid reading one file. |
+| "This is a well-known library, I have used it a hundred times." | Familiarity is the exposure, not the protection. The APIs recalled most confidently are the ones learned longest ago, so recollection is most stale exactly where it feels safest, and confident wrong calls skip their own review. |
+| "A blog post shows this exact pattern working." | It worked, at some version, on some day, for somebody whose lockfile you cannot see. That makes it a lead worth thirty seconds against the installed types — it does not make it evidence, and citing it does not turn a guess into a check. |
+| "Checking every call would take all day, so I checked none." | The list is not every call. It is the ones whose failure is silent — option bags, untyped surfaces, effects you cannot observe locally, changed defaults. Typed calls under a type-check are already verified; that is most of them. |
+| "I was not sure about two of these, but the rest are solid." | Then the two are invisible, because a diff shows no difference between them and the forty around them. Mark them at the call site with what would settle them, or the reviewer's only options are re-check everything or trust everything. |
+
+## Verification
+
+Do not report the work as done until all of these hold:
+
+- Every dependency call this change introduced is either verified against a
+  named source at a named version, or carries an `unverified:` marker at the
+  call site.
+- Each version named is the one installed on disk — read from the package's own
+  installed metadata, not from a manifest range — and any disagreement with the
+  lockfile is reported.
+- Every check cites its rank (§3): which artefact or versioned document, not
+  "the docs". No call is reported as verified on rank 5 alone.
+- Where documentation and the installed build disagreed, the report says which
+  versions were compared, which side was followed, and why — and no call site
+  branches across both.
+- The report carries the unverified list — symbol, package, version, reason the
+  check was skipped, and the observation that would close it — stated as empty
+  when it is empty.
+- Any needed behaviour that exists only in a newer release is written up as an
+  upgrade decision for the dependency's owner, and no version was bumped inside
+  this change to obtain it.
+
+Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+(MIT) is where the pairing comes from — check the dependency before calling it,
+and mark what went out unchecked. The ranks and the version rule are ours.

package/src/gdskills/bundled/skills/quality/changelog/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: changelog
-description: "Use when generating a changelog, release notes, or summarizing what changed between tags, versions, or date ranges."
+description: "Use when generating a changelog, release notes, or summarizing what changed between tags, versions, or date ranges. NOT for describing a single pull request or its linked issue (use `pr-issue-documenter`)."
 triggers:
-  - "/changelog"
-  - "Generate changelog"
+  - "generate changelog"
+  - "release notes"
+  - "what changed"
   - "What changed since"
-  - "Release notes"
   - "What's new"
 metadata:
   author: "MrCipherSmith"
@@ -82,3 +82,23 @@ If `gh` CLI available: fetch PR titles for merge commits, get authors and labels
 - If no conventional commits found, fall back to plain list by date
 - Breaking changes always go first
 - One line per change
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This commit has no `feat:`/`fix:` prefix, but it reads like a feature — I'll file it under Features" | Classification comes from the commit's own prefix. Guessing a section invents a release note nobody wrote. Unprefixed commits go to the plain dated fallback list |
+| "The subject is terse, so I'll describe what the change probably did" | You read the log, not the diff. A changelog entry that states an effect the commit never claimed is a false release note that ships to users |
+| "No tag matches the range, so I'll start from the first commit" | That silently turns "since last release" into the project's whole history. State the range you could not resolve and ask, rather than emitting a thousand-line changelog |
+| "The merge commit summarizes the branch nicely, keep it alongside the branch's commits" | It double-counts: the merge subject and the commits underneath describe the same work. Use the PR title, drop the merge |
+| "The type is `fix:` so it belongs in Bug Fixes, even though the body says BREAKING CHANGE" | `BREAKING CHANGE` outranks the type prefix. A breaking change filed under Bug Fixes is the entry a reader upgrades past without noticing |
+
+## Verification
+
+Do not report the changelog as done until all of the following hold:
+
+- The range actually used (tag-to-tag, tag-to-HEAD, or `--since` date) is stated in the output, including when it was a fallback
+- Every commit in `git log <range> --oneline` is either an entry or a deliberate skip (merge commit, exact duplicate) — none dropped silently
+- No section header is emitted with zero entries under it
+- Breaking Changes, when present, is the first section
+- With `--output` / `--prepend`: the target file exists, the pre-existing content is still intact, and the new block sits at the top rather than replacing it

package/src/gdskills/bundled/skills/quality/commit/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: commit
-description: "Use when committing code changes and a well-structured conventional commit message is needed, with optional amend or selective staging."
+description: "Use when committing code changes and a well-structured conventional commit message is needed, with optional amend or selective staging. NOT for publishing the branch to the remote (use `push`) or opening a pull request (use `pr`)."
 triggers:
-  - "/commit"
-  - "Commit changes"
+  - "commit changes"
+  - "git commit"
+  - "conventional commit"
   - "Commit this"
   - "Save changes"
 metadata:
@@ -64,3 +65,23 @@ Show the result: `git log --oneline -1` and `git status`
 - NEVER add Co-Authored-By lines
 - If pre-commit hook fails: fix the issue, re-stage, create a NEW commit (don't amend)
 - Follow existing commit message conventions in the repository
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Everything in the tree is my work, so staging it all is faster" | It is not all your work. A parallel agent, a running lane, or a half-finished edit of the user's rides along invisibly. Never stage by wildcard — list explicit pathspecs |
+| "The pre-commit hook failed on a file I didn't touch, `--no-verify` gets me past it" | The hook is the repository's gate, not an obstacle to route around. Fix the issue, re-stage, commit again |
+| "The last commit is mine and close enough — I'll amend it" | Amend only when the user explicitly asked. Amending a commit that is already pushed rewrites history someone else has fetched |
+| "The diff shows what happened, so `chore: updates` is enough" | The subject line is all a `git log` reader gets. Name the change and its scope in under 72 chars |
+| "The user is out of the loop on this untracked file, but it looks like mine" | Untracked files that look unrelated to recent work get a question, not a guess — that is how an `.env` or a scratch dump gets committed |
+
+## Verification
+
+Do not report the commit as done until all of the following hold:
+
+- `git log --oneline -1` shows the new commit, subject in `<type>(<scope>): <description>` form and under 72 chars
+- `git show --stat HEAD` lists exactly the intended files — no `.env`, credential, key, or large binary file
+- `git status` shows nothing else newly staged that you did not mean to include
+- `git show HEAD` carries no `Co-Authored-By` or generated-by trailer
+- Hooks ran — no `--no-verify` was passed; if a hook failed, a NEW commit exists rather than an amend

package/src/gdskills/bundled/skills/quality/db-migrate/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: db-migrate
-description: "Use when creating, applying, rolling back, or checking the status of database migrations."
+description: "Use when creating, applying, rolling back, or checking the status of database migrations. NOT for shipping the application release that carries the migration (use `deploy`)."
 triggers:
-  - "/db-migrate"
+  - "database migration"
+  - "db migrate"
+  - "migration status"
   - "Create migration"
   - "Run migrations"
-  - "Migration status"
   - "Rollback migration"
 metadata:
   author: "MrCipherSmith"
@@ -64,3 +65,23 @@ Search for: `prisma/schema.prisma`, `ormconfig.*`, `data-source.ts`, `knexfile.*
 - NEVER apply to production without explicit confirmation
 - For destructive operations (drop table, remove column), double-warn
 - If ORM can't be detected, ask the user
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The ORM autogenerated it, so the SQL must be correct" | Autogenerate routinely emits drop-and-recreate for a change that could have been an in-place alter. The generated file is a draft to read, not an answer to trust |
+| "It's only the dev database, no need to show the SQL first" | The same file is what runs against production later. The preview is the one moment the destructive statement can still be caught, and skipping it in dev means nobody ever read it |
+| "A rollback is unlikely, so an empty `down` is fine" | An empty `down` is worse than a missing one: the rollback reports success while changing nothing, and the schema silently stays ahead of the code |
+| "Two migration tools are configured; I'll use the one I know" | Each tool keeps its own history table. Picking the wrong one writes a migration the project's real tool will never see and cannot roll back. Ask which is authoritative |
+| "`prisma migrate dev` is the standard create command, just run it" | On a database with any drift it offers to reset — i.e. drop the data. Know what the create command does to an existing database before pointing it at one |
+
+## Verification
+
+Do not report the migration as done until all of the following hold:
+
+- The status command shows the intended migration in the intended state (applied, or pending for `create`), and no other migration changed state
+- The migration file carries both directions (up and down, or the ORM's equivalent) and the down path was read, not assumed
+- Any destructive statement (`DROP`, `ALTER … DROP`, `TRUNCATE`, a column removal) was shown to the user and confirmed in this conversation before it ran
+- The report names the detected tool, the migration name/id, and the environment the command ran against
+- For a production target: an explicit confirmation exists in this conversation, and the SQL preview preceded it

package/src/gdskills/bundled/skills/quality/dependency-update/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: dependency-update
-description: "Use when checking for outdated packages or upgrading dependencies with compatibility verification."
+description: "Use when checking for outdated packages or upgrading dependencies with compatibility verification. NOT for finding which packages are vulnerable in the first place (use `security-audit`)."
 triggers:
-  - "/dependency-update"
-  - "Update dependencies"
-  - "Upgrade packages"
+  - "update dependencies"
+  - "upgrade packages"
+  - "bump deps"
   - "Check outdated"
   - "Update npm packages"
 metadata:
@@ -79,3 +79,24 @@ npm run lint && npx tsc --noEmit && npm test && npm run build
 - Commit each group separately
 - Respect pinned versions
 - Check peer dependency warnings
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The suite passes with all of them installed, so batching the majors saved five rounds" | When it breaks you cannot tell which major did it, and bisecting a batch costs more than the rounds you saved. Majors go one at a time, tests after each (Step 4) |
+| "Tests broke after the major bump — I'll migrate the call sites while I'm here" | Two fix attempts, then rollback. An open-ended API migration is a separate task with its own review; smuggling it into a dependency bump hides it from everyone |
+| "This version is pinned, but the pin looks stale" | A pin is a decision someone made, usually about a break you cannot see from `npm outdated`. Report it as pinned and let the user unpin it |
+| "`npm outdated` printed nothing, so the project is up to date" | It prints nothing when the lockfile belongs to a different package manager. Detect from the lockfile (`bun.lock`, `pnpm-lock.yaml`, `yarn.lock`) before concluding "current" |
+| "Peer dependency warnings are warnings, not errors" | They are the standard cause of the runtime failure that shows up two commits later, in something that was never touched. Carry them into the report |
+| "One commit for the whole update is tidier than three" | It makes the one bad package unrevertable without dropping the good ones. Commit per risk group, as Step 4 specifies |
+
+## Exit Criteria
+
+Do not report the update as done until all of the following hold:
+
+- `npm run lint && npx tsc --noEmit && npm test && npm run build` — or the project's own equivalents — all pass on the final tree
+- Every major was applied and tested on its own, with its own commit; no major shares a commit with another
+- Every package the plan proposed is accounted for in the report as updated, skipped (with the reason), or rolled back
+- `git status` is clean and the lockfile is committed alongside the manifest it belongs to
+- Pinned versions are unchanged, and peer dependency warnings that appeared are listed in the report

package/src/gdskills/bundled/skills/quality/deploy/SKILL.md

@@ -1,8 +1,11 @@
 ---
 name: deploy
-description: "Use when deploying to any environment (staging, production) or when a deployment pipeline needs to run."
+description: "Use when deploying to any environment (staging, production) or when a deployment pipeline needs to run. NOT for the database schema changes a release depends on (use `db-migrate`)."
 triggers:
-  - "/deploy"
+  - "deploy"
+  - "deployment"
+  - "ship"
+  - "release"
   - "Deploy to"
   - "Push to production"
   - "Deploy staging"
@@ -41,7 +44,7 @@ Run in parallel where possible:
 2. **Branch check**: correct branch for target env (production → main/master)
 3. **Tests**: `npm test` / `pytest` / `go test ./...` (skip with `--skip-tests`)
 4. **Lint**: `npm run lint` if available
-5. **Type-check**: `npx tsc --noEmit` if TypeScript
+5. **Type-check**: `keryx health run --source typescript` if TypeScript (`src/health/sources/typescript.ts` resolves the real invocation, never a hardcoded `npx tsc`; on a project with no keryx health config, fall back to its own configured type-check command)
 6. **Build**: `npm run build` / `docker build`
 
 If any check fails → stop and report.
@@ -68,3 +71,23 @@ If any check fails → stop and report.
 - NEVER deploy from dirty working tree without warning
 - Show summary before deploying: branch, env, target, version
 - If deploy target can't be detected, ask the user
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "That test is flaky, `--skip-tests` just this once" | `--skip-tests` is a flag the user passes, never one you add. Report the failing test and let them decide whether it is flaky — from inside the run you cannot tell flaky from newly broken |
+| "The tree is dirty, but only with files unrelated to the deploy" | A deploy from a dirty tree ships an artifact that matches no commit, so it cannot be reproduced, diffed, or rolled back to a known state. Warn, and get an answer before proceeding |
+| "The user said 'ship it', so production is confirmed" | Production takes a confirmation that names production. "Ship it" is how a staging deploy gets requested at least as often |
+| "The deploy command exited 0 — done" | Exit 0 means the command ran, not that the process came up. Health-check the endpoint and read the startup logs before reporting success (Phase 4) |
+| "I can't tell the target for certain, but `vercel.json` is here so Vercel is a fair bet" | A guessed deploy target deploys to a real environment. When detection is ambiguous, ask — the cost of the question is one message, the cost of the guess is an unplanned release |
+
+## Exit Criteria
+
+Do not report the deploy as done until all of the following hold:
+
+- Every Phase 2 pre-flight check either passed or was skipped by a flag the user passed — none skipped on your own judgment
+- For a production target: an explicit confirmation naming production exists in this conversation, and the summary (branch, env, target, version) preceded it
+- The health endpoint responded successfully after the deploy, and the startup logs show no errors
+- The report states the environment, the detected target, the deployed version/commit, and the result of the health check
+- For `--dry-run`: nothing was executed — the report shows only what would have run