@mrciphersmith/keryx 0.2.73 → 0.2.75

package/src/gdskills/bundled/skills/review/review-pr-feedback/input-contract.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://keryx.local/schemas/review-pr-feedback/input-contract.schema.json",
+  "title": "ReviewPrFeedbackInput",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "pr_url"
+  ],
+  "properties": {
+    "pr_url": {
+      "type": "string",
+      "minLength": 1,
+      "description": "GitHub PR URL (https://github.com/owner/repo/pull/123), owner/repo#123, or #123 when the git remote resolves the repository."
+    },
+    "fix": {
+      "type": "boolean",
+      "default": false,
+      "description": "Run the execution steps: dispatch flow-orchestrator with the fix plan, merge into the reviewed PR's head branch, and answer every comment. Never inferred \u2014 absent this flag the skill produces a plan and stops."
+    },
+    "context_doc": {
+      "type": "string",
+      "description": "Path to a job context document, e.g. <JOBS_ROOT>/<job>/ai/context.md. Optional and non-blocking."
+    },
+    "comment_ids": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Restrict the run to these collected comment ids. Every excluded comment is still listed, with that as its reason \u2014 a filter that removes silently reads as nobody having commented."
+    },
+    "max_fix_rounds": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Ceiling on review/fix rounds, passed to flow-orchestrator as a constraint. It can only lower that skill's own attempt budget, never raise it."
+    },
+    "operator_confirmed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "confirmed_by",
+        "confirmed_at",
+        "plan_digest"
+      ],
+      "description": "REQUIRED whenever `fix` is true and this skill is running under dispatch. A subagent has no user to answer the Step 9 confirmation, and --fix merges third-party review comments into somebody's pull request: without this the run is BLOCKED, never defaulted. What `plan_digest` is worth is stated on the field itself; do not infer a replay defence from its presence here.",
+      "properties": {
+        "confirmed_by": {
+          "type": "string",
+          "minLength": 1
+        },
+        "confirmed_at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "plan_digest": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A record of WHICH plan the human said they read \u2014 not a control. Nothing in this tree computes or verifies a digest, and the schema constrains it only to a non-empty string, so an agent composing the dispatch chooses the value and a plan mutated after approval carries the same one. `operator_confirmed`'s PRESENCE is enforced; this field's VALUE is not. Making it a control means hashing the rendered plan and having the receiver recompute over what it got."
+        }
+      }
+    }
+  },
+  "if": {
+    "required": [
+      "fix"
+    ],
+    "properties": {
+      "fix": {
+        "const": true
+      }
+    }
+  },
+  "then": {
+    "required": [
+      "operator_confirmed"
+    ]
+  }
+}

package/src/gdskills/bundled/skills/review/review-pr-feedback/output-contract.schema.json

@@ -0,0 +1,375 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://keryx.local/schemas/review-pr-feedback/output-contract.schema.json",
+  "title": "ReviewPrFeedbackOutput",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "mode",
+    "pr",
+    "head_sha",
+    "collected",
+    "verdicts",
+    "plan_items",
+    "summary",
+    "screen_status",
+    "screened",
+    "excluded_for_injection",
+    "filtered"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": [
+        "DONE",
+        "DONE_WITH_CONCERNS",
+        "NEEDS_CONTEXT",
+        "BLOCKED"
+      ]
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "analyze",
+        "fix"
+      ]
+    },
+    "pr": {
+      "type": "string",
+      "description": "<owner>/<repo>#<n>"
+    },
+    "head_sha": {
+      "type": "string",
+      "description": "The commit the collection and every verdict are true of. A run that cannot name it is stale, never fresh."
+    },
+    "collected": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "filtered": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "comment",
+          "reason"
+        ],
+        "properties": {
+          "comment": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "Everything the collection or comment_ids removed, with the reason. Never empty by omission."
+    },
+    "verdicts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "valid": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "valid-wider": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "already-fixed": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "not-reproducible": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "disagree": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "out-of-scope": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "needs-clarification": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unverified": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "plan_items": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "fix": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "description": "Present in fix mode only. Null in analyze mode: no branch, no PR, no merge, no reply.",
+      "required": [
+        "flow_id",
+        "flow_status",
+        "merged_into",
+        "operator_confirmed"
+      ],
+      "properties": {
+        "flow_id": {
+          "type": "string"
+        },
+        "flow_status": {
+          "type": "string",
+          "enum": [
+            "initialized",
+            "in_progress",
+            "implemented",
+            "done",
+            "blocked",
+            "failed"
+          ]
+        },
+        "fix_pr_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "merged_into": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The reviewed PR's head branch. Any other value is a fix that did not land inside the pull request it answers."
+        },
+        "merge_sha": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The merge commit. Its presence is what makes the round's exit condition enforceable: a recorded merge REQUIRES remaining_findings.blocker/major/minor to be 0. The threshold was prose in two skills and nothing refused an output that merged over three blockers."
+        },
+        "review_rounds": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "remaining_findings": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "blocker": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "major": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "minor": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "info": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "description": "A merge requires blocker, major and minor to be zero. info does not hold the loop."
+        },
+        "operator_confirmed": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "confirmed_by",
+            "confirmed_at",
+            "plan_digest"
+          ],
+          "description": "Who authorised the merge and the replies, and against which plan. REQUIRED in fix mode and NOT nullable: the field exists to separate an approved run from an assumed one, and both an omitted field and a null one are the assumed run wearing the approved one's shape. An interactive run records the operator it asked; there is no merge without somebody behind it.",
+          "properties": {
+            "confirmed_by": {
+              "type": "string",
+              "minLength": 1
+            },
+            "confirmed_at": {
+              "type": "string",
+              "minLength": 1
+            },
+            "plan_digest": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      },
+      "if": {
+        "required": [
+          "merge_sha"
+        ],
+        "properties": {
+          "merge_sha": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "remaining_findings": {
+            "required": [
+              "blocker",
+              "major",
+              "minor"
+            ],
+            "properties": {
+              "blocker": {
+                "const": 0
+              },
+              "major": {
+                "const": 0
+              },
+              "minor": {
+                "const": 0
+              }
+            }
+          }
+        }
+      }
+    },
+    "replies": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "description": "Present in fix mode only, after the merge.",
+      "properties": {
+        "posted": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "escalated": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "backlog": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      }
+    },
+    "action_items": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "learning_proposal": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Path to the proposal keryx review learn wrote. Proposed, never applied \u2014 applying is the caller's step."
+    },
+    "needs_context": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "summary": {
+      "type": "string"
+    },
+    "screened": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Comments passed through `keryx security check-input`. REQUIRED: absent and 0 are different claims. Whether the screen ran at all is `screen_status`, not this \u2014 a fallback run reports `screened: 0` with `screen_status: unavailable`, and that pairing is enforced."
+    },
+    "excluded_for_injection": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Comment ids carrying a prompt-injection finding. They produce no plan item and skip Steps 6 and 7; they are still answered in Step 10."
+    },
+    "screen_status": {
+      "type": "string",
+      "enum": [
+        "ran",
+        "unavailable"
+      ],
+      "description": "Whether the injection screen ran at all. REQUIRED, because `screened: 0` is ambiguous on its own: the documented fallback path \u2014 keryx CLI unavailable \u2014 screens nothing and would otherwise emit exactly what a run that screened and found nothing emits. `unavailable` obliges the report to carry the line saying so."
+    }
+  },
+  "if": {
+    "required": [
+      "mode"
+    ],
+    "properties": {
+      "mode": {
+        "const": "fix"
+      }
+    }
+  },
+  "then": {
+    "required": [
+      "fix"
+    ],
+    "properties": {
+      "fix": {
+        "type": "object"
+      }
+    }
+  },
+  "else": {
+    "properties": {
+      "fix": {
+        "type": "null"
+      },
+      "replies": {
+        "type": "null"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": [
+          "screen_status"
+        ],
+        "properties": {
+          "screen_status": {
+            "const": "unavailable"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "screened": {
+            "const": 0
+          },
+          "excluded_for_injection": {
+            "maxItems": 0
+          }
+        }
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/skills/review/review-testing-practices/SKILL.md

@@ -6,11 +6,13 @@ description: |
   against repository-local testing conventions: co-location, network mocking,
   MSW-style boundary mocks, behaviour assertions, deterministic waits,
   smoke/full split, locator priority, and screenshot-test discipline.
+  Runs a bounded mutation pass over the gates the diff added, so a suite that
+  cannot fail is found by executing it rather than by reading it.
   Dispatched by review-orchestrator for --testing-practices,
   --project-conventions, --all, or changed test/e2e/story files.
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "1.1.0"
   category: "review"
 license: "MIT"
 ---
@@ -36,6 +38,64 @@ If the repository has local test documentation, cite the relevant convention in
 
 ---
 
+## The mutation pass — run this before you read anything
+
+Reading a suite tells you whether it is *well written*. It does not tell you
+whether it can **fail**. Those are different questions, and the second one is the
+one this reviewer exists to answer.
+
+So: before the checklist, for every guard, filter, conditional or branch the diff
+**added or changed**, delete it, run the nearest suite, record the result, revert.
+
+```
+for each gate G added or changed in scope A:
+    delete G  ->  run the nearest suite  ->  record red/green  ->  revert
+```
+
+**A gate whose deletion leaves the suite green is a finding**, however correct the
+gate itself is. State it as: *this gate is unpinned; no fixture builds the input
+that separates it from the condition beside it.* It is mandatory when the gate was
+added in answer to an earlier round — that is where a regression costs most and
+where coverage is most often assumed rather than written.
+
+Publish the whole table, survivors and casualties both. The reds are what makes
+the greens mean something; a table with only survivors reads as cherry-picking.
+
+| mutation | result |
+|---|---|
+| delete the `(half.weight ?? 0) > 0` filter | **18/18 green** |
+| `controlsScore` -> `report.score` | 2 fail |
+| drop `Math.min(100, …)` | 1 fail |
+
+### Why this is your job and not the verifier's
+
+`review-verifier` also executes — but it is **delete-only**: it confirms or refutes
+findings that already exist. A surviving mutation is not a verdict on a finding,
+it *is* the finding, and nothing downstream of you can produce one. If you skip
+this pass the class is unreachable for the whole round.
+
+### Bounds
+
+- Mutate only gates inside **scope A**, one at a time, reverting each before the
+  next. Never leave a mutation in the tree.
+- Run the **nearest** suite, not the full one. This is not a `test:mutation`
+  sweep — those are slow, opt-in, and answer a different question.
+- Cap it: the gates the diff added, plus any gate a previous round asked for. If
+  that set is larger than your budget, take the previous-round gates first and say
+  in your summary how many you did not reach. A stated cap is a result; silence
+  reads as a clean sweep.
+- If you cannot run the suite at all, say so and skip the pass. Do **not** report
+  a mutation you did not run — a predicted result is `info` at best, and this
+  reviewer has no use for one.
+
+### This does not replace reading the tests
+
+Assertion duplication and mutation survival are independent: a suite can be free
+of duplication, correctly tiered, properly mocked — and still pin nothing. Run the
+pass, then work the checklist.
+
+---
+
 ## Checklist
 
 ### Test Location and Tiers
@@ -65,6 +125,39 @@ If the repository has local test documentation, cite the relevant convention in
 - Store-internal timing and concurrency can be unit-tested with lower-level mocks when that is
   the clean seam.
 
+### Fixture Shape Against the Producer
+
+- For every fixture whose name or comment claims a scenario — `drift-only`, `legacy
+  report`, `never run` — find the **producer** (the backend class, the builder, the
+  API contract) and compare **every** field, not only the one the test pins.
+- A fixture that calls itself X while carrying the shape of Y covers Y, leaves X
+  untested, and reads to the next author as coverage of X. That is worse than no
+  fixture: it is coverage that lies.
+- Cheapest tell: the fixture sets one field to the scenario's value and inherits
+  the rest from a default builder written for a different scenario.
+- Name the field that disagrees and the producer line that settles it. If the
+  producer lives in another repository, pin the SHA you read it at. If you cannot
+  read it, the finding is `info` and says what would settle it.
+- A value the producer **cannot emit** (a score of 40 where the backend rounds to
+  tens, two weights summing to 200) is the same class: the test pins a state that
+  does not exist, so it cannot catch the state that does.
+
+### Branch Under Test
+
+- When the code under test chooses between sources — a preferred one and a
+  fallback — establish which branch the fixture actually drives.
+- A comment of the form *"this copy is the authoritative one, the other is a
+  fallback"* is a direct instruction that the test must go through the preferred
+  branch. Assertions that all ride the fallback while the preferred source is
+  authoritative leave the suite green in exactly the failure the comment warns
+  about.
+- Look for the preference in **the code under test, not in the test**. The test
+  cannot tell you which branch it takes; the selector can.
+- Same shape, one level up: a test that asserts only falsy state — "not open",
+  "not present", "no toast" — passes trivially when the code path never ran. Each
+  such test needs one positive artifact proving the path was entered before the
+  negative assertions mean anything.
+
 ### Browser and E2E Determinism
 
 - Tests create their own artifacts with unique names and assert on those artifacts.
@@ -158,9 +251,26 @@ conditions land under that rubric.
 |---|---|---|
 | A test that passes while the behaviour it names is broken | `blocker` | The acceptance criterion is unimplemented — the test only claims otherwise |
 | Real-network leak; shared-data mutation across tests; fixed sleeps; asserting on a backend race | `major` | Named trigger (the run) and named outcome (flake or a false pass) |
+| A gate the diff added survives deletion with the suite green | `minor` | The code is correct; the cost is that the next edit to it is unprotected |
+| A fixture whose shape contradicts the scenario it names, or pins a value the producer cannot emit | `minor` | Same — plus the next author reads it as coverage it does not provide |
+| Assertions ride the fallback branch while the code names another authoritative | `minor` | Same |
 | Substrate choice, smoke tagging, locator priority, co-location | `minor` | The suite is correct; the cost is to whoever maintains it |
 | A convention preference with no effect on determinism or signal | `info` | Shared laws 1 and 2 |
 
 A flaky test is `major`, not `blocker`: it wastes time, but it does not ship a
 defect. A test that cannot fail does — which is why it is the one `blocker` here.
 
+The three mutation-pass rows sit at `minor` deliberately, and the reasoning is
+the canonical rubric rather than modesty: a coverage gap names no runtime trigger
+and no user-visible outcome, so it cannot be `major` under the boundary test. What
+makes them worth reporting is not severity but **evidence class** — each one is a
+command that ran, which is the rarest thing in a review and the only kind of
+finding a later round cannot argue away. Report them with the mutation and its
+result, and they survive adjudication intact. Report them as "coverage looks
+thin" and they are correctly discarded.
+
+The moment a surviving mutation is accompanied by a **reachable input that makes
+the unpinned code do the wrong thing**, that is a separate finding at the severity
+its own outcome earns — usually `major`. The coverage gap and the defect are two
+findings, not one, and conflating them loses whichever the adjudicator disbelieves.
+

package/src/gdskills/bundled/skills/review/review-verifier/SKILL.md

@@ -17,7 +17,7 @@ triggers:
   - "verification pass"
 metadata:
   author: "MrCipherSmith"
-  version: "1.0.0"
+  version: "1.1.0"
   category: "review"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
@@ -130,6 +130,30 @@ A finding is `confirmed` when the procedure **reproduced the defect**, and
 command you ran would not have failed either way, you have not verified anything —
 use `unverifiable` and say what you ran.
 
+#### `refuted` by unreachability is not the end of the thread
+
+There is one refutation shape that closes a finding and leaves a question standing:
+the input the finding needs is **unreachable given the current behaviour of a
+producer you do not own** — another repository, a service, a generated client.
+
+The harm claim is genuinely dead and `refuted` is the correct verdict. But an
+invariant held by another repo's code plus a comment on ours is exactly what breaks
+silently when the contract moves, and the question the refutation raises is a
+different one:
+
+> *Does any test build the shape that was in question?*
+
+Record that successor question in your **prose summary**, naming the producer and
+the SHA your check relied on. It is prose, never a claim — you delete, you do not
+add — and the orchestrator picks it up for the next round or routes it to
+`review-testing-practices`.
+
+The failure this exists to stop is recorded: a reviewer asked "is this broken?",
+a verifier correctly answered "no, the backend never emits that", and the thread
+ended. The shape was untested, stayed untested, and the coverage gap was found by a
+different reviewer two rounds later. *Is it broken* and *is it pinned* are two
+questions; refuting the first says nothing about the second.
+
 ### 2. `site-check` — do the named sites exist?
 
 A `blocker` or `major` carries `class_scope.sites`: every location holding the