@mrciphersmith/keryx 0.2.97 → 0.2.99

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

@@ -1,16 +1,16 @@
 ---
 name: pr
-description: "Use when opening a pull request for the current branch."
+description: "Use when opening a pull request for the current branch. NOT for rewriting the body of a pull request that already exists or its linked issue (use `pr-issue-documenter`)."
 triggers:
-  - "/pr"
-  - "Create PR"
+  - "open PR"
+  - "create pull request"
+  - "draft PR"
   - "Open pull request"
-  - "Create pull request"
   - "Make PR"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "workflow"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -73,3 +73,23 @@ Return the PR URL to the user.
 - Always analyze ALL commits, not just the last one
 - If the branch has linked GitHub issues, reference them in the body
 - Ask user for confirmation before creating if there are 10+ commits
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The last commit message already summarizes the work, use it as the body" | A PR is the whole branch, not its tip. Read `main...HEAD`; the earliest commits are usually where the design decision a reviewer needs actually happened |
+| "The branch isn't pushed, but `gh pr create` will sort that out" | It either fails or opens a PR against a stale remote head, so the diff a reviewer sees is not the diff you analyzed. Push with `-u origin <branch>` first |
+| "The tree is dirty, but the commits are what get reviewed anyway" | Exactly — which means the uncommitted half of the change quietly does not exist in the PR, and the reviewer approves something incomplete. Ask before opening over a dirty tree |
+| "There's an open issue that sounds like this work, I'll write `Closes #N`" | `Closes` shuts an issue on merge. Reference only issues the branch or its commits actually link to; a guess closes someone else's ticket |
+| "The user asked for a PR, so 40 commits is still just 'create the PR'" | 10+ commits gets a confirmation first. A branch that large is usually two PRs, and saying so is cheaper before the PR exists than after review starts |
+
+## Verification
+
+Do not report the PR as done until all of the following hold:
+
+- `gh pr view --json url,title,body` returns the created PR, with a non-empty body carrying Summary, Changes and Test plan
+- The title is under 70 chars and describes the branch, not the last commit
+- Every commit in `git log <base>..HEAD` is represented somewhere in the body — no area of the diff goes unmentioned
+- The branch has an upstream and the remote head equals local `HEAD`
+- The PR URL is returned to the user

package/src/gdskills/bundled/skills/quality/pr-issue-documenter/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: pr-issue-documenter
-description: "Use when documenting PR changes, adding a PR description, creating a linked issue for a PR, or updating an existing issue body."
+description: "Use when documenting PR changes, adding a PR description, creating a linked issue for a PR, or updating an existing issue body. NOT for opening the pull request in the first place (use `pr`)."
 triggers:
+  - "document PR"
+  - "PR description"
+  - "create issue for PR"
   - "Add PR description"
   - "Document PR changes"
   - "Describe what was done in PR"
-  - "Create issue for PR"
   - "Update PR and issue"
   - "Add description to PR"
   - "Write PR summary"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "documentation"
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  category: "quality"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -363,6 +365,27 @@ Always present contradictions to user before making changes.
 9. **DO NOT** modify PR title unless explicitly asked
 10. **DO NOT** write comments on GitHub PRs/issues (only edit body)
 
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The existing issue body is stale and mine is better — replace it" | That body is someone's written record, and the parts you think are stale may be the parts they argued for. Present the contradictions, offer the three choices in Step 5.1, apply what the user picks |
+| "The diff is huge; the commit messages describe it well enough" | Commit subjects and the diff disagree constantly — a rename half-finished, a "refactor" that changed behavior. Never write a change you have not seen in `gh pr diff` |
+| "No issue is linked and this clearly deserves one, so I'll create it" | Issue creation needs the user's confirmation every time (Rule 8). An unasked-for issue is noise someone else has to triage and close |
+| "The PR title is wrong too — fixing it while I'm in here is a favour" | Title changes are out of scope unless asked (Rule 9). The author chose it, and a silent retitle is invisible in the notification a reviewer gets |
+| "Leaving a comment is less destructive than editing the body" | This skill edits bodies and never comments (Rule 10). A comment is a notification to every subscriber and does not update the description anyone reads first |
+| "The diff has a hardcoded value, but that's the author's business" | Temporary and hardcoded values get marked for follow-up in the description — that is where the next reader looks, and where it otherwise disappears |
+
+## Verification
+
+Do not report done until all of the following hold:
+
+- `gh pr view {number} --json body` returns the new body, with Summary, Changes and Key Files present, plus `Closes #N` when an issue is linked
+- Every statement in the body maps to something visible in `gh pr diff {number}` — nothing invented, nothing carried over from a stale description
+- If an issue was created or updated, `gh issue view {number} --json body` shows it; if it is a sub-issue, the parent issue body now contains its link
+- Every contradiction found in Step 5.1 was presented to the user and resolved by their choice — none resolved silently
+- The final report lists every PR and issue URL touched, as in Step 7
+
 ## Job Context Awareness
 
 If called within an orchestrator job context, check for job context before starting:

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

