@mrciphersmith/keryx 0.2.75 → 0.2.77

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.opencode.md

@@ -534,10 +534,8 @@ second copy of a schema is how that happens.
 9. **DO** verify your work before reporting.
 10. **DO** make `STATUS: <TOKEN>` the first line of your final message, and put no
     JSON in the response body. The full JSON result is the file Phase 6.1 writes
-    and records. (This rule used to say the opposite — "return the JSON result
-    object as your final message" — which contradicted 6.2, `## Reporting
-    Results`, and `parseChildResult`, the production function that throws on any
-    first line that is not a canonical STATUS token.)
+    and records. `parseChildResult` throws on any first line that is not a
+    canonical STATUS token.
 
 ---
 

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.zed.md

@@ -534,10 +534,8 @@ second copy of a schema is how that happens.
 9. **DO** verify your work before reporting.
 10. **DO** make `STATUS: <TOKEN>` the first line of your final message, and put no
     JSON in the response body. The full JSON result is the file Phase 6.1 writes
-    and records. (This rule used to say the opposite — "return the JSON result
-    object as your final message" — which contradicted 6.2, `## Reporting
-    Results`, and `parseChildResult`, the production function that throws on any
-    first line that is not a canonical STATUS token.)
+    and records. `parseChildResult` throws on any first line that is not a
+    canonical STATUS token.
 
 ---
 

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -3,13 +3,17 @@ name: autodoc-orchestrator
 description: >
   Autonomous reverse-engineering documentation pipeline — scans an existing codebase
   and produces comprehensive developer documentation without user involvement after initial setup.
-  Use when: "autodoc", "generate docs for my project", "document this codebase",
-  "reverse engineer documentation", "create project documentation from code",
-  "сгенерируй документацию проекта", "задокументируй кодовую базу",
-  "автодок", "autodoc".
-  Trigger on: user provides a repo path, asks to document existing code, wants
-  onboarding docs, API reference, or architecture overview generated automatically.
+  Use when the user provides a repo path, asks to document existing code, or wants
+  onboarding docs, an API reference, or an architecture overview generated automatically.
   NOT for: writing new PRDs or planning new features (use gproject-orchestrator).
+triggers:
+  - "autodoc"
+  - "автодок"
+  - "document this codebase"
+  - "generate docs for my project"
+  - "reverse engineer documentation"
+  - "задокументируй кодовую базу"
+  - "сгенерируй документацию проекта"
 metadata:
   version: 1.0.0
 ---

package/src/gdskills/bundled/skills/planning/interview/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: interview
-description: "Use before implementation, design, or migration when requirements are unclear and targeted clarifying questions are needed to gather precise context."
+description: "Use to clarify implementation-specific ambiguities AFTER context has already been collected and the goal is known — the questions that sharpen a plan, not the ones that scope the request. This is the `implement`-intent interview job-orchestrator runs at 0.3. To pin down a vague request before any context is gathered, use `interviewer` instead."
 triggers:
   - "/interview"
   - "Interview"

package/src/gdskills/bundled/skills/planning/interview/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: interview
-description: "Use before implementation, design, or migration when requirements are unclear and targeted clarifying questions are needed to gather precise context."
+description: "Use to clarify implementation-specific ambiguities AFTER context has already been collected and the goal is known — the questions that sharpen a plan, not the ones that scope the request. This is the `implement`-intent interview job-orchestrator runs at 0.3. To pin down a vague request before any context is gathered, use `interviewer` instead."
 triggers:
   - "/interview"
   - "Interview"

package/src/gdskills/bundled/skills/planning/interview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: interview
-description: "Use before implementation, design, or migration when requirements are unclear and targeted clarifying questions are needed to gather precise context."
+description: "Use to clarify implementation-specific ambiguities AFTER context has already been collected and the goal is known — the questions that sharpen a plan, not the ones that scope the request. This is the `implement`-intent interview job-orchestrator runs at 0.3. To pin down a vague request before any context is gathered, use `interviewer` instead."
 triggers:
   - "/interview"
   - "Interview"

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.codex.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Use when requirements are ambiguous and precise clarification is needed before proceeding with a complex task."
+description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. For clarifying implementation specifics AFTER context is already collected, use `interview` instead."
 triggers:
   - "Interview me"
   - "Ask me questions"

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.cursor.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Use when requirements are ambiguous and precise clarification is needed before proceeding with a complex task."
+description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. For clarifying implementation specifics AFTER context is already collected, use `interview` instead."
 triggers:
   - "Interview me"
   - "Ask me questions"

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Use when requirements are ambiguous and precise clarification is needed before proceeding with a complex task."
+description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. For clarifying implementation specifics AFTER context is already collected, use `interview` instead."
 triggers:
   - "Interview me"
   - "Ask me questions"

package/src/gdskills/bundled/skills/platform/agent-entrypoint-distiller/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: agent-entrypoint-distiller
 description: Use when the user asks to split, decompose, distill, or refactor a large AGENTS.md or CLAUDE.md into Metaproject rules and project-specific skills while keeping root entrypoints compact.
+triggers:
+  - "distill AGENTS.md"
+  - "split CLAUDE.md"
+  - "разнеси CLAUDE.md по правилам"
 metadata:
   version: "1.0.0"
   category: platform

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

@@ -5,8 +5,7 @@ description: |
   Use when: reviewing code for architectural violations — layer violations, dependency direction
   mistakes, module boundary coupling, SOLID principle breaches, NestJS module/provider structure,
   React MVVM boundary violations, or MobX store layer misplacement.
-  Triggered by: "review architecture", "check architecture", "architectural review",
-  or dispatched by review-orchestrator with --architecture or --backend.
+  Dispatched by review-orchestrator with --architecture or --backend.
   NOT for: style/naming preferences, logic correctness bugs, or security vulnerabilities.
 triggers:
   - "review architecture"

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

@@ -3,8 +3,8 @@ name: review-backend
 model_tier: standard
 description: |
   Use when: reviewing NestJS backend changes — API design, service layer, DTO validation,
-  database patterns, and TypeScript correctness. Covers "review backend", "backend review",
-  "review API", "review NestJS", or dispatched by review-orchestrator with --backend flag.
+  database patterns, and TypeScript correctness. Dispatched by review-orchestrator
+  with the --backend flag.
   NOT for: frontend patterns, MobX, React components, general security vulnerabilities
   (use review-security-code for XSS/injection/auth-bypass), or performance profiling
   (use review-performance).

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

@@ -6,8 +6,7 @@ description: |
   function/class level — meaningful names, small functions, single level of abstraction,
   argument count, error handling, DRY, comment quality, and SOLID (SRP, OCP, LSP, ISP, DIP)
   as applied to individual classes and functions.
-  Triggered by: "review clean code", "check clean code", "Uncle Bob review", "SOLID review",
-  "review --clean-code", or dispatched by review-orchestrator.
+  Dispatched by review-orchestrator.
   NOT for: architectural layer violations (review-architecture), naming convention formatting
   (review-style), logic correctness bugs (review-logic), or security (review-security-code).
 triggers:

package/src/gdskills/bundled/skills/review/review-core-boundaries/SKILL.md

@@ -6,6 +6,10 @@ description: |
   direction, feature-boundary leakage, abstraction stability, composition,
   and blast-radius risks. Dispatched by review-orchestrator for
   --core-boundaries, --project-conventions, --all, or src/core/** changes.
+triggers:
+  - "review core boundaries"
+  - "review --core-boundaries"
+  - dispatched by review-orchestrator
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"

package/src/gdskills/bundled/skills/review/review-flow-graph/SKILL.md

@@ -7,6 +7,10 @@ description: |
   boundaries, selection lifecycle, and large-graph performance. Dispatched by
   review-orchestrator for --flow-graph, --project-conventions, --all, or
   src/core/flow/** / graph abstraction changes.
+triggers:
+  - "review flow graph"
+  - "review --flow-graph"
+  - dispatched by review-orchestrator
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"

package/src/gdskills/bundled/skills/review/review-frontend-conventions/SKILL.md

@@ -8,6 +8,10 @@ description: |
   styling tokens, Storybook expectations, and local tooling rules. Dispatched
   by review-orchestrator for --frontend-conventions, --project-conventions,
   --all, or frontend src/**/*.ts(x) changes when local convention docs exist.
+triggers:
+  - "review frontend conventions"
+  - "review --frontend-conventions"
+  - dispatched by review-orchestrator
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"

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

@@ -6,8 +6,7 @@ description: |
   race conditions, connection pool exhaustion, cache invalidation, missing indexes,
   unbounded queues, missing backpressure, retry storms, idempotency gaps,
   hot-path blocking I/O, and distributed systems anti-patterns.
-  Triggered by: "review highload", "review scalability", "highload review",
-  "review concurrency", "review --highload", or dispatched by review-orchestrator.
+  Dispatched by review-orchestrator.
   NOT for: frontend re-render performance (review-performance), general N+1 queries
   (review-performance), clean code style (review-clean-code), or NestJS module structure
   (review-architecture).

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

@@ -52,7 +52,7 @@ unified report sorted by severity. It does not perform any review logic itself.
 ```
 Review Orchestrator Progress:
 - [ ] Step 0: On a PR target, collect external comments — `keryx review comments collect`
-- [ ] Step 1: Build Review Context Pack (PR metadata, scope, rules, context_doc summary)
+- [ ] Step 1: Build Review Context Pack — PR metadata AND the PR's own description, scope, rules, context_doc summary, accepted memory, and the cross-repo contracts the diff consumes
 - [ ] Step 2: Detect review mode (diff mode vs. path mode)
 - [ ] Step 3: Build the bounded scope with `keryx review scope` — never by hand
 - [ ] Step 3b: On a deep round, compute scope B with `keryx review blast-radius` — never by browsing — and KEEP the `--json` file; `review ingest --blast-radius <file>` is refused without it
@@ -204,9 +204,8 @@ keryx review complete <review-id-or-path>
                       [--finding <id> --disposition <state> --evidence <ref>]...
 ```
 
-**An unrecognised option is refused, not ignored.** A misspelling used to be
-accepted with exit 0, so `review complete --disposition ...` printed
-`status: closed` and wrote nothing at all.
+**An unrecognised option is refused, not ignored** — a misspelled flag exits
+non-zero rather than printing `status: closed` and writing nothing at all.
 
 `--verifications` takes what `review-verifier` returned. `--scope` takes the
 whole `--json` output of `keryx review scope`, so the package records what the
@@ -462,8 +461,8 @@ Required content:
 - Git/PR metadata: repo, branch, base, head, merge-base, PR number/URL when available.
 - Scope summary: changed files grouped by domain, high-risk files, generated/ignored files.
 - Requirements: issue URL, linked task docs, acceptance criteria extracted from `context_doc` when available.
-- **The PR's own description**, fetched not assumed: `gh pr view <n> --json title,body`. See below.
-- **Cross-repo contracts the diff depends on**, each pinned to the SHA you read it at. See below.
+- **The PR's own description**, fetched not assumed: `gh pr view <n> --json title,body`, into the typed `pr.body`. See below.
+- **Cross-repo contracts the diff depends on**, in the typed `cross_repo`: each pinned to the ref you read it at, and each recording whether the producer has merged. See below.
 - Rules: matched repository rules and convention docs by path.
 - **Memory: accepted project memory intersecting the changed paths.** See below — this step is required, not best-effort.
 - Decisions: why each reviewer was selected or skipped.
@@ -487,8 +486,17 @@ and not a pleasantry because unfiled housekeeping is raised again every round an
 fixed in none — three consecutive rounds of "still worth rewriting" is the
 recorded outcome of leaving it out of the findings array.
 
+**The Stage 1 gate files it.** Handing the body to every reviewer is what makes
+the body available; it is not what makes the comparison happen. A rule addressed
+to everyone is owned by no one, and that is the state this finding sat in for
+three rounds. The gate already holds the stated intent and the diff side by side,
+so the comparison belongs there — see `## Stage 1 Gate — Spec Compliance`.
+
 Same class, same severity: an approach that depends on another repository's change
-being deployed first, with no deploy note saying so.
+being deployed first, with no deploy note saying so. Note the boundary — that
+`minor` is about the *description*. When the dependency is real and this change
+can merge first, the blocker is filed against the call site instead; see
+`### A producer that has not merged yet`.
 
 ### Cross-repo contracts are read, not assumed
 
@@ -499,15 +507,21 @@ the SHA:
 ```yaml
 cross_repo:
   - repo: vantage-backend
+    state: merged
     sha: f5219d5d4
+    merge_order: independent
     reason: "DQ report payload: which halves are null vs 0"
+    facts_pinned_round: 1
     facts:
       - "sqlScore/schemaDriftScore stay null when the half is absent"
       - "sqlWeightPercentage/schemaDriftWeightPercentage init to 0.0 and are set unconditionally"
 ```
 
-Put the facts in `review_context` so every reviewer shares one reading, and so a
-later round can tell a contract that moved from a reviewer that misread it.
+Put the facts in `review_context.cross_repo` so every reviewer shares one reading,
+and so a later round can tell a contract that moved from a reviewer that misread
+it. The shape is typed in `review-context.schema.json`: `repo`, `reason`, `facts`
+and `state` are required, `state: merged` requires the `sha`, and `state: open`
+requires the `pr`.
 
 The rule that follows for reviewers, and that belongs in the dispatch prompt:
 
@@ -517,9 +531,49 @@ The rule that follows for reviewers, and that belongs in the dispatch prompt:
 > producer disproves, and a defect missed because the producer's actual default was
 > assumed rather than read.
 
-If the other repository is not available to you, say so in `cross_repo` and leave
-the dependent findings at `info`. An unavailable producer is a result. Assuming
-one is not.
+If the other repository is not available to you, record it as
+`state: unavailable` in `cross_repo` and leave the dependent findings at `info`.
+An unavailable producer is a result. Assuming one is not.
+
+A finding whose evidence lives in the producer sets `repo` on the finding itself.
+`file` and `line` alone name a path in the repository under review, so without
+`repo` a cross-repo claim cannot say where its evidence is — and the `info` rule
+above then rests on nothing a later round can check.
+
+### A producer that has not merged yet
+
+`state: merged` is the easy case: the contract is on the producer's base branch,
+you pin the SHA, and it stays where you pinned it. A **parallel pull request** —
+the backend change your change was written against, still open — is a different
+object, and pinning it the same way is wrong in three separate ways.
+
+**Pin the pull request, not just the commit.** An open branch gets rebased and
+squashed. A SHA read from it today names a commit that will not exist after the
+merge, so `state: open` requires `pr` and the SHA becomes a note about when you
+read it rather than an address a later reader can follow.
+
+**Merge order is a `blocker`, not a note.** A missing deploy note in the PR body
+is `minor` — that is a documentation finding and it stays where it is. The
+operational case is not that one: when an entry is `state: open` with
+`merge_order: producer_first`, and this change can merge without the producer,
+**production breaks the moment it does**. That is a `blocker` under the existing
+enumeration, not a new shape — the consumer calls what is not there, or reads a
+default the producer has not changed yet, which is shape 1 or shape 2 in
+`### \`blocker\` — merge-blocking, and nothing else`. File it against the consuming
+call site rather than the description, and write the fix as what it is: a merge
+gate, a flag, or a fallback, never an edit to a diff that may be perfectly
+correct. Scope it exactly — both facts have to be recorded, an open producer AND
+a producer-first order, and no gate already holding the merge. A
+`merge_order: unknown` is a question to resolve, not a blocker to file.
+
+**Re-read an open producer every round.** `facts` pinned in round 1 are a
+statement about a branch that is still being written; by round 3 the contract may
+have changed under a finding that still cites it. On each round, re-read every
+entry with `state: open` and set `revalidated_round`. An entry whose
+`revalidated_round` is behind the current round has not been checked this round,
+and findings resting on it drop to `info` until it is. This is the same discipline
+`prior_findings` already imposes on the local diff, applied to the one input that
+is most likely to have moved.
 
 ### Memory (required)
 
@@ -624,16 +678,12 @@ A **fix round** is any review of work produced to answer earlier findings. Set
 `is_fix_round: true` on every reviewer input, and populate `prior_findings` with
 the earlier findings and the disposition the fix claimed for each.
 
-**Nothing refuses a dispatch that omits them, and this file used to say
-otherwise.** `reviewer-input.schema.json` states the rule and no production
-TypeScript loads that schema; reviewer dispatch is an action the host agent
-takes, not a `keryx` invocation, so there is no point at which a malformed
-dispatch could be rejected. `reviewer-input` is also absent from the `CONTRACTS`
-registry (`src/gdskills/contracts.ts`), so `keryx skills contracts validate`
-cannot be pointed at it either. The sentence that stood here until flow 209 told
-you the schema would reject a dispatch without `prior_findings`; it asserted an
-enforcement that has never existed, which is the same class of claim this whole
-package was written to delete.
+**Nothing refuses a dispatch that omits them.** `reviewer-input.schema.json`
+states the rule and no production TypeScript loads that schema; reviewer
+dispatch is an action the host agent takes, not a `keryx` invocation, so there
+is no point at which a malformed dispatch could be rejected. `reviewer-input` is
+also absent from the `CONTRACTS` registry (`src/gdskills/contracts.ts`), so
+`keryx skills contracts validate` cannot be pointed at it either.
 
 So this is a requirement on you, unenforced, and the only evidence it was met is
 the `prior_findings` array the reviewer actually receives. A reviewer that cannot
@@ -1117,7 +1167,8 @@ local frontend conventions reviewer.
 
 ## Stage 1 Gate — Spec Compliance
 
-**Run this FIRST, before dispatching quality reviewers, when an `issue_url` or task doc is provided.**
+**Run this FIRST, before dispatching quality reviewers, whenever the change has a
+stated intent — an `issue_url`, a task doc, or a PR body.**
 
 1. Fetch issue or task requirements.
 2. Map changed files and functions to acceptance criteria.
@@ -1125,6 +1176,27 @@ local frontend conventions reviewer.
 4. If there are unimplemented criteria: emit them as `blocker` findings in the final report and note them in `## Blockers`.
 5. Continue dispatching the remaining reviewers regardless (spec gaps + quality issues both belong in the report).
 
+### With no issue and no task doc, the PR body is the spec
+
+A pull request with nothing linked is the common case, not the exception, and the
+gate used to skip entirely on it — which meant the only written statement of what
+the change was for went unchecked precisely when it was the only one there. When
+`issue_url` and `context_doc` are both absent, read `pr.body` as the spec and run
+steps 2-4 against it. Nothing at all to read — no issue, no task doc, an empty
+body — is itself the finding: `minor`, that the change states no intent.
+
+### This gate owns the description-vs-diff comparison
+
+The `minor` for a description that promises an approach the diff does not take
+(see the Context Pack) is **filed here**. It was previously stated as a rule for
+"every reviewer" and owned by none, which is how it stayed a remark instead of a
+finding across three rounds. A domain reviewer reviews its domain; the one step
+that already holds intent and diff side by side is this one.
+
+Run it on every round, not only the first. The drift the finding catches is
+created BY the rounds: the code moves to answer findings, the body does not, and
+whoever reads the merge commit a year later reads the body.
+
 ---
 
 ## Dispatching Reviewers
@@ -1328,6 +1400,18 @@ Everything else is at most `major`. "This will definitely cause problems later"
 is not one of the four. Neither is "this violates the architecture", "this fails
 the linter", or "this is how the last outage started".
 
+**An unshipped dependency is shape 1 or shape 2, and the list stays closed.**
+When a producer is recorded `state: open` with `merge_order: producer_first` and
+nothing stops this change merging first, ask the enumeration's own question —
+what happens at runtime. The consumer calls what is not there (shape 1) or reads
+the default the producer has not changed yet (shape 2). That is why it is a
+`blocker` without a fifth shape being invented for it. Two things follow from
+its being an ordering fault rather than a coding one: file it against the
+consuming call site, and say in the fix that the remedy is a merge gate, a flag,
+or a fallback — never a change to the diff, which may be entirely correct. A
+missing deploy note with no recorded producer state behind it is not this; that
+is the `minor` in the Context Pack. See `### A producer that has not merged yet`.
+
 ### `major` / `minor` / `info` — the boundary test
 
 Ask one question, and ask it of the **finding**, not of the code:
@@ -1459,6 +1543,7 @@ All findings from all sub-reviewers must be normalized to this format before con
 
 - **Severity**: blocker | major | minor | info
 - **File**: path/to/file.ts:line
+- **Repo**: producer repository — only when the evidence is not in the repository under review
 - **Problem**: what is wrong
 - **Why it matters**: impact on correctness / safety / maintainability / UX
 - **Fix**: concrete suggestion

package/src/gdskills/bundled/skills/review/review-orchestrator/review-context.schema.json

@@ -23,6 +23,58 @@
         "object",
         "null"
       ],