@@ -1,15 +1,16 @@
 ---
 name: push
-description: "Use when pushing the current branch to the remote, especially when upstream tracking or safety checks are needed."
+description: "Use when pushing the current branch to the remote, especially when upstream tracking or safety checks are needed. NOT for creating the commits themselves (use `commit`) or opening a pull request afterwards (use `pr`)."
 triggers:
-  - "/push"
+  - "push branch"
+  - "git push"
+  - "publish branch"
   - "Push changes"
   - "Push to remote"
-  - "Push branch"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "workflow"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -50,3 +51,23 @@ Show result: confirm push success with commit count.
 - NEVER force push to main/master without double confirmation
 - NEVER use `--no-verify`
 - If push is rejected (non-fast-forward), suggest `git pull --rebase` first
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "It was rejected, but `--force-with-lease` is safe enough here" | The lease only compares against the ref you last fetched. A teammate's push that landed since then is still discarded, silently. Rebase and push normally, or ask |
+| "It's my own feature branch, so a force push hurts nobody" | Open PRs, CI runs, review threads and other worktrees read that ref. Rewriting it invalidates all of them. Force only when the user says "force push" in this conversation |
+| "There are uncommitted changes, but they're unrelated to what I'm pushing" | The push ships what is committed, so unrelated work silently stays behind while the branch looks complete to a reviewer. Warn and ask before pushing over a dirty tree |
+| "No upstream is set, so `git push origin HEAD` will do" | That leaves the branch untracked, and every later `git status` / `git push` has to guess. Use `git push -u origin <branch>` so the tracking is recorded once |
+| "The pre-push hook is slow and this is a tiny change" | `--no-verify` is never the answer here — a tiny change is exactly what an unrun hook lets through |
+
+## Verification
+
+Do not report the push as done until all of the following hold:
+
+- `git status` reports the branch up to date with its upstream
+- `git branch -vv` shows an upstream for the current branch (set with `-u` if it had none)
+- `git log @{upstream}..HEAD --oneline` is empty — nothing left unpushed
+- The report states the commit count pushed and the remote/branch they landed on
+- `--force` was used only if the user asked for it in this conversation, and never against main/master without double confirmation

package/src/gdskills/bundled/skills/quality/root-cause/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: root-cause
+model_tier: deep
+description: |
+  Use when a defect exists and nobody can yet say what produces it — a crash, a
+  wrong result, a failure a user hits and the suite never sees. The order is
+  fixed: reproduce it and write down how, localize before editing anything,
+  reduce to the smallest failing case, repair the mechanism rather than the
+  symptom, and leave behind a guard that was WATCHED failing without the repair.
+  Covers the case the defect refuses to appear: which evidence is admissible,
+  when to stop looking, and what to report in place of a fix.
+  NOT for: a defect already pinned to a line and a mechanism, where nothing
+  remains but writing the patch and its guard.
+triggers:
+  - "root cause"
+  - "why does this fail"
+  - "cannot reproduce"
+  - "track down the bug"
+  - "debugging"
+  - "bisect"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "quality"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# Root Cause
+
+A defect exists and nobody knows why. Your job is **not** to make the symptom
+stop. It is to name the mechanism that produces it, change that, and leave
+something behind that fails if it ever comes back.
+
+The five steps below are an order, not a menu. Every one of them is skipped by
+agents in the same way — forward, into the edit — and each skip costs the step
+after it.
+
+## 1. Reproduce, and write the reproduction down
+
+Before any code is read: the exact command, the input, the environment, what you
+expected, what happened, and **how often** — `10/10` and `3/10` are different
+defects with different causes.
+
+A fix produced without a reproduction is a guess with a diff attached. It cannot
+be verified, because there is nothing that was failing to stop failing.
+
+If the reproduction needs setup (a seeded row, a cleared cache, a second
+process), that setup is part of it. Write it as commands someone else can run.
+
+## 2. Localize before you edit
+
+Reading a file top to bottom is not localization; it is hoping. Localization is
+a **search that halves**:
+
+- over history — `git bisect` between a known-good and known-bad revision;
+- over the call path — `keryx gdgraph affected <file>` for what reaches the
+  site, then a probe at the midpoint of the path;
+- over the input — cut the payload in half, keep the failing half;
+- over the environment — one variable, one flag, one version at a time.
+
+Two rules hold for the whole step. **Change one thing and record what happened.**
+And **an edit made "to see what happens" is not a fix** — it either goes away or
+it gets named in the diff as instrumentation.
+
+Long output (a bisect run, a failing suite, a log) goes through
+`keryx ctx run -- <cmd>` rather than into the reading window whole.
+
+## 3. Reduce to the smallest failing case
+
+Delete everything that can be deleted while it still fails. Each removal that
+keeps the failure is evidence about what does **not** matter, and the residue is
+usually the cause stated in the shortest possible form.
+
+A reduced case is also the guard from step 5, already written.
+
+## 4. Name the cause, then repair it
+
+Say it in one sentence carrying a **mechanism**, not a location: "the cache key
+omits the tenant id, so the second tenant reads the first tenant's row". "It is
+in `store.ts`" is a location. "It is a race" is a category. Neither is a cause.
+
+Then check the repair against that sentence:
+
+| The repair | What it actually is |
+|---|---|
+| A guard that returns early when the value is missing | The missing value is the defect; you hid the only thing reporting it |
+| A retry, a longer timeout, a `sleep` | The mechanism is untouched and now it is slower and intermittent |
+| A widened type, a cast, an `any` | The compiler was right; the wrong value is still produced |
+| A changed assertion or an expectation loosened to match | The test was the last thing telling the truth here |
+
+Every row above makes the symptom go away. None of them is this skill's output.
+
+## 5. Leave a guard that was seen failing
+
+A test written after a fix and never observed red proves the test runs. It does
+not prove it catches anything.
+
+So: run the new test against the **unfixed** code and watch it fail. If the fix
+is already applied, undo it in place (never `git stash` — a scoped stash takes
+other people's uncommitted work with it), watch the test fail, restore the fix,
+watch it pass. Record both observations.
+
+If the defect cannot be reached from a test — it needs a device, a customer's
+data, real concurrency — say so, and say what the guard would be instead: an
+assertion, a counter, a log line at the decision point.
+
+---
+
+## When it does not reproduce
+
+This is the case handled worst, and it is handled worst in one specific way: the
+search for the defect quietly becomes a search for *something wrong*, and a
+plausible-looking repair is shipped for a failure nobody ever saw.
+
+### What is admissible
+
+In descending strength:
+
+1. **A failure you produced yourself.** Nothing else is in this class.
+2. **An artifact of the original failure** — a stack trace, a log line with a
+   timestamp, a CI run id, an error string quoted by the reporter, a dump.
+3. **A path you can show reaches the reported state**, with the input that
+   drives it *named and shown to exist*.
+4. **A measured environment delta** — a version, a locale, a timezone, a clock
+   skew, an ordering, a concurrency level you actually varied and observed.
+
+Not admissible, at any strength: this looks wrong; this pattern is usually a
+bug; this is the kind of thing that causes that; two readings of the same file
+agreeing. Reading harder produces no new evidence — the file says the same thing
+the third time.
+
+### Widen the attempt before you give up
+
+One axis at a time, each attempt and its result recorded: input, environment and
+versions, ordering and concurrency, persisted state (cache, DB, temp files),
+clock and timezone, isolation (the single test vs the whole suite), random seed.
+
+For anything intermittent, a count replaces a verdict. Run it 50 times and
+report `1/50`. "It passed when I re-ran it" is not a result.
+
+### When to stop
+
+Stop when any of these is true, and stop deliberately rather than by drifting
+into a fix:
+
+- the next axis is one you cannot control — production data, a customer's
+  machine, hardware you do not have;
+- the budget the task set for reproduction is spent;
+- going further requires changing the code under investigation to see anything
+  at all. That is instrumentation, and landing it is a separate decision the
+  requester gets to make.
+
+### Report instead of a fix
+
+Not reproducing is a result, and it is reportable. What it is not is permission
+to ship a change. The report carries:
+
+- every reproduction attempt, one line each, with what happened;
+- the strongest evidence held, labelled with its class from the list above;
+- the hypotheses that survive that evidence — two or three, each with **the
+  observation that would kill it**;
+- the instrumentation that would settle it, and where it goes;
+- what was left unchanged.
+
+Landing instrumentation alone and stopping is legitimate work. Landing a
+speculative repair and closing the issue is not: if no experiment can tell your
+change from a no-op, nothing was fixed, and the next person's bisect now
+straddles a commit that did nothing.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "It never reproduced, but I found something that looks wrong — I will fix that." | A smell you found and a defect you never saw are different objects. Repairing the smell closes the ticket with the reported failure still live, and the next report now arrives against code you changed for unrelated reasons. |
+| "It passed when I ran it again, so it is flaky / it is gone." | A single pass is not evidence of absence for a failure that was observed. Run it 50 times and report the rate; `1/50` is a finding, "it passed" is a sentence about one run. |
+| "The stack trace names this line, so this line is the cause." | The trace names where the bad value surfaced, not where it was produced. The throwing frame is usually innocent; walk back to where the value was created and prove it was already wrong there. |
+| "A null check here makes the crash go away." | The crash was the only thing reporting that the value was missing. A guard moves the failure somewhere later, quieter, and further from its cause — and the next report will not mention this file. |
+| "I fixed it and the test I added passes." | A guard never watched failing proves the test executes. Run it against the unfixed code first; if it passes there, it is testing something other than the defect. |
+| "I changed three things and now it works." | You have a working tree and no cause. One of the three was the fix and two are unexplained edits nobody can review. Revert to one change at a time, or the repair is folklore. |
+| "It only breaks in CI, so it is an infrastructure problem." | "Only in CI" is an environment difference you have not named yet — ordering, concurrency, a clock, a locale, a missing file, a cold cache. Name the difference before assigning the defect to somebody else. |
+| "It is obviously a race condition." | "Race" is a category, not a cause. Which two operations, over which piece of state, in which interleaving? Without those three, the word ends the investigation instead of advancing it. |
+| "The reproduction takes too long to write down; I have it in my head." | The reproduction is the artifact the fix is verified against. Unwritten, it cannot be re-run after the change, and "it works now" becomes unfalsifiable. |
+
+## Verification
+
+Report the defect fixed only when all of these hold:
+
+- The reproduction is written down as commands plus expected/observed, and it
+  failed before the change.
+- The cause is one sentence naming a mechanism, not a file and not a category.
+- The change alters that mechanism. No symptom was suppressed by a guard, a
+  retry, a widened type, or a loosened assertion.
+- A guard exists and was **watched failing** against the unfixed code; the
+  report says where that was observed.
+- Everything added to investigate — logging, timeouts, skipped tests, scratch
+  edits — is either removed or deliberately kept and named in the diff.
+- If it never reproduced, no fix is claimed: the report carries the attempts,
+  the evidence and its class, the surviving hypotheses with their killing
+  observations, and the instrumentation that would settle it.
+
+Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+(MIT) is why this set carries a debugging skill at all; the step order, the
+evidence classes and the non-reproduction protocol were written here, not taken.

package/src/gdskills/bundled/skills/quality/security-audit/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: security-audit
-description: "Use when checking for dependency vulnerabilities, accidentally committed secrets, or security issues in Docker images."
+description: "Use when checking for dependency vulnerabilities, accidentally committed secrets, or security issues in Docker images. NOT for Metaproject security policy — prompt-injection, redaction and memory/wiki/report writes belong to `metaproject-security` — and NOT for performing the upgrades a finding calls for (use `dependency-update`)."
 triggers:
-  - "Security audit"
-  - "Check vulnerabilities"
-  - "Audit dependencies"
+  - "security audit"
+  - "audit dependencies"
+  - "scan secrets"
   - "Security scan"
   - "Check for CVEs"
   - "npm audit"
@@ -106,3 +106,24 @@ Otherwise report `container-scan: NOT RUN — <no Dockerfile | docker unavailabl
   selected, could not run, or returned no vulnerability data. Report `not
   measured` and name the reason. In a security report, silence read as "clean"
   is the most expensive defect available.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The advisory is informational / low severity — ship it" | This skill reports severity, it does not filter it. Accepting a known CVE is the caller's decision to make explicitly, not one you make for them by omission |
+| "`npm audit` returned JSON with no vulnerabilities in it, so the project is clean" | Check for the `vulnerabilities` / `advisories` key before grouping. `ENOLOCK` is ~240 bytes of error that groups to zero in every severity — indistinguishable from clean, and that is the whole point of Step 1 |
+| "No lockfile row matched, but `npm audit` is the usual one" | Falling through to another package manager's audit is a guess dressed as a result. The outcome is `dependency-audit: NOT RUN — no recognised lockfile`, with no totals attached |
+| "There's no Dockerfile, so container scan: 0 issues" | "No Dockerfile" and "scanned, found nothing" are different results and only one of them is evidence. Report `container-scan: NOT RUN — no Dockerfile` |
+| "`npm audit fix --force` clears the whole list" | `--force` installs semver-major upgrades across the tree. Never recommend it without stating which packages it would move and by how much |
+| "That key looks like a test fixture, not a real secret" | A committed credential gets reported with its path and rotated first; whether it was live is decided afterwards, by someone who can check. Never print its value in the report |
+
+## Verification
+
+Do not report the audit as done until all of the following hold:
+
+- Every step carries `RAN` or `NOT RUN — <reason>`, and no step marked NOT RUN carries a numeric total
+- Severity totals appear only for steps that ran; everywhere else the report reads `not measured`, never `0`
+- Every critical/high entry names a CVE or advisory id, the package, and the version range that pulls it in
+- No raw secret value appears anywhere in the report — only path, line, and a redacted preview
+- The report names the package manager and lockfile detected in Step 1, so a reader can tell which tree was audited

package/src/gdskills/bundled/skills/quality/test-gen/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: test-gen
-description: "Use when unit or integration tests need to be written for a specific file or module."
+description: "Use when unit or integration tests need to be written for a specific file or module that already exists. NOT for writing failing test stubs ahead of the implementation (use `tests-creator`)."
 triggers:
-  - "/test-gen"
-  - "Generate tests"
+  - "generate tests"
+  - "write tests"
+  - "add coverage"
   - "Write tests for"
   - "Add tests"
   - "Create test file"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "testing"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -56,8 +57,13 @@ Auto-generate tests for specified files or modules.
 
 ### Step 5: Verify
 ```bash
-npx jest <test-file> --no-coverage
+keryx test run --changed --strict
 ```
+`src/testing/service.ts` detects the project's own test runner from its
+lockfile/scripts and builds the invocation — do not hard-code a test runner
+or binary here. On a project with no keryx testing config, run the project's
+own configured test command instead (discovered, not hardcoded).
+
 Fix failing tests (max 3 iterations) — fix the test, not the source.
 
 ### Step 6: Report
@@ -73,3 +79,23 @@ Fix failing tests (max 3 iterations) — fix the test, not the source.
 - Mock external dependencies, not internal modules
 - Meaningful test descriptions
 - If no test framework detected, suggest installing one
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The test fails because the source has a bug — I'll fix the source" | This skill writes test files only. A source change buried inside a test-generation run is an unreviewed fix, and it also hides the bug the new test just found. Report the failure instead |
+| "Still failing on iteration four; I'll loosen the assertion until it's green" | A test that asserts nothing covers nothing while reporting coverage — strictly worse than no test. After 3 iterations, stop and report the failing case |
+| "No test framework here, so I'll install vitest and a config" | Choosing a test framework is a project decision with config, CI and convention consequences. Suggest one; do not add it |
+| "Mocking the neighbouring module is easier than building its input" | Mock external dependencies, not internal ones. A test whose collaborators are all mocked asserts that your mocks agree with each other |
+| "One test that exercises the whole file covers more per line written" | It reports one failure for any of a dozen causes, so nobody can tell what broke. One behaviour per test, and let the description name it |
+
+## Verification
+
+Do not report generation as done until all of the following hold:
+
+- The test file sits at the project's own convention path, with the import style, describe/it structure and assertion style of the neighbouring tests read in Step 2
+- `keryx test run --changed --strict` — or, with no keryx testing config, the project's own discovered test command — exits 0 with every generated test passing
+- `git status` shows only test files added or modified; no source file changed
+- Every exported function, component, endpoint or class identified in Step 1 has at least one test, or the report says why it does not
+- The Step 6 report states the file path and the test-case count, and that count matches what the runner reported

package/src/gdskills/bundled/skills/quality/tests-creator/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: tests-creator
-description: "Use when writing test cases BEFORE implementation — converts acceptance criteria into failing test stubs that task-implementer will make pass. Mandatory step in the TDD pipeline between issue-analyzer and task-implementer."
+description: "Use when writing test cases BEFORE implementation — converts acceptance criteria into failing test stubs that task-implementer will make pass. Mandatory step in the TDD pipeline between issue-analyzer and task-implementer. NOT for adding tests to code that already exists (use `test-gen`)."
 triggers:
-  - "Create tests"
+  - "create tests first"
+  - "test scenarios"
+  - "tdd"
   - "Write tests first"
   - "Generate test specs"
   - "Tests before implementation"
@@ -11,9 +13,9 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "testing"
+  category: "quality"
   agent_worthy: true
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -63,17 +65,23 @@ Identify the test framework and conventions used in the project.
 **1.1 Detect framework:**
 
 ```bash
-# Check package.json for test dependencies
-cat <codebase_path>/package.json | grep -E '"(jest|vitest|mocha|jasmine|bun:test|pytest|go test)"'
+keryx test analyze
+```
 
-# Check for config files
-ls <codebase_path>/{vitest.config.*,jest.config.*,pytest.ini,setup.cfg}
+Discovers the framework, test scripts, config files, and existing test file
+paths in one pass — do NOT `cat`/`grep` `package.json`, `ls` config globs, or
+`find` for test files; that is exactly what `keryx test analyze` already
+walks the project for. Read the result compactly:
 
-# Check existing test files for imports
-find <codebase_path>/src -name "*.test.*" -o -name "*.spec.*" | head -5
+```bash
+keryx ctx read .metaproject/data/testing/context.md
 ```
 
-**1.2 Read 2-3 existing test files** to understand:
+On a project with no keryx testing config, fall back to the project's own
+configured way of finding its test framework and existing tests (discovered,
+not a hardcoded `cat`/`ls`/`find` invocation).
+
+**1.2 Read 2-3 existing test files** (from the `context.md` test file list) to understand:
 - Import style (`import { describe, it, expect } from 'vitest'` vs global)
 - Test file location (co-located `*.test.ts` vs `__tests__/` directory)
 - Describe/it/test nesting patterns
@@ -324,6 +332,19 @@ This ensures the TDD cycle is maintained end-to-end.
 
 ---
 
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The module doesn't exist, so the import breaks the whole suite — I'll create a stub module first" | That stub is implementation code, and it is exactly what Rule 1 forbids. A failing import IS the RED phase; `task-implementer` creates the module |
+| "A placeholder like `expect(true).toBe(true)` gets the file committed and the pipeline moving" | A test that passes before implementation proves nothing and goes green forever after. RED means failing (Rule 2) — use `it.todo`, or the forward-declared assertion from 3.3 |
+| "I know how this will be built, so I'll assert it calls the repository method" | That tests HOW, not WHAT (Rule 3), and it fails the moment the implementer picks a different — valid — structure. Assert observable behaviour |
+| "This acceptance criterion is too vague to test, so I'll skip it" | Every criterion needs at least one test (Rule 4). Derive from the task description, log the warning, and say in `notes` what you assumed — an untested criterion silently leaves the pipeline |
+| "`verify_red` shows the test passing already; close enough, report DONE" | A test green before implementation is a wrong test, not an early win. Fix the assertion, or report it as a concern — do not pass it downstream as covered |
+| "I'll leave the stubs uncommitted and let `task-implementer` commit everything together" | The handoff assumes committed RED files (Rule 6): the implementer's first step is to run them and confirm they fail. Uncommitted stubs make that step unverifiable |
+
+---
+
 ## Job Context Awareness
 
 When dispatched by `job-orchestrator`:

package/src/gdskills/bundled/skills/review/code-ai-review/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: code-ai-review
-description: "Performs strict AI code review following code-review-ai-assistant.mdc standards. Reviews current branch changes from merge-base by default, including both committed and local uncommitted changes. Use when: code review requested, checking branch changes, reviewing implementation quality."
+description: "Use when the legacy strict AI review profile (code-review-ai-assistant.mdc) is asked for by name — reviews the current branch from its merge-base, committed and uncommitted changes together. NOT for: a code review request that names no profile (review-orchestrator)."
 triggers:
-  - "Code review"
-  - "Review my changes"
-  - "Check this code"
-  - "Review code"
+  - "code-ai-review"
+  - "AI review baseline"
+  - "strict AI review"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "review"
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -56,7 +55,7 @@ This skill does NOT duplicate:
 
 ## Scope Detection
 
-See shared script: `skills/shared/git-merge-base.md`
+See shared script: `.metaproject/skills/gdskills/shared/git-merge-base.md`
 
 Run the script from that file to determine MERGE_BASE and SCOPE before proceeding with the review.
 
@@ -201,3 +200,39 @@ If provided and the file exists, read the context document before starting the r
 - Reference context when justifying suggestions
 
 If the file does not exist or is not provided, proceed normally — context is optional and non-blocking.
+
+---
+
+## Red Flags
+
+This profile is a thin wrapper around `code-review-ai-assistant.mdc`, and it
+predates everything the review domain standardised afterwards. The rows below are
+the ways that gap makes it misfire.
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "A review was requested, so I will run this profile." | It is a legacy opt-in profile, reached by name or through `review --legacy-profiles`. An unqualified review request belongs to `review-orchestrator`; running this one instead silently drops every specialised lane along with the finding schema. |
+| "The output template has a Severity field, so my report is a review result." | It is not. This profile predates `reviewer-finding.schema.json`: it emits free prose with no machine-readable finding and no class enumeration, so nothing downstream can screen, verify or deduplicate it. Hand the report to a person, never to `keryx review ingest`. |
+| "Half these instructions are in Russian, so the report should be in Russian." | The mixed language is an artefact of when this file was written, not an instruction about the report. Write the report in the language the requester used. |
+| "I noticed a store problem and a naming problem, so I will include them here." | The Scope Boundaries table above routes those to `code-mobx-store-review` and `code-style-review`. A finding filed under the wrong profile is a finding the requester did not ask this profile for, and it arrives without the checks that lane would have applied. |
+| "One entry per occurrence is more thorough." | It is longer, not more thorough. Where one shape repeats, report it once and list every site — ten entries that are one problem hide the other nine. |
+| "I cannot reach the code path, but the pattern is usually wrong." | Then it is an observation, not a finding. Say what input, call or condition would reach it, and let the reader decide. |
+
+---
+
+## Verification
+
+Report done only once all of these hold:
+
+- The requester asked for this profile by name, or through
+  `review --legacy-profiles`. If they asked for "a review", stop and hand the
+  request to `review-orchestrator` instead.
+- The scope block carries the real branch, parent ref, merge-base and scope mode —
+  not the template placeholders.
+- Every finding carries Severity, Location (path plus the lines from the diff),
+  Problem, Why it matters and a concrete Suggested fix; a patch where the fix is
+  a line or two.
+- Every finding is anchored to a line the branch slice actually changed. Nothing
+  outside `merge-base..worktree` is discussed.
+- The report is free prose by design, so it is delivered to a person and is not
+  fed into the managed-review pipeline.