+      "description": "The pull request under review, when there is one. `body` is the author's own statement of what the change does, and it is checkable against the diff — it is typed here rather than left to convention because the Context Pack prose told reviewers to read `pr.body` while the schema declared no such field, so nothing carried it and nothing could tell a body that was never fetched from one that was empty.",
+      "properties": {
+        "number": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "body": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Fetched, not assumed: `gh pr view <n> --json title,body`. Null means the fetch did not happen or returned nothing; an empty string means the author wrote no description, which is a different fact and a reportable one."
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "open",
+            "merged",
+            "closed",
+            null
+          ]
+        },
+        "base": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "head": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
       "additionalProperties": true
     },
     "scope": {
@@ -71,6 +123,129 @@
         "type": "string"
       }
     },
+    "cross_repo": {
+      "type": "array",
+      "description": "Contracts owned by another service that this diff consumes — a payload shape, a status enum, a timeout, a permission, a default. Each entry is one reading of the producer, shared by every reviewer, so that a later round can tell a contract that moved from a reviewer that misread it. An entry is a RECORD OF READING: an unavailable producer is a result and belongs here as `state: unavailable`, whereas an assumed one belongs nowhere.",
+      "items": {
+        "type": "object",
+        "required": [
+          "repo",
+          "reason",
+          "facts",
+          "state"
+        ],
+        "properties": {
+          "repo": {
+            "type": "string",
+            "minLength": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What this diff needs from the producer, in one line."
+          },
+          "facts": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            },
+            "description": "What the producer actually says, read at the pinned ref. A claim about another service's behaviour with no `file:line` behind it at a pinned ref is `info`, not `major`, however confident — both failure modes are recorded: a finding the producer disproves, and a defect missed because the producer's real default was assumed rather than read."
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "merged",
+              "open",
+              "unavailable"
+            ],
+            "description": "Where the contract lives right now. `merged` is on the producer's own base branch and is pinned by `sha`. `open` is a parallel pull request that has not landed: its branch will be rebased or squashed, so a sha pinned today names a commit that will not exist after the merge, and the contract itself can still change. `unavailable` means the producer could not be read."
+          },
+          "sha": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The commit the facts were read at. Required when `state` is `merged`."
+          },
+          "pr": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The producer's pull request, when the contract is not merged yet."
+          },
+          "branch": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "merge_order": {
+            "type": "string",
+            "enum": [
+              "producer_first",
+              "consumer_first",
+              "independent",
+              "unknown"
+            ],
+            "default": "unknown",
+            "description": "Which side has to ship first for production to stay correct. `producer_first` on a `state: open` entry is the case where merging THIS change first breaks production, and it is a blocker rather than the `minor` filed for a missing deploy note."
+          },
+          "facts_pinned_round": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "The review round the facts were read in."
+          },
+          "revalidated_round": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "The last round the producer was re-read. An entry with `state: open` that was pinned in round 1 and never revalidated is stale by round 3: a parallel pull request is precisely the thing that moves between rounds."
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "state": {
+                  "const": "merged"
+                }
+              },
+              "required": [
+                "state"
+              ]
+            },
+            "then": {
+              "required": [
+                "sha"
+              ]
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "state": {
+                  "const": "open"
+                }
+              },
+              "required": [
+                "state"
+              ]
+            },
+            "then": {
+              "required": [
+                "pr"
+              ]
+            }
+          }
+        ],
+        "additionalProperties": true
+      }
+    },
     "memory": {
       "type": "object",
       "required": [

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-finding.schema.json

@@ -60,6 +60,13 @@
               "info"
             ]
           },
+          "repo": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Which repository `file` and `line` are in. Null, the default, means the repository under review. A cross-repo claim names the producer here and pins the ref it was read at in `evidence`; without this field a finding about another service's behaviour could not say where its evidence lived, so the rule that such a claim is `info` unless it has a `file:line` at a pinned ref could not be checked by anything but the reviewer's word. Kept identical to src/gdskills/contracts/review-finding.schema.json, which is stricter (additionalProperties: false) and would reject a finding carrying `repo` if the property were declared only here."
+          },
           "file": {
             "type": [
               "string",

package/src/gdskills/bundled/skills/review/review-pr-feedback/SKILL.md

@@ -4,9 +4,8 @@ model_tier: standard
 description: |
   Use when: a developer has received PR review comments and wants to understand them,
   check whether they are still true of the code, act on them, or extract patterns
-  from them. Covers "analyze PR comments", "review PR feedback", "what did reviewers
-  say", "parse PR #N", "explain PR comments", and — with `--fix` — validating every
-  comment, planning the fix, driving it to a merged state and answering each reviewer.
+  from them. With `--fix`, also validates every comment, plans the fix, drives it to
+  a merged state and answers each reviewer.
   NOT for: reviewing code directly — this skill reads human or bot PR feedback and
   makes it actionable. To review code, use the domain review skills.
 triggers